mysqlpp::Connection Class Reference

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

#include <connection.h>

Inheritance diagram for mysqlpp::Connection:

[legend]Collaboration diagram for mysqlpp::Connection:

[legend]List of all members.

Public Member Functions
	Connection (bool te=true)
	Create object without connecting to the database server.
	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.
	Connection (const Connection &other)
	Establish a new connection using the same parameters as an existing connection.
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.
bool	connected () const
	Returns true if connection was established successfully.
ulonglong	count_rows (const std::string &table)
	Returns the number of rows in a table.
bool	create_db (const std::string &db)
	Ask the database server to create a database.
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.
int	errnum ()
	Return last error number associated with this connection.
const char *	error () const
	Return error message for last error associated with this connection.
std::string	ipc_info () const
	Get information about the IPC connection to the database server.
bool	kill (unsigned long tid) const
	Kill a database server thread.
	operator private_bool_type () const
	Test whether any error has occurred within the object.
Connection &	operator= (const Connection &rhs)
	Copy an existing Connection object's state into this object.
bool	ping ()
	"Pings" the database server
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.
Query	query (const std::string &qstr)
	Return a new query object.
bool	select_db (const std::string &db)
	Change to a different database managed by the database server we are connected to.
std::string	server_version () const
	Get the database server's version string.
bool	set_option (Option *o)
	Sets a connection option.
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.
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.
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.
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 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

mysqlpp::Connection::Connection

(

bool

te = true

)

Create object without connecting to the database server.

Parameters:

te

if true, exceptions are thrown on errors

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.

mysqlpp::Connection::Connection

(

const Connection &

other

)

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

Parameters:

other

existing Connection object

---

Member Function Documentation

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.

bool mysqlpp::Connection::connected

(

)

const

Returns true if connection was established successfully.

Returns:

true if connection was established successfully

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

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.

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

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

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.

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.

bool mysqlpp::Connection::kill

(

unsigned long

tid

)

const

Kill a database server thread.

Parameters:

tid

ID of thread to kill

See also:

thread_id()

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:

        /// 

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.