mysqlpp::DBDriver Class Reference

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

#include <dbdriver.h>

List of all members.

Public Types
	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"
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.
virtual	~DBDriver ()
	Destroy object.
ulonglong	affected_rows ()
	Return the number of rows affected by the last query.
std::string	client_version () const
	Get database client library version.
bool	connect (const MYSQL &mysql)
	Establish a new connection using the same parameters as an existing connection.
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.
bool	connected () const
	Return true if we have an active connection to the database server.
void	copy (const DBDriver &other)
	Establish a new connection as a copy of an existing one.
bool	create_db (const char *db) const
	Ask the database server to create a database.
void	data_seek (MYSQL_RES *res, ulonglong offset) const
	Seeks to a particualr row within the result set.
void	disconnect ()
	Drop the connection to the database server.
bool	drop_db (const std::string &db) const
	Drop a database.
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.
const char *	error ()
	Return error message for last MySQL error associated with this connection.
int	errnum ()
	Return last MySQL error number associated with this connection.
size_t	escape_string (char *to, const char *from, size_t length)
	SQL-escapes the given string, taking into account the default character set of the database server we're connected to.
bool	execute (const char *qstr, size_t length)
	Executes the given query string.
MYSQL_ROW	fetch_row (MYSQL_RES *res) const
	Returns the next raw C API row structure from the given result set.
const unsigned long *	fetch_lengths (MYSQL_RES *res) const
	Returns the lengths of the fields in the current row from a "use" query.
MYSQL_FIELD *	fetch_field (MYSQL_RES *res, size_t i=UINT_MAX) const
	Returns information about a particular field in a result set.
void	field_seek (MYSQL_RES *res, size_t field) const
	Jumps to the given field within the result set.
void	free_result (MYSQL_RES *res) const
	Releases memory used by a result set.
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.
ulonglong	insert_id ()
	Get ID generated for an AUTO_INCREMENT column in the previous INSERT query.
bool	kill (unsigned long tid)
	Kill a MySQL server thread.
bool	more_results ()
	Returns true if there are unconsumed results from the most recent query.
nr_code	next_result ()
	Moves to the next result set from a multi-query.
int	num_fields (MYSQL_RES *res) const
	Returns the number of fields in the given result set.
ulonglong	num_rows (MYSQL_RES *res) const
	Returns the number of rows in the given result set.
bool	ping ()
	"Pings" the MySQL database
int	protocol_version ()
	Returns version number of MySQL protocol this connection is using.
std::string	query_info ()
	Returns information about the last executed query.
bool	refresh (unsigned options)
	Asks the database server to refresh certain internal data structures.
bool	result_empty ()
	Returns true if the most recent result set was empty.
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.
std::string	set_option (Option *o)
	Sets a connection option.
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.
std::string	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.
std::string	server_status ()
	Returns the database server's status.
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.
unsigned long	thread_id ()
	Returns the MySQL server thread ID for this connection.
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.
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.
static bool	thread_aware ()
	Returns true if MySQL++ and the underlying MySQL C API library were both compiled with thread awareness.
static void	thread_end ()
	Tells the underlying MySQL C API library that this thread is done using the library.
static bool	thread_start ()
	Tells the underlying C API library that the current thread will be using the library's services.

---

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

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

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.

---

Member Function Documentation

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.

std::string mysqlpp::DBDriver::client_version

(

)

const [inline]

Get database client library version.

Wraps mysql_get_client_info() in the MySQL C API.

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.

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

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.

void mysqlpp::DBDriver::copy

(

const DBDriver &

other

)

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

Parameters:

other

the connection to copy

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

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.

void mysqlpp::DBDriver::disconnect

(

)

Drop the connection to the database server.

This method is protected because it should only be used within the library. Unless you use the default constructor, this object should always be connected.

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

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.

int mysqlpp::DBDriver::errnum

(

)

[inline]

Return last MySQL error number associated with this connection.

Wraps mysql_errno() in the MySQL C API.

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.

size_t mysqlpp::DBDriver::escape_string	(	char *	to,
		const char *	from,
		size_t	length
	)			[inline]

SQL-escapes the given string, taking into account the default character set of the database server we're connected to.

Wraps mysql_real_escape_string() in the MySQL C API.

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.

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.

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.)

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.

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.

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.

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.

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.

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.

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()

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.

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.

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.

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.

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.

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.

string mysqlpp::DBDriver::query_info

(

)

Returns information about the last executed query.

Wraps mysql_info() in the MySQL C API

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.

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.

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.

std::string mysqlpp::DBDriver::server_version

(

)

[inline]

Get the database server's version number.

Wraps mysql_get_server_info() in the MySQL C API.

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.

std::string 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

bool mysqlpp::DBDriver::shutdown

(

)

Ask database server to shut down.

User must have the "shutdown" privilege.

Wraps mysql_shutdown() in the MySQL C API.

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.

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.

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.

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().

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.

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.

---

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

• dbdriver.h
• dbdriver.cpp

---