Please Help

RudeDatabase™ Open Source C++ Database Library

Version 4.1.0

DETAIL:  FIELD | CONSTR | METHOD

Back to Introduction

Database

Class rude::Database


Constructor Summary
protected  Database( const char* contextName )
          Database objects cannot be instantiated directly - instead, call instance() to obtain a reference to the object.
  virtual ~Database()
          
 
Method Summary
 static void addContext( const char* contextname, const char* database, const char* username, const char* password, const char* server, int port )
          Specifies a database, username, password, server and port that will be identified by contextname.
 const char* column( int index )
          Returns the value located at the specified column within the current row set
 static char* escape( const char* string, int length )
          Escapes illegal characters within a string
 bool executeQuery( const char* query )
          Sends queries that do not return a result (UPDATE, DELETE, CREATE, INSERT, ALTER, etc...)
 static void finish()
          Closes all open database connections
 bool freeResult()
          Frees resources consumed by a query result set
 const char* getError()
          Returns the last known error
 int insertQuery( const char* query )
          Sends an INSERT query and returns the insert id
 static Database* instance( const char* contextname )
          Returns the singleton database object for a given context
 bool nextRow()
          Selects the next row from query result set
 const char* singleValueQuery( const char* query )
          Send a query that expects a single value result
 const char* stat()
          Returns MYSQL server status information
 bool storeResultQuery( const char* query )
          Sends a query that expects a result set - obtains results from server all at once (time friendly)
 bool useResultQuery( const char* query )
          Sends a query that expects a result set - obtains results from server one row at a time (memory / network friendly)
 

Constructor Detail

Database

protected Database( const char* contextName );
Database objects cannot be instantiated directly - instead, call instance() to obtain a reference to the object.
This component uses the Singleton design pattern to ensure global accessability and improve performance.
This architecture allows multiple parts of your program to access a particular database without
having to worry about connecting or disconnecting to/from the database. If every section of your program
needed to use a database and was responsible for connecting/disconnecting, then multiple connections
would be opened and closed - consuming both resources and time. Our architecture ensures that a connection
is established once - and then only if necessary - and can be shared throughout the program. Multiple contexts
allow multiple connections to different databases or database accounts simultaneously.

~Database

public virtual ~Database();



Method Detail

addContext

public static void addContext( const char* contextname, const char* database, const char* username, const char* password, const char* server, int port );
Specifies a database, username, password, server and port that will be identified by contextname.
The context name can be anything and is simply used as an identifier to the context.
After a context is added, the database represented by the context name can be obtained by
calling the Database::instance(contextname) method.
Any number of contexts can be added. Each context should have a unique contextname.

column

public const char* column( int index );
Returns the value located at the specified column within the current row set
first index is 0.
will return NULL when out of range.

Example

if(database->storeResultQuery("SELECT fname, lname, address, age from tbl_contacts"))
{
while(database->nextRow())
{
const char *first_name = database->column(0);
const char *last_name = database->column(1);
const char *address = database->column(2);

// convert the age to integer
//
int age = atoi( database->column(3) );

// do stuff with data.....
}
database->freeResult();
}
else
{
std::cout << database->getError() << "\n";
}


escape

public static char* escape( const char* string, int length );
Escapes illegal characters within a string
This ensures that string or binary data won't mess up your queries.
You should escape all string data that can possibly be tainted (eg. you are not sure what is in it).
The caller (you) is responsible for deleting the resulting string.

Note: To avoid memory leaks, you MUST delete the resulting string.
As such, the following sequence should always be followed when using this method:

// 1. Obtain safe strings ( as a static method, it can be called through an object or directly from the class )
//
const char *safe_string = database->escape( unsafe_string , strlen(unsafe_string) );
const char *safe_string2 = rude::Database::escape( another_string, strlen(another_string) );

// 2. ... use the safe strings

// 3. Delete the safe strings
//
delete [] safe_string
delete [] safe_string2

Example:

// Obtain database object
//
rude::Database *database = rude::Database::instance("stock");

const char *catname="A very ''' Awkward ===== Category Name !!'' \"\"\" ****** Indeed!!";

// Escape illegal characters in the new category name
//
char *safe_name = database->escape( catname, strlen(catname));

// Build the SQL statement
// string / character data (whether escaped or not) should be surrounded by single quotes.
//
std::string sqlstatement = "INSERT INTO tbl_category SET name='";
sqlstatement += safe_name;
sqlstatement += "'";

// REMEMBER to delete the escaped string
//
delete [] safe_name;

