MySQL++: mysqlpp::DBDriver Class Reference
mysqlpp::DBDriver Class Reference

Provides a thin abstraction layer over the underlying database client library. More...

`#include <dbdriver.h>`

## Public Types

enum | nr_code { nr_more_results , nr_last_result , nr_error , nr_not_supported }
| Result code returned by next_result() More...

## Public Member Functions

| DBDriver ()
| Create object.
| DBDriver (const DBDriver &other)
| Duplicate an existing driver. More...
virtual | ~DBDriver ()
| Destroy object.
ulonglong | affected_rows ()
| Return the number of rows affected by the last query. More...
std::string | client_version () const
| Get database client library version. More...
bool | connect (const MYSQL &mysql)
| Establish a new connection using the same parameters as an existing connection. More...
virtual bool | connect (const char *host, const char *socket_name, unsigned int port, const char *db, const char *user, const char *password)
| Connect to database server. More...
bool | connected () const
| Return true if we have an active connection to the database server. More...
void | copy (const DBDriver &other)
| Establish a new connection as a copy of an existing one. More...
bool | create_db (const char *db) const
| Ask the database server to create a database. More...
void | data_seek (MYSQL_RES *res, ulonglong offset) const
| Seeks to a particualr row within the result set. More...
void | disconnect ()
| Drop the connection to the database server. More...
bool | drop_db (const std::string &db) const
| Drop a database. More...
bool | enable_ssl (const char *key=0, const char *cert=0, const char *ca=0, const char *capath=0, const char *cipher=0)
| Enable SSL-encrypted connection. More...
const char * | error ()
| Return error message for last MySQL error associated with this connection. More...
int | errnum ()
| Return last MySQL error number associated with this connection. More...
size_t | escape_string (char *to, const char *from, size_t length)
| Return a SQL-escaped version of the given character buffer. More...
size_t | escape_string (std::string *ps, const char *original, size_t length)
| Return a SQL-escaped version of a character buffer. More...
bool | execute (const char *qstr, size_t length)
| Executes the given query string. More...
MYSQL_ROW | fetch_row (MYSQL_RES *res) const
| Returns the next raw C API row structure from the given result set. More...
const unsigned long * | fetch_lengths (MYSQL_RES *res) const
| Returns the lengths of the fields in the current row from a "use" query. More...
MYSQL_FIELD * | fetch_field (MYSQL_RES *res, size_t i=UINT_MAX) const
| Returns information about a particular field in a result set. More...
void | field_seek (MYSQL_RES *res, size_t field) const
| Jumps to the given field within the result set. More...
void | free_result (MYSQL_RES *res) const
| Releases memory used by a result set. More...
st_mysql_options | get_options () const
| Return the connection options object.
std::string | ipc_info ()
| Get information about the IPC connection to the database server. More...
ulonglong | insert_id ()
| Get ID generated for an AUTO_INCREMENT column in the previous INSERT query. More...
bool | kill (unsigned long tid)
| Kill a MySQL server thread. More...
bool | more_results ()
| Returns true if there are unconsumed results from the most recent query. More...
nr_code | next_result ()
| Moves to the next result set from a multi-query. More...
int | num_fields (MYSQL_RES *res) const
| Returns the number of fields in the given result set. More...
ulonglong | num_rows (MYSQL_RES *res) const
| Returns the number of rows in the given result set. More...
bool | ping ()
| "Pings" the MySQL database More...
int | protocol_version ()
| Returns version number of MySQL protocol this connection is using. More...
std::string | query_info ()
| Returns information about the last executed query. More...
bool | refresh (unsigned options)
| Asks the database server to refresh certain internal data structures. More...
bool | result_empty ()
| Returns true if the most recent result set was empty. More...
bool | select_db (const char *db)
| Asks the database server to switch to a different database.
std::string | server_version ()
| Get the database server's version number. More...
bool | set_option (Option *o)
| Sets a connection option. More...
bool | set_option (mysql_option moption, const void *arg=0)
| Set MySQL C API connection option.
bool | set_option (unsigned int option, bool arg)
| Set MySQL C API connection option. More...
bool | set_option_default (Option *o)
| Same as set_option(), except that it won't override a previously-set option.
bool | shutdown ()
| Ask database server to shut down. More...
std::string | server_status ()
| Returns the database server's status. More...
MYSQL_RES * | store_result ()
| Saves the results of the query just execute()d in memory and returns a pointer to the MySQL C API data structure the results are stored in. More...
unsigned long | thread_id ()
| Returns the MySQL server thread ID for this connection. More...
MYSQL_RES * | use_result ()
| Returns a result set from the last-executed query which we can walk through in linear fashion, which doesn't store all result sets in memory. More...

