Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members   File Members  

mysqlpp::Connection Class Reference

Manages the connection to the MySQL database. More...

#include <connection.h>

List of all members.

Public Methods

 Connection ()
 Create object without connecting it to the MySQL server.

 Connection (bool te)
 Connection (const char *db, const char *host="", const char *user="", const char *passwd="", bool te=true)
 For connecting to database without any special options.

 Connection (const char *db, const char *host, const char *user, const char *passwd, uint port, my_bool compress=0, unsigned int connect_timeout=60, bool te=true, cchar *socket_name=0, unsigned int client_flag=0)
 Connect to database, allowing you to specify all connection parameters.

bool connect (cchar *db="", cchar *host="", cchar *user="", cchar *passwd="")
 Open connection to MySQL database.

bool real_connect (cchar *db="", cchar *host="", cchar *user="", cchar *passwd="", uint port=0, my_bool compress=0, unsigned int connect_timeout=60, cchar *socket_name=0, unsigned int client_flag=0)
 Connect to database after object is created.

void close ()
 Close connection to MySQL server.

std::string info ()
 Calls MySQL C API function mysql_info() and returns result as a C++ string.

bool connected () const
 return true if connection was established successfully

bool success () const
 Return true if the last query was successful.

bool lock ()
 Lock the object.

void unlock ()
 Unlock the object.

void purge ()
 Alias for close().

Query query ()
 Return a new query object.

 operator bool ()
 Alias for success().

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.

int refresh (unsigned int refresh_options)
 Wraps MySQL C API function mysql_refresh().

int ping ()
 "Pings" the MySQL database

int kill (unsigned long pid)
 Kill a MySQL server thread.

std::string client_info ()
 Get MySQL client library version.

std::string host_info ()
 Get information about the network connection.

int proto_info ()
 Returns version number of MySQL protocol this connection is using.

std::string server_info ()
 Get the MySQL server's version number.

std::string stat ()
 Returns information about MySQL server status.

Result store (const std::string &str)
 Execute a query that can return a result set.

ResUse use (const std::string &str)
 Execute a query that can return a result set.

ResNSel execute (const std::string &str)
 Execute a query.

bool exec (const std::string &str)
 Execute a query.

Result store (const std::string &str, bool te)
 Same as store(str) except that it allows you to turn off exceptions for this query.

ResUse use (const std::string &str, bool te)
 Same as use(str) except that it allows you to turn off exceptions for this query.

ResNSel execute (const std::string &str, bool te)
 Same as execute(str) except that it allows you to turn off exceptions for this query.

bool create_db (std::string db)
 Create a database.

bool drop_db (std::string db)
 Drop a database.

bool select_db (std::string db)
 Change to a different database.

bool select_db (const char *db)
 Change to a different database.

bool reload ()
 Ask MySQL server to reload the grant tables.

bool shutdown ()
 Ask MySQL server to shut down.

std::string infoo ()
 Alias for info().

st_mysql_options get_options () const
 Return the connection options object.

int read_options (enum mysql_option option, const char *arg)
 Sets the given MySQL connection option.

my_ulonglong affected_rows ()
 Return the number of rows affected by the last query.

my_ulonglong insert_id ()
 Get ID generated for an AUTO_INCREMENT column in the previous INSERT query.

template<class Sequence> void storein_sequence (Sequence &con, const std::string &s)
 Execute a query, storing the result set in an STL sequence container.

template<class Set> void storein_set (Set &con, const std::string &s)
 Execute a query, storing the result set in an STL associative container.

template<class T> void storein (std::vector< T > &con, const std::string &s)
 Specialization of storein_sequence() for std::vector.

template<class T> void storein (std::deque< T > &con, const std::string &s)
 Specialization of storein_sequence() for std::deque.

template<class T> void storein (std::list< T > &con, const std::string &s)
 Specialization of storein_sequence() for std::list.

template<class T> void storein (std::set< T > &con, const std::string &s)
 Specialization of storein_set() for std::set.

template<class T> void storein (std::multiset< T > &con, const std::string &s)
 Specialization of storein_set() for std::multiset.


Detailed Description

Manages the connection to the MySQL database.


Constructor & Destructor Documentation

mysqlpp::Connection::Connection  
 

Create object without connecting it to the MySQL server.

Use real_connect() method to establish the connection.

mysqlpp::Connection::Connection bool    te
 

Same as default ctor except that it allows you to choose whether exceptions are enabled.

Parameters:
te  if true, exceptions are thrown on errors

mysqlpp::Connection::Connection const char *    db,
const char *    host = "",
const char *    user = "",
const char *    passwd = "",
bool    te = true
 

For connecting to database without any special options.

This constructor takes the minimum parameters needed for most programs' use of MySQL. There is a more complicated constructor that lets you specify everything that the C API function mysql_real_connect() does.

Parameters:
db  name of database to use
host  host name or IP address of MySQL server, or 0 if server is running on the same host as your program
user  user name to log in under, or 0 to use the user name this program is running under
passwd  password to use when logging in
te  if true, throw exceptions on errors

mysqlpp::Connection::Connection const char *    db,
const char *    host,
const char *    user,
const char *    passwd,
uint    port,
my_bool    compress = 0,
unsigned int    connect_timeout = 60,
bool    te = true,
cchar   socket_name = 0,
unsigned int    client_flag = 0
 

Connect to database, allowing you to specify all connection parameters.

This constructor allows you to most fully specify the options used when connecting to the MySQL database. It is the thinnest layer in MySQL++ over the MySQL C API function mysql_real_connect().

Parameters:
db  name of database to use
host  host name or IP address of MySQL server, or 0 if server is running on the same host as your program
user  user name to log in under, or 0 to use the user name this program is running under
passwd  password to use when logging in
port  TCP port number MySQL server is listening on, or 0 to use default value
compress  if true, compress data passing through connection, to save bandwidth at the expense of CPU time
connect_timeout  max seconds to wait for server to respond to our connection attempt
te  if true, throw exceptions on errors
socket_name  Unix domain socket server is using, if connecting to MySQL server on the same host as this program running on, or 0 to use default name
client_flag  special connection flags. See MySQL C API documentation for mysql_real_connect() for details.


Member Function Documentation

my_ulonglong mysqlpp::Connection::affected_rows   [inline]
 

Return the number of rows affected by the last query.

Simply wraps mysql_affected_rows() in the C API.

std::string mysqlpp::Connection::client_info   [inline]
 

Get MySQL client library version.

Simply wraps mysql_get_client_info() in the C API.

void mysqlpp::Connection::close   [inline]
 

Close connection to MySQL server.

Closes the connection to the MySQL server.

bool mysqlpp::Connection::connect cchar   db = "",
cchar   host = "",
cchar   user = "",
cchar   passwd = ""
 

Open connection to MySQL database.

Open connection to the MySQL server, using defaults for all but the most common parameters. It's better to use one of the connect-on-create constructors if you can.

See this for parameter documentation.

bool mysqlpp::Connection::connected   const [inline]
 

return true if connection was established successfully

Returns:
true if connection was established successfully

bool mysqlpp::Connection::create_db std::string    db [inline]
 

Create a database.

Parameters:
db  name of database to create
Returns:
false if database was created successfully. (Yes, false! This behavior will change in the next major version.)

bool mysqlpp::Connection::drop_db std::string    db [inline]
 

Drop a database.

Parameters:
db  name of database to destroy
Returns:
false if database was created successfully. (Yes, false! This behavior will change in the next major version.)

int mysqlpp::Connection::errnum   [inline]
 

Return last MySQL error number associated with this connection.

Simply wraps mysql_errno() in the C API.

const char* mysqlpp::Connection::error   [inline]
 

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

Simply wraps mysql_error() in the C API.

bool mysqlpp::Connection::exec const std::string &    str
 

Execute a query.

Same as execute(), except that it only returns a flag indicating whether the query succeeded or not. It is basically a thin wrapper around the C API function mysql_query().

Parameters:
str  the query to execute
Returns:
true if query was executed successfully
See also:
execute(), store(), storein(), and use()

ResNSel mysqlpp::Connection::execute const std::string &    str,
bool    te
 

Same as execute(str) except that it allows you to turn off exceptions for this query.

Parameters:
str  query to execute
te  if true, no exceptions will be thrown on errors.

ResNSel mysqlpp::Connection::execute const std::string &    str [inline]
 

Execute a query.

Use this function if you don't expect the server to return a result set. For instance, a DELETE query. The returned ResNSel object contains status information from the server, such as whether the query succeeded, and if so how many rows were affected.

Parameters:
str  the query to execute
Returns:
ResNSel status information about the query
See also:
exec(), store(), storein(), and use()

std::string mysqlpp::Connection::host_info   [inline]
 

Get information about the network connection.

String contains info about type of connection and the server hostname.

Simply wraps mysql_get_host_info() in the C API.

std::string mysqlpp::Connection::infoo   [inline]
 

Alias for info().

This probably shouldn't exist. It will be removed in the next major version of the library unless a good justification is found.

my_ulonglong mysqlpp::Connection::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.

int mysqlpp::Connection::kill unsigned long    pid [inline]
 

Kill a MySQL server thread.

Parameters:
pid  ID of thread to kill
Simply wraps mysql_kill() in the C API.

bool mysqlpp::Connection::lock   [inline]
 

Lock the object.

Apparently supposed to prevent multiple simultaneous connections since only connection-related functions change the lock status but it's never actually checked! See Wishlist for plan to fix this.

mysqlpp::Connection::operator bool   [inline]
 

Alias for success().

Alias for success() member function. Allows you to have code constructs like this:

                    Connection conn;
                    .... use conn
                    if (conn) {
                        ... last SQL query was successful
                    }
                    else {
                        ... error occurred in SQL query
                    }

int mysqlpp::Connection::ping   [inline]
 

"Pings" the MySQL database

If server doesn't respond, this function tries to reconnect.

Return values:
0  if server is responding, regardless of whether we had to reconnect or not
nonzero  if server did not respond to ping and we could not re-establish the connection
Simply wraps mysql_ping() in the C API.

int mysqlpp::Connection::proto_info   [inline]
 

Returns version number of MySQL protocol this connection is using.

Simply wraps mysql_get_proto_info() in the C API.

Query mysqlpp::Connection::query  
 

Return a new query object.

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

int mysqlpp::Connection::read_options enum mysql_option    option,
const char *    arg
[inline]
 

Sets the given MySQL connection option.

Not sure why this is named as it is; set_option() would be a better name. It may change in the next major version of the library.

Simply wraps mysql_option() in the C API.

bool mysqlpp::Connection::real_connect cchar   db = "",
cchar   host = "",
cchar   user = "",
cchar   passwd = "",
uint    port = 0,
my_bool    compress = 0,
unsigned int    connect_timeout = 60,
cchar   socket_name = 0,
unsigned int    client_flag = 0
 

Connect to database after object is created.

It's better to use one of the connect-on-create constructors if you can.

Despite the name, this function is not a direct wrapper for the MySQL C API function mysql_real_connect(). It also sets some connection-related options using mysql_options().

See this for parameter documentation.

int mysqlpp::Connection::refresh unsigned int    refresh_options [inline]
 

Wraps MySQL C API function mysql_refresh().

The corresponding C API function is undocumented. All I know is that it's used by mysqldump and mysqladmin, according to MySQL bug database entry http://bugs.mysql.com/bug.php?id=9816 If that entry changes to say that the function is now documented, reevaluate whether we need to wrap it. It may be that it's not supposed to be used by regular end-user programs.

bool mysqlpp::Connection::reload  
 

Ask MySQL server to reload the grant tables.

User must have the "reload" privilege.

Simply wraps mysql_reload() in the C API. Since that function is deprecated, this one is, too. The MySQL++ replacement is execute("FLUSH PRIVILEGES").

std::string mysqlpp::Connection::server_info   [inline]
 

Get the MySQL server's version number.

Simply wraps mysql_get_server_info() in the C API.

bool mysqlpp::Connection::shutdown  
 

Ask MySQL server to shut down.

User must have the "shutdown" privilege.

Simply wraps mysql_shutdown() in the C API.

std::string mysqlpp::Connection::stat   [inline]
 

Returns information about MySQL server 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.

Result mysqlpp::Connection::store const std::string &    str,
bool    te
 

Same as store(str) except that it allows you to turn off exceptions for this query.

Parameters:
str  query to execute
te  if true, no exceptions will be thrown on errors.

Result mysqlpp::Connection::store const std::string &    str [inline]
 

Execute a query that can return a result set.

This function returns the entire result set immediately. This is useful if you actually need all of the records at once, but if not, consider using use() instead, which returns the results one at a time. As a result of this difference, use() doesn't need to allocate as much memory as store().

You must use store(), storein() or use() for SELECT, SHOW, DESCRIBE and EXPLAIN queries. You can use these functions with other query types, but since they don't return a result set, exec() and execute() are more efficient.

The name of this method comes from the MySQL C API function it is implemented in terms of, mysql_store_result().

Returns:
Result object containing entire result set
See also:
exec(), execute(), storein(), and use()

template<class Sequence>
void mysqlpp::Connection::storein_sequence Sequence &    con,
const std::string &    s
 

Execute a query, storing the result set in an STL sequence container.

This function works much like store() from the caller's perspective, because it returns the entire result set at once. It's actually implemented in terms of use(), however, so that memory for the result set doesn't need to be allocated twice.

Parameters:
con  any STL sequence container, such as std::vector
s  query string to execute
See also:
exec(), execute(), store(), and use()

template<class Set>
void mysqlpp::Connection::storein_set Set   con,
const std::string &    s
 

Execute a query, storing the result set in an STL associative container.

Parameters:
con  any STL associative container, such as std::set
s  query string to execute
The same thing as storein_sequence(), except that it's used with associative STL containers, such as std::set. Other than that detail, that method's comments apply equally well to this one.

void mysqlpp::Connection::unlock   [inline]
 

Unlock the object.

See lock() documentation for caveats.

ResUse mysqlpp::Connection::use const std::string &    str,
bool    te
 

Same as use(str) except that it allows you to turn off exceptions for this query.

Parameters:
str  query to execute
te  if true, no exceptions will be thrown on errors.

ResUse mysqlpp::Connection::use const std::string &    str [inline]
 

Execute a query that can return a result set.

Unlike store(), this function does not return the result set directly. Instead, it returns an object that can walk through the result records one by one. This is superior to store() when there are a large number of results; store() would have to allocate a large block of memory to hold all those records, which could cause problems.

A potential downside of this method is that MySQL database resources are tied up until the result set is completely consumed. Do your best to walk through the result set as expeditiously as possible.

The name of this method comes from the MySQL C API function that initiates the retrieval process, mysql_use_result(). This method is implemented in terms of that function.

Returns:
ResUse object that can walk through result set serially
See also:
exec(), execute(), store() and storein()


The documentation for this class was generated from the following files:
Generated on Thu May 26 09:40:28 2005 for MySQL++ by doxygen1.2.18