// Perform the INSERT
//
int newid = database->insertQuery(sqlstatement.c_str());



executeQuery

public bool executeQuery( const char* query );
Sends queries that do not return a result (UPDATE, DELETE, CREATE, INSERT, ALTER, etc...)
Returns true if successful, false otherwise.
NOTE: Use insertQuery() for INSERT's when you want to know the resulting insert-id.

Example:

if( db_database->executeQuery( "DELETE FROM tbl_color WHERE color='blue'" ) )
{
std::cout << "Deleted the color blue"\n";
}
else
{
std::cout << db_database->getError() << "\n";
}


finish

public static void finish();
Closes all open database connections
You can safely call this even if no connections were open and no instances were accessed.
We recommend that this method be called at the end of your main() method in any application that
may use the database object.

freeResult

public bool freeResult();
Frees resources consumed by a query result set
For every call to useResultQuery() or storeResultQuery() in your application,
there should be an accompanying freeResult() call as well.

getError

public const char* getError();
Returns the last known error
Example


std::cout << database->getError() << "\n";


insertQuery

public int insertQuery( const char* query );
Sends an INSERT query and returns the insert id
This is only applicable for tables with an AUTO_INCREMENT primary key.
For tables without an AUTO_INCREMENT primary key, use executeQuery() instead.
Returns 0 if an error occurs.

Example:

if( int insertid = db_database->insertQuery( "INSERT INTO tbl_color SET color='blue'" ) )
{
std::cout << "Inserted a color with id of " << y << "\n";
}
else
{
std::cout << db_database->getError() << "\n";
}


instance

public static Database* instance( const char* contextname );
Returns the singleton database object for a given context
Example:

rude::Database *database = rude::Database::instance("context1");
// use the database object...


nextRow

public bool nextRow();
Selects the next row from query result set
Returns true if the next row is selected
Returns false if there are no more rows.
Must be called to get the first row.

Example

if(database->storeResultQuery("SELECT category_name tbl_categories"))
{
if(database->nextRow())
{
// We got some data back

std::cout << "Current Categories:\n";
do
{
std::cout << database->column(0) << "\n";
}
while(database->netxRow())
}
else
{
// The result set was empty
std::cout << "There are no categories at this time\n";
}
database->freeResult();
}
else
{
std::cout << database->getError() << "\n";
}


singleValueQuery

public const char* singleValueQuery( const char* query );
Send a query that expects a single value result
Use this method when you expect a single value to be the result.
Returns c-string (const char *) representation of data if successful
Returns null if a result could not be obtained or an error occurs
Example:

const char *username = db_database->singleValueQuery( "SELECT username form tbl_users where userid=348" );
if(username)
{
std::cout << "Username for givevn ID is " << username << "\n";
}
else
{
std::cout << "Userid 348 does not exist: " << db_database->getError() << "\n";
}


stat

public const char* stat();
Returns MYSQL server status information
Example

std::cout << database->stat() << "\n";


storeResultQuery

public bool storeResultQuery( const char* query );
Sends a query that expects a result set - obtains results from server all at once (time friendly)
This is the faster alternative to calling useResultQuery(),
and is the preferred method when small result sets are expected.
Returns false if an error occurs.
If it returns true, use nextRow() and column() to access the results.
If the first call to nextRow() returns false, then the result set is empty.
After you are done with the results, call freeResult() to free the system resources.
Example

if(database->storeResultQuery("SELECT username, password from tbl_users"))
{
while(database->nextRow())
{
std::string username = database->column(0);
std::string password = database->column(1);
std::cout << "Username: << username << " Password: " << password << "\n";
}
database->freeResult();
}
else
{
std::cout << database->getError() << "\n";
}


useResultQuery

public bool useResultQuery( const char* query );
Sends a query that expects a result set - obtains results from server one row at a time (memory / network friendly)
This uses less memory and network resources than calling useResultQuery(),
and is the preferred method when large result sets are expected
Returns false if an error occurs.
If it returns true, use nextRow() and column() to access the results
If the first call to nextRow() returns false, then the result set is empty.
After you are done with the results, call freeResult() to free the system resources.

Example

if(database->storeResultQuery("SELECT username, password from tbl_users"))
{
while(database->nextRow())
{
std::string username = database->column(0);
std::string password = database->column(1);
std::cout << "Username: << username << " Password: " << password << "\n";
}
database->freeResult();
}
else
{
std::cout << database->getError() << "\n";
}


DETAIL:  FIELD | CONSTR | METHOD Database
Generated on July 30, 2003 at 22:15