## Static Public Member Functions

static size_t | escape_string_no_conn (char *to, const char *from, size_t length)
| SQL-escapes the given string without reference to the character set of a database server. More...
static size_t | escape_string_no_conn (std::string *ps, const char *original=0, size_t length=0)
| SQL-escapes the given string without reference to the character set of a database server. More...
static bool | thread_aware ()
| Returns true if MySQL++ and the underlying MySQL C API library were both compiled with thread awareness. More...
static void | thread_end ()
| Tells the underlying MySQL C API library that this thread is done using the library. More...
static bool | thread_start ()
| Tells the underlying C API library that the current thread will be using the library's services. More...

## Protected Member Functions

bool | connect_prepare ()
| Does things common to both connect() overloads, before each go and establish the connection in their different ways.
bool | set_option_impl (Option *o)
| Common implementation of set_option(Option*) and the delayed option setting code in connect_prepare()

## Detailed Description

Provides a thin abstraction layer over the underlying database client library.

This class does as little as possible to adapt between its public interface and the interface required by the underlying C API. That is, in fact, its only mission. The high-level interfaces indended for use by MySQL++ users are in Connection, Query, Result, and ResUse, all of which delegate the actual database communication to an object of this type, created by Connection. If you really need access to the low-level database driver, get it via Connection::driver(); don't create DBDriver objects directly.

Currently this is a concrete class for wrapping the MySQL C API. In the future, it may be turned into an abstract base class, with subclasses for different database server types.

## Member Enumeration Documentation

## nr_code

enum mysqlpp::DBDriver::nr_code

Result code returned by next_result()

Enumerator
nr_more_results | success, with more results to come
nr_last_result | success, last result received
nr_error | problem retrieving next result
nr_not_supported | this C API doesn't support "next result"

## Constructor & Destructor Documentation

## DBDriver()

mysqlpp::DBDriver::DBDriver | ( | const DBDriver & | other | ) |

Duplicate an existing driver.

Parameters

  other | existing DBDriver object

This establishes a new database server connection with the same parameters as the other driver's.

References copy().

## Member Function Documentation

## affected_rows()

ulonglong mysqlpp::DBDriver::affected_rows | ( |  | ) |

inline

Return the number of rows affected by the last query.

Wraps `mysql_affected_rows()` in the MySQL C API.

Referenced by mysqlpp::Query::affected_rows().

## client_version()

std::string mysqlpp::DBDriver::client_version | ( |  | ) | const

inline

Get database client library version.

Wraps `mysql_get_client_info()` in the MySQL C API.

Referenced by mysqlpp::Connection::client_version(), and set_option_impl().

## connect() [1/2]

bool mysqlpp::DBDriver::connect | ( | const char * | host,
|  | const char * | socket_name,
|  | unsigned int | port,
|  | const char * | db,
|  | const char * | user,
|  | const char * | password
| ) |  |

virtual

Connect to database server.

If you call this method on an object that is already connected to a database server, the previous connection is dropped and a new connection is established.

References connect_prepare().

## connect() [2/2]

bool mysqlpp::DBDriver::connect | ( | const MYSQL & | mysql | ) |

Establish a new connection using the same parameters as an existing connection.

Parameters

  mysql | existing MySQL C API connection object

References connect_prepare().

Referenced by mysqlpp::Connection::connect(), and copy().

## connected()

bool mysqlpp::DBDriver::connected | ( |  | ) | const

inline

Return true if we have an active connection to the database server.

This does not actually check whether the connection is viable, it just indicates whether there was previously a successful connect() call and no disconnect(). Call ping() to actually test the connection's viability.

Referenced by connect_prepare(), mysqlpp::Connection::connected(), copy(), set_option(), shutdown(), and ~DBDriver().

## copy()

void mysqlpp::DBDriver::copy | ( | const DBDriver & | other | ) |

Establish a new connection as a copy of an existing one.

Parameters

  other | the connection to copy

References connect(), connected(), and disconnect().

Referenced by mysqlpp::Connection::copy(), and DBDriver().

## create_db()

bool mysqlpp::DBDriver::create_db | ( | const char * | db | ) | const

Ask the database server to create a database.

Parameters

  db | name of database to create

Returns
  true if database was created successfully

## data_seek()

void mysqlpp::DBDriver::data_seek | ( | MYSQL_RES * | res,
|  | ulonglong | offset
| ) |  | const

inline

Seeks to a particualr row within the result set.

Wraps mysql_data_seek() in MySQL C API.

## disconnect()

void mysqlpp::DBDriver::disconnect | ( |  | ) |

Drop the connection to the database server.

This method should only be used by MySQL++ library internals. Unless you use the default constructor, this object should always be connected.

Referenced by connect_prepare(), copy(), mysqlpp::Connection::disconnect(), and ~DBDriver().

## drop_db()

bool mysqlpp::DBDriver::drop_db | ( | const std::string & | db | ) | const

Drop a database.

Parameters

  db | name of database to destroy

Returns
  true if database was created successfully

## enable_ssl()

bool mysqlpp::DBDriver::enable_ssl | ( | const char * | key = `0`,
|  | const char * | cert = `0`,
|  | const char * | ca = `0`,
|  | const char * | capath = `0`,
|  | const char * | cipher = `0`
| ) |  |

Enable SSL-encrypted connection.

Parameters

  key | the pathname to the key file
  cert | the pathname to the certificate file
  ca | the pathname to the certificate authority file
  capath | directory that contains trusted SSL CA certificates in pem format.
  cipher | list of allowable ciphers to use

Returns
  False if call fails or the C API library wasn't compiled with SSL support enabled.

Must be called before connection is established.

Wraps `mysql_ssl_set()` in MySQL C API.

## errnum()

int mysqlpp::DBDriver::errnum | ( |  | ) |

inline

Return last MySQL error number associated with this connection.

Wraps `mysql_errno()` in the MySQL C API.

Referenced by mysqlpp::Connection::errnum(), mysqlpp::UseQueryResult::fetch_row(), and mysqlpp::StoreQueryResult::StoreQueryResult().

## error()

const char* mysqlpp::DBDriver::error | ( |  | ) |

inline

Return error message for last MySQL error associated with this connection.

Can return a MySQL++ DBDriver-specific error message if there is one. If not, it simply wraps `mysql_error()` in the MySQL C API.

Referenced by mysqlpp::Connection::error(), mysqlpp::UseQueryResult::fetch_row(), mysqlpp::Connection::set_option(), and mysqlpp::StoreQueryResult::StoreQueryResult().

## escape_string() [1/2]

size_t mysqlpp::DBDriver::escape_string | ( | char * | to,
|  | const char * | from,
|  | size_t | length
| ) |  |

inline

Return a SQL-escaped version of the given character buffer.

Parameters

  to | character buffer to hold escaped version; must point to at least (length * 2 + 1) bytes
  from | pointer to the character buffer to escape
  length | number of characters to escape

Return values

  number | of characters placed in escaped

Wraps `mysql_real_escape_string()` in the MySQL C API.

Proper SQL escaping takes the database's current character set into account, however if a database connection isn't available DBDriver also provides a static version of this same method.

See also
  escape_string_no_conn(char*, const char*, size_t)

Referenced by escape_string(), mysqlpp::Query::escape_string(), and mysqlpp::SQLStream::escape_string().

## escape_string() [2/2]

size_t mysqlpp::DBDriver::escape_string | ( | std::string * | ps,
|  | const char * | original,
|  | size_t | length
| ) |  |

Return a SQL-escaped version of a character buffer.

Parameters

  ps | pointer to C++ string to hold escaped version; if original is 0, also holds the original data to be escaped
  original | if given, pointer to the character buffer to escape instead of contents of *ps
  length | if both this and original are given, number of characters to escape instead of ps->length()

Return values

  number | of characters placed in *ps

This method has three basic operation modes:

- Pass just a pointer to a C++ string containing the original data to escape, plus act as receptacle for escaped version
- Pass a pointer to a C++ string to receive escaped string plus a pointer to a C string to be escaped
- Pass nonzero for all parameters, taking original to be a pointer to an array of char with given length; does not treat null characters as special

There's a degenerate fourth mode, where ps is zero: simply returns 0, because there is nowhere to store the result.

Note that if original is 0, we always ignore the length parameter even if it is nonzero. Length always comes from ps->length() in this case.

ps is a pointer because if it were a reference, the other overload would be impossible to call: the compiler would complain that the two overloads are ambiguous because std::string has a char* conversion ctor. A nice bonus is that pointer syntax makes it clearer that the first parameter is an "out" parameter.

See also
  comments for escape_string(char*, const char*, size_t) for further details.
  escape_string_no_conn(std::string*, const char*, size_t)

References escape_string().

## escape_string_no_conn() [1/2]

static size_t mysqlpp::DBDriver::escape_string_no_conn | ( | char * | to,
|  | const char * | from,
|  | size_t | length
| ) |  |

inline static

SQL-escapes the given string without reference to the character set of a database server.

Wraps `mysql_escape_string()` in the MySQL C API.

See also
  escape_string(char*, const char*, size_t)

Referenced by mysqlpp::Query::escape_string(), mysqlpp::SQLStream::escape_string(), and escape_string_no_conn().

## escape_string_no_conn() [2/2]

size_t mysqlpp::DBDriver::escape_string_no_conn | ( | std::string * | ps,
|  | const char * | original = `0`,
|  | size_t | length = `0`
| ) |  |

static

SQL-escapes the given string without reference to the character set of a database server.

See also
  escape_string(std::string*, const char*, size_t), escape_string_no_conn(char*, const char*, size_t)

References escape_string_no_conn().

## execute()

bool mysqlpp::DBDriver::execute | ( | const char * | qstr,
|  | size_t | length
| ) |  |

inline

Executes the given query string.

Wraps `mysql_real_query()` in the MySQL C API.

Referenced by mysqlpp::Query::exec(), mysqlpp::Query::execute(), shutdown(), mysqlpp::Query::store(), and mysqlpp::Query::use().

## fetch_field()

MYSQL_FIELD* mysqlpp::DBDriver::fetch_field | ( | MYSQL_RES * | res,
|  | size_t | i = `UINT_MAX`
| ) |  | const

inline

Returns information about a particular field in a result set.

Parameters

  res | result set to fetch field information for
  i | field number to fetch information for, if given

If i parameter is given, this call is like a combination of field_seek() followed by fetch_field() without the i parameter, which otherwise just iterates through the set of fields in the given result set.

Wraps `mysql_fetch_field()` and mysql_fetch_field_direct() in MySQL C API. (Which one it uses depends on i parameter.)

Referenced by mysqlpp::ResultBase::ResultBase().

## fetch_lengths()

const unsigned long* mysqlpp::DBDriver::fetch_lengths | ( | MYSQL_RES * | res | ) | const

inline

Returns the lengths of the fields in the current row from a "use" query.

Wraps `mysql_fetch_lengths()` in MySQL C API.

Referenced by mysqlpp::UseQueryResult::fetch_lengths(), and mysqlpp::StoreQueryResult::StoreQueryResult().

## fetch_row()

MYSQL_ROW mysqlpp::DBDriver::fetch_row | ( | MYSQL_RES * | res | ) | const

inline

Returns the next raw C API row structure from the given result set.

This is for "use" query result sets only. "store" queries have all the rows already.

Wraps `mysql_fetch_row()` in MySQL C API.

Referenced by mysqlpp::UseQueryResult::fetch_raw_row(), mysqlpp::UseQueryResult::fetch_row(), and mysqlpp::StoreQueryResult::StoreQueryResult().

## field_seek()

void mysqlpp::DBDriver::field_seek | ( | MYSQL_RES * | res,
|  | size_t | field
| ) |  | const

inline

Jumps to the given field within the result set.

Wraps `mysql_field_seek()` in MySQL C API.

Referenced by mysqlpp::ResultBase::ResultBase().

## free_result()

void mysqlpp::DBDriver::free_result | ( | MYSQL_RES * | res | ) | const

inline

Releases memory used by a result set.

Wraps `mysql_free_result()` in MySQL C API.

Referenced by mysqlpp::StoreQueryResult::StoreQueryResult().

## insert_id()

ulonglong mysqlpp::DBDriver::insert_id | ( |  | ) |

inline

Get ID generated for an AUTO_INCREMENT column in the previous INSERT query.

Return values

  0 | if the previous query did not generate an ID. Use the SQL function LAST_INSERT_ID() if you need the last ID generated by any query, not just the previous one. This applies to stored procedure calls because this function returns the ID generated by the last query, which was a CALL statement, and CALL doesn't generate IDs. You need to use LAST_INSERT_ID() to get the ID in this case.

Referenced by mysqlpp::Query::insert_id().

## ipc_info()

std::string mysqlpp::DBDriver::ipc_info | ( |  | ) |

inline

Get information about the IPC connection to the database server.

String contains info about type of connection (e.g. TCP/IP, named pipe, Unix socket...) and the server hostname.

Wraps `mysql_get_host_info()` in the MySQL C API.

Referenced by mysqlpp::Connection::ipc_info().

## kill()

bool mysqlpp::DBDriver::kill | ( | unsigned long | tid | ) |

inline

Kill a MySQL server thread.

Parameters

  tid | ID of thread to kill

Wraps `mysql_kill()` in the MySQL C API.

See also
  thread_id()

Referenced by mysqlpp::Connection::kill().

## more_results()

bool mysqlpp::DBDriver::more_results | ( |  | ) |

inline

Returns true if there are unconsumed results from the most recent query.

Wraps `mysql_more_results()` in the MySQL C API.

Referenced by mysqlpp::Query::more_results().

## next_result()

nr_code mysqlpp::DBDriver::next_result | ( |  | ) |

inline

Moves to the next result set from a multi-query.

Returns
  A code indicating whether we successfully found another result, there were no more results (but still success) or encountered an error trying to find the next result set.

Wraps `mysql_next_result()` in the MySQL C API, with translation of its return value from magic integers to nr_code enum values.

Referenced by mysqlpp::Query::store_next().

## num_fields()

int mysqlpp::DBDriver::num_fields | ( | MYSQL_RES * | res | ) | const

inline

Returns the number of fields in the given result set.

Wraps `mysql_num_fields()` in MySQL C API.

## num_rows()

ulonglong mysqlpp::DBDriver::num_rows | ( | MYSQL_RES * | res | ) | const

inline

Returns the number of rows in the given result set.

Wraps `mysql_num_rows()` in MySQL C API.

## ping()

bool mysqlpp::DBDriver::ping | ( |  | ) |

inline

"Pings" the MySQL database

This function will try to reconnect to the server if the connection has been dropped. Wraps `mysql_ping()` in the MySQL C API.

Return values

  true | if server is responding, regardless of whether we had to reconnect or not
  false | if either we already know the connection is down and cannot re-establish it, or if the server did not respond to the ping and we could not re-establish the connection.

Referenced by mysqlpp::Connection::ping().

## protocol_version()

int mysqlpp::DBDriver::protocol_version | ( |  | ) |

inline

Returns version number of MySQL protocol this connection is using.

Wraps `mysql_get_proto_info()` in the MySQL C API.

Referenced by mysqlpp::Connection::protocol_version().

## query_info()

string mysqlpp::DBDriver::query_info | ( |  | ) |

Returns information about the last executed query.

Wraps `mysql_info()` in the MySQL C API

Referenced by mysqlpp::Query::info().

## refresh()

bool mysqlpp::DBDriver::refresh | ( | unsigned | options | ) |

inline

Asks the database server to refresh certain internal data structures.

Wraps `mysql_refresh()` in the MySQL C API. There is no corresponding interface for this in higher level MySQL++ classes because it was undocumented until recently, and it's a pretty low-level thing. It's designed for things like MySQL Administrator.

## result_empty()

bool mysqlpp::DBDriver::result_empty | ( |  | ) |

inline

Returns true if the most recent result set was empty.

Wraps `mysql_field_count()` in the MySQL C API, returning true if it returns 0.

Referenced by mysqlpp::Query::result_empty().

## server_status()

std::string mysqlpp::DBDriver::server_status | ( |  | ) |

inline

Returns the database server's status.

String is similar to that returned by the `mysqladmin` `status` command. Among other things, it contains uptime in seconds, and the number of running threads, questions and open tables.

Wraps `mysql_stat()` in the MySQL C API.

Referenced by mysqlpp::Connection::server_status().

## server_version()

std::string mysqlpp::DBDriver::server_version | ( |  | ) |

inline

Get the database server's version number.

Wraps `mysql_get_server_info()` in the MySQL C API.

Referenced by mysqlpp::Connection::server_version().

## set_option() [1/2]

bool mysqlpp::DBDriver::set_option | ( | Option * | o | ) |

Sets a connection option.

This is the database-independent high-level option setting interface that Connection::set_option() calls. There are several private overloads that actually implement the option setting.

See also
  Connection::set_option(Option*) for commentary

References connected(), and set_option_impl().

Referenced by mysqlpp::Connection::set_option().

## set_option() [2/2]

bool mysqlpp::DBDriver::set_option | ( | unsigned int | option,
|  | bool | arg
| ) |  |

Set MySQL C API connection option.

Manipulates the MYSQL.client_flag bit mask. This allows these flags to be treated the same way as any other connection option, even though the C API handles them differently.

## shutdown()

bool mysqlpp::DBDriver::shutdown | ( |  | ) |

Ask database server to shut down.

User must have the "shutdown" privilege.

Wraps `mysql_shutdown()` in the MySQL C API.

References connected(), and execute().

Referenced by mysqlpp::Connection::shutdown().

## store_result()

MYSQL_RES* mysqlpp::DBDriver::store_result | ( |  | ) |

inline

Saves the results of the query just execute()d in memory and returns a pointer to the MySQL C API data structure the results are stored in.

See also
  use_result()

Wraps `mysql_store_result()` in the MySQL C API.

Referenced by mysqlpp::Query::store(), and mysqlpp::Query::store_next().

## thread_aware()

bool mysqlpp::DBDriver::thread_aware | ( |  | ) |

static

Returns true if MySQL++ and the underlying MySQL C API library were both compiled with thread awareness.

This is based in part on a MySQL C API function mysql_thread_safe(). We deliberately don't call this wrapper thread_safe() because it's a misleading name: linking to thread-aware versions of the MySQL++ and C API libraries doesn't automatically make your program "thread-safe". See the chapter on threads in the user manual for more information and guidance.

Referenced by mysqlpp::Connection::thread_aware().

## thread_end()

static void mysqlpp::DBDriver::thread_end | ( |  | ) |

inline static

Tells the underlying MySQL C API library that this thread is done using the library.

This exists because the MySQL C API library allocates some per-thread memory which it doesn't release until you call this.

Referenced by mysqlpp::Connection::thread_end().

## thread_id()

unsigned long mysqlpp::DBDriver::thread_id | ( |  | ) |

inline

Returns the MySQL server thread ID for this connection.

This has nothing to do with threading on the client side. It's a server-side thread ID, to be used with kill().

Referenced by mysqlpp::Connection::thread_id().

## thread_start()

static bool mysqlpp::DBDriver::thread_start | ( |  | ) |

inline static

Tells the underlying C API library that the current thread will be using the library's services.

Return values

  True | if there was no problem

The MySQL++ user manual's chapter on threads details two major strategies for dealing with connections in the face of threads. If you take the simpler path, creating one DBDriver object per thread, it is never necessary to call this function; the underlying C API will call it for you when you establish the first database server connection from that thread. If you use a more complex connection management strategy where it's possible for one thread to establish a connection that another thread uses, you must call this from each thread that can use the database before it creates any MySQL++ objects. If you use a DBDriverPool object, this applies; DBDriverPool isn't smart enough to call this for you, and the MySQL C API won't do it, either.

Referenced by mysqlpp::Connection::thread_start().

## use_result()

MYSQL_RES* mysqlpp::DBDriver::use_result | ( |  | ) |

inline

Returns a result set from the last-executed query which we can walk through in linear fashion, which doesn't store all result sets in memory.

See also
  store_result

Wraps `mysql_use_result()` in the MySQL C API.

Referenced by mysqlpp::Query::use().

The documentation for this class was generated from the following files:

- dbdriver.h
- dbdriver.cpp