Manages the connection to the database server. More...

#include <connection.h>

Inheritance diagram for mysqlpp::Connection:

[legend]

Collaboration diagram for mysqlpp::Connection:

Public Member Functions
	Connection (bool te=true)
	Create object without connecting to the database server. More...

	Connection (const char db, const char server=0, const char user=0, const char password=0, unsigned int port=0)
	Create object and connect to database server in one step. More...

	Connection (const Connection &other)
	Establish a new connection using the same parameters as an existing connection. More...

virtual	~Connection ()
	Destroy object.

std::string	client_version () const
	Get version of library underpinning the current database driver.

virtual bool	connect (const char db=0, const char server=0, const char user=0, const char password=0, unsigned int port=0)
	Connect to database after object is created. More...

bool	connected () const
	Returns true if connection was established successfully. More...

ulonglong	count_rows (const std::string &table)
	Returns the number of rows in a table. More...

bool	create_db (const std::string &db)
	Ask the database server to create a database. More...

void	disconnect ()
	Drop the connection to the database server.

DBDriver *	driver ()
	Returns a reference to the current database driver.

bool	drop_db (const std::string &db)
	Asks the database server to drop (destroy) a database. More...

int	errnum ()
	Return last error number associated with this connection.

const char *	error () const
	Return error message for last error associated with this connection. More...

std::string	ipc_info () const
	Get information about the IPC connection to the database server. More...

bool	kill (unsigned long tid) const
	Kill a database server thread. More...

	operator private_bool_type () const
	Test whether any error has occurred within the object. More...

Connection &	operator= (const Connection &rhs)
	Copy an existing Connection object's state into this object.

bool	ping ()
	"Pings" the database server More...

int	protocol_version () const
	Returns version number of the protocol the database driver uses to communicate with the server.

Query	query (const char *qstr=0)
	Return a new query object. More...

Query	query (const std::string &qstr)
	Return a new query object. More...

bool	select_db (const std::string &db)
	Change to a different database managed by the database server we are connected to. More...

std::string	server_version () const
	Get the database server's version string.

bool	set_option (Option *o)
	Sets a connection option. More...

bool	shutdown ()
	Ask database server to shut down.

std::string	server_status () const
	Returns information about database server's status.

unsigned long	thread_id ()
	Returns the database server's thread ID for this connection. More...

Public Member Functions inherited from mysqlpp::OptionalExceptions
	OptionalExceptions (bool e=true)
	Default constructor. More...

virtual	~OptionalExceptions ()
	Destroy object.

void	enable_exceptions () const
	Enable exceptions from the object.

void	disable_exceptions () const
	Disable exceptions from the object.

bool	throw_exceptions () const
	Returns true if exceptions are enabled.

Static Public Member Functions
static bool	thread_aware ()
	Returns true if both MySQL++ and database driver we're using were compiled with thread awareness.

static void	thread_end ()
	Tells the underlying database driver that this thread is done using the library.

static bool	thread_start ()
	Tells the underlying database driver that the current thread is now using its services. More...

Protected Member Functions
void	build_error_message (const char *core)
	Build an error message in the standard form used whenever one of the methods can't succeed because we're not connected to the database server.

void	copy (const Connection &other)
	Establish a new connection as a copy of an existing one. More...

bool	parse_ipc_method (const char *server, std::string &host, unsigned int &port, std::string &socket_name)
	Extract elements from the server parameter in formats suitable for passing to DBDriver::connect().

Protected Member Functions inherited from mysqlpp::OptionalExceptions
void	set_exceptions (bool e) const
	Sets the exception state to a particular value. More...

Protected Attributes
std::string	error_message_
	MySQL++ specific error, if any.

Detailed Description

Manages the connection to the database server.

This class is a thick wrapper around DBDriver, adding high-level error handling, utility functions, and abstraction away from underlying C API details.

Constructor & Destructor Documentation

◆ Connection() [1/3]

mysqlpp::Connection::Connection ( bool te = true )

Create object without connecting to the database server.

Parameters

te	if true, exceptions are thrown on errors

◆ Connection() [2/3]

mysqlpp::Connection::Connection	(	const char *	db,
		const char *	server = `0`,
		const char *	user = `0`,
		const char *	password = `0`,
		unsigned int	port = `0`
	)

Create object and connect to database server in one step.

This constructor allows you to most fully specify the options used when connecting to the database server.

Parameters

db	name of database to select upon connection
server	specifies the IPC method and parameters for contacting the server; see below for details
user	user name to log in under, or 0 to use the user name this program is running under
password	password to use when logging in
port	TCP port number database server is listening on, or 0 to use default value; note that you may also give this as part of the `server` parameter

The server parameter can be any of several different forms:

0: Let the database driver decide how to connect; usually some sort of localhost IPC method.
".": On Windows, this means named pipes, if the server supports it
"/some/domain/socket/path": If the passed string doesn't match one of the previous alternatives and we're on a system that supports Unix domain sockets, MySQL++ will test it to see if it names one, and use it if we have permission.
"host.name.or.ip:port": If the previous test fails, or if the system doesn't support Unix domain sockets at all, it assumes the string is some kind of network address, optionally followed by a colon and port. The name can be in dotted quad form, a host name, or a domain name. The port can either be a TCP/IP port number or a symbolic service name. If a port or service name is given here and a nonzero value is passed for the port parameter, the latter takes precedence.

References connect().

◆ Connection() [3/3]

mysqlpp::Connection::Connection ( const Connection & other )

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

Parameters

other existing Connection object

References copy().

Member Function Documentation

◆ connect()

bool mysqlpp::Connection::connect	(	const char *	db = `0`,
		const char *	server = `0`,
		const char *	user = `0`,
		const char *	password = `0`,
		unsigned int	port = `0`
	)

virtual

Connect to database after object is created.

It's better to use the connect-on-create constructor if you can. See its documentation for the meaning of these parameters.

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 mysqlpp::DBDriver::connect(), errnum(), error(), error_message_, parse_ipc_method(), and mysqlpp::OptionalExceptions::throw_exceptions().

Referenced by Connection().

◆ connected()

bool mysqlpp::Connection::connected ( ) const

Returns true if connection was established successfully.

Returns: true if connection was established successfully

References mysqlpp::DBDriver::connected().

Referenced by ping(), select_db(), and shutdown().

◆ copy()

void mysqlpp::Connection::copy ( const Connection & other )

protected

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

Parameters

other the connection to copy

References mysqlpp::DBDriver::copy(), error_message_, mysqlpp::OptionalExceptions::set_exceptions(), and mysqlpp::OptionalExceptions::throw_exceptions().

Referenced by Connection(), and operator=().

◆ count_rows()

ulonglong mysqlpp::Connection::count_rows ( const std::string & table )

Returns the number of rows in a table.

Parameters

table name of table whose rows you want counted

This is syntactic sugar for a SELECT COUNT(*) FROM table SQL query.

References error_message_, mysqlpp::Query::store(), and mysqlpp::OptionalExceptions::throw_exceptions().

◆ create_db()

bool mysqlpp::Connection::create_db ( const std::string & db )

Ask the database server to create a database.

Parameters

db	name of database to create

Returns: true if database was created successfully

References error_message_, mysqlpp::Query::exec(), and mysqlpp::OptionalExceptions::throw_exceptions().

◆ drop_db()

bool mysqlpp::Connection::drop_db ( const std::string & db )

Asks the database server to drop (destroy) a database.

Parameters

db	name of database to destroy

Returns: true if database was dropped successfully

References error_message_, mysqlpp::Query::exec(), and mysqlpp::OptionalExceptions::throw_exceptions().

◆ error()

const char * mysqlpp::Connection::error ( ) const

Return error message for last error associated with this connection.

Returns either a MySQL++-specific error message if one exists, or one from the current database driver otherwise.

References mysqlpp::DBDriver::error(), and error_message_.

Referenced by connect(), mysqlpp::Query::error(), select_db(), and shutdown().

◆ ipc_info()

std::string mysqlpp::Connection::ipc_info ( ) const

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.

References mysqlpp::DBDriver::ipc_info().

◆ kill()

bool mysqlpp::Connection::kill ( unsigned long tid ) const

Kill a database server thread.

Parameters

tid	ID of thread to kill

See also: thread_id()

References error_message_, and mysqlpp::DBDriver::kill().

◆ operator private_bool_type()

mysqlpp::Connection::operator private_bool_type ( ) const

inline

Test whether any error has occurred within the object.

Allows the object to be used in bool context, like this:

Connection conn;
.... use conn
if (conn) {
    ... nothing bad has happened since last successful use
}
else {
    ... some error has occurred
}

Prior to MySQL++ v3, the object was always falsy when we weren't connected. Now a true return simply indicates a lack of errors. If you've been using this to test for whether the connection is still up, you need to call connected() instead.

◆ ping()

bool mysqlpp::Connection::ping ( )

"Pings" the database server

Return values

true	if server is responding
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.

References build_error_message(), connected(), error_message_, and mysqlpp::DBDriver::ping().

◆ query() [1/2]

Query mysqlpp::Connection::query ( const char * qstr = 0 )

Return a new query object.

The returned query object is tied to this connection object, so when you call a method like execute() on that object, the query is sent to the server this object is connected to.

Parameters

qstr	an optional query string for populating the new Query object

References mysqlpp::OptionalExceptions::throw_exceptions().

Referenced by mysqlpp::Transaction::commit(), query(), mysqlpp::Transaction::rollback(), and mysqlpp::Transaction::Transaction().

◆ query() [2/2]

Query mysqlpp::Connection::query ( const std::string & qstr )

Return a new query object.

Parameters

qstr	initial query string

References query().

◆ select_db()

bool mysqlpp::Connection::select_db ( const std::string & db )

Change to a different database managed by the database server we are connected to.

Parameters

db	database to switch to

Return values

true	if we changed databases successfully

References build_error_message(), connected(), errnum(), error(), error_message_, mysqlpp::DBDriver::select_db(), and mysqlpp::OptionalExceptions::throw_exceptions().

◆ set_option()

bool mysqlpp::Connection::set_option ( Option * o )

Sets a connection option.

Parameters

o	pointer to any derivative of Option allocated on the heap

Objects passed to this method and successfully set will be released when this Connection object is destroyed. If an error occurs while setting the option the object will be deleted immediately.

Because there are so many Option subclasses, the actual effect of this function has a wide range. This mechanism abstracts away many things that are unrelated down at the database driver level, hiding them behind a coherent, type-safe interface.

The rules about which options can be set, when, are up to the underlying database driver. Some must be set before the connection is established because they can only be used during that connection setup process. Others can be set at any time after the connection comes up. If you get it wrong, you'll get a BadOption exception.

Return values

true	if option was successfully set

References mysqlpp::DBDriver::error(), error_message_, mysqlpp::DBDriver::set_option(), and mysqlpp::OptionalExceptions::throw_exceptions().

◆ thread_id()

unsigned long mysqlpp::Connection::thread_id ( )

Returns the database server's thread ID for this connection.

This has nothing to do with threading on the client side. The only thing you can do with this value is pass it to kill().

References mysqlpp::DBDriver::thread_id().

◆ thread_start()

bool mysqlpp::Connection::thread_start ( )

static

Tells the underlying database driver that the current thread is now using its services.

It's not necessary to call this from the thread that creates the connection as it's done automatically. This method exists for times when multiple threads may use this object; it allows the underlying database driver to set up any per-thread data structures it needs.

The MySQL++ user manual's chapter on threads details two major strategies for dealing with connections in the face of threads. The Connection-per-thread option frees you from ever having to call this method. The other documented strategy is to use ConnectionPool, which opens the possibility for one thread to create a connection that another uses, so you do need to call this method in that case, or with any other similar strategy.

Return values

True	if there was no problem

References mysqlpp::DBDriver::thread_start().

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

connection.h
connection.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Connection() [1/3]

◆ Connection() [2/3]

◆ Connection() [3/3]

Member Function Documentation

◆ connect()

◆ connected()

◆ copy()

◆ count_rows()

◆ create_db()

◆ drop_db()

◆ error()

◆ ipc_info()

◆ kill()

◆ operator private_bool_type()

◆ ping()

◆ query() [1/2]

◆ query() [2/2]

◆ select_db()

◆ set_option()

◆ thread_id()

◆ thread_start()