# mysqlpp::Connection Class Reference

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

`#include <connection.h>`

Inheritance diagram for mysqlpp::Connection:

[legend]
Collaboration diagram for mysqlpp::Connection:

[legend]
List of all members.

## Public Types

enum | OptionArgType { opt_type_none, opt_type_string, opt_type_integer, opt_type_boolean }
| Legal types of option arguments.

enum

Option {
opt_FIRST = -1, opt_connect_timeout = 0, opt_compress, opt_named_pipe,
opt_init_command, opt_read_default_file, opt_read_default_group, opt_set_charset_dir,
opt_set_charset_name, opt_local_infile, opt_protocol, opt_shared_memory_base_name,
opt_read_timeout, opt_write_timeout, opt_use_result, opt_use_remote_connection,
opt_use_embedded_connection, opt_guess_connection, opt_set_client_ip, opt_secure_auth,
opt_multi_statements, opt_report_data_truncation, opt_reconnect, opt_COUNT
}

| Per-connection options you can set with set_option(). More...

## Public Member Functions

| Connection (bool te=true)
| Create object without connecting it to the MySQL server.
| Connection (const char *db, const char *host="", const char *user="", const char *passwd="", uint port=0, my_bool compress=0, unsigned int connect_timeout=60, cchar *socket_name=0, unsigned int client_flag=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 C API connection.
bool | connect (const MYSQL &mysql)
| Establish a new connection using the same parameters as an existing C API connection.
| ~Connection ()
| Destroy connection object.
bool | 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.
void | purge ()
| Alias for close().
Query | query ()
| Return a new query object.
| operator bool ()
| Alias for success().
Connection & | operator= (const Connection &rhs)
| Copy an existing Connection object's state into this object.
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.
bool | create_db (const std::string &db)
| Create a database.
bool | drop_db (const std::string &db)
| Drop a database.
bool | select_db (const 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.
st_mysql_options | get_options () const
| Return the connection options object.
bool | set_option (Option option)
| Sets a connection option, with no argument.
bool | set_option (Option option, const char *arg)
| Sets a connection option, with string argument.
bool | set_option (Option option, unsigned int arg)
| Sets a connection option, with integer argument.
bool | set_option (Option option, bool arg)
| Sets a connection option, with Boolean argument.
bool | set_option_default (Option option)
| Same as set_option(), except that it won't override a previously-set option.
template<typename T> bool | set_option_default (Option option, T arg)
| Same as set_option(), except that it won't override a previously-set option.
bool | option_set (Option option)
| Returns true if the given option has been set already.
void | 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.
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.
std::ostream & | api_version (std::ostream &os)
| Insert C API version we're linked against into C++ stream.

## Protected Types

enum | OptionError { opt_err_type, opt_err_value, opt_err_conn }
| Types of option setting errors we can diagnose.

## Protected Member Functions

void | disconnect ()
| Drop the connection to the database server.
bool | bad_option (Option option, OptionError error)
| Error handling routine for set_option().
OptionArgType | option_arg_type (Option option)
| Given option value, return its proper argument type.
bool | set_option_impl (mysql_option moption, const void *arg=0)
| Set MySQL C API connection option.
void | copy (const Connection &other)
| Establish a new connection as a copy of an existing one.

## Friends

class | ResNSel
class | ResUse
class | Query

## Detailed Description

Manages the connection to the MySQL database.

## Member Enumeration Documentation

enum mysqlpp::Connection::Option

| Per-connection options you can set with set_option(). This is currently a combination of the MySQL C API `mysql_option` and `enum_mysql_set_option` enums. It may be extended in the future.

## Constructor & Destructor Documentation

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

Create object without connecting it to the MySQL server.

Parameters:

  te | if true, exceptions are thrown on errors

mysqlpp::Connection::Connection | ( | const char * | db,
|  | const char * | host = "",
|  | const char * | user = "",
|  | const char * | passwd = "",
|  | uint | port = 0,
|  | my_bool | compress = 0,
|  | unsigned int | connect_timeout = 60,
|  | cchar * | socket_name = 0,
|  | unsigned int | client_flag = 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 MySQL database. It is the thinnest layer in MySQL++ over the MySQL C API function `mysql_real_connect()`. The correspondence isn't exact as we have some additional parameters you'd have to set with `mysql_option()` when using the C API.

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

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

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

Parameters:

  other | existing Connection object

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

ostream & mysqlpp::Connection::api_version | ( | std::ostream & | os | ) |

| Insert C API version we're linked against into C++ stream. Version will be of the form X.Y.Z, where X is the major version number, Y the minor version, and Z the bug fix number.

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 = "",
|  | 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 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::connect | ( | const MYSQL & | mysql | ) |

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

Parameters:

  mysql | existing MySQL C API connection object

bool mysqlpp::Connection::connected | ( |  | ) | const`[inline]`

return 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

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

Create a database.

Parameters:

  db | name of database to create

Returns:
  true if database was created successfully

void mysqlpp::Connection::disconnect | ( |  | ) | `[protected]`

| 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::Connection::drop_db | ( | const std::string & | db | ) |

Drop a database.

Parameters:

  db | name of database to destroy

Returns:
  true if database was created successfully

void mysqlpp::Connection::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. Must be called before connection is established. Wraps `mysql_ssl_set()` in MySQL C API.

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.

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.

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.

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

"Pings" the MySQL database

Wraps `mysql_ping()` in the C API. As a result, this function will try to reconnect to the server if the connection has been dropped.

Return values:

  0 | if server is responding, regardless of whether we had to reconnect or not
  nonzero | 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::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::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::set_option | ( | Option | option | ) |

Sets a connection option, with no argument.

Parameters:

  option | any of the Option enum constants

Based on the option you give, this function calls either `mysql_options()` or `mysql_set_server_option()` in the C API.

There are several overloaded versions of this function. The others take an additional argument for the option and differ only by the type of the option. Unlike with the underlying C API, it does matter which of these overloads you call: if you use the wrong argument type or pass an argument where one is not expected (or vice versa), the call will either throw an exception or return false, depending on the object's "throw exceptions" flag.

This mechanism parallels the underlying C API structure fairly closely, but do not expect this to continue in the future. Its very purpose is to 'paper over' the differences among the C API's option setting mechanisms, so it may become further abstracted from these mechanisms.

Return values:

  true | if option was successfully set, or at least queued for setting during connection establishment sequence

If exceptions are enabled, a false return means the C API rejected the option, or the connection is not established and so the option was queued for later processing. If exceptions are disabled, false can also mean that the argument was of the wrong type (wrong overload was called), the option value was out of range, or the option is not supported by the C API, most because it isn't a high enough version. These latter cases will cause BadOption exceptions otherwise.

bool mysqlpp::Connection::set_option_impl | ( | mysql_option | moption,
|  | const void * | arg = 0
| ) | `[protected]`

| Set MySQL C API connection option. Wraps `mysql_options()` in C API. This is an internal implementation detail, to be used only by the public overloads above.

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.

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

- connection.h
- connection.cpp