| Home | Libraries | People | FAQ | More

#### any_connection

A connection to a MySQL server.

##### Synopsis

Defined in header `<boost/mysql/any_connection.hpp>`

    class any_connection;

##### Types

Name | Description
--- | ---
executor_type | The executor type associated to this object.

##### Member Functions

Name | Description
--- | ---
any_connection [constructor] | Constructs a connection object from an executor and an optional set of parameters. — Constructs a connection object from an execution context and an optional set of parameters. — Move constructor.
async_close | Cleanly closes the connection to the server.
async_close_statement | Closes a statement, deallocating it from the server.
async_connect | Establishes a connection to a MySQL server.
async_execute | Executes a text query or prepared statement.
async_ping | Checks whether the server is alive.
async_prepare_statement | Prepares a statement server-side.
async_read_resultset_head | Reads metadata for subsequent resultsets in a multi-resultset operation.
async_read_some_rows | Reads a batch of rows.
async_reset_connection | Resets server-side session state, like variables and prepared statements.
async_run_pipeline | Runs a set of pipelined requests.
async_set_character_set | Sets the connection's character set, as per SET NAMES.
async_start_execution | Starts a SQL execution as a multi-function operation.
backslash_escapes | Returns whether backslashes are being treated as escape sequences.
close | Cleanly closes the connection to the server.
close_statement | Closes a statement, deallocating it from the server.
connect | Establishes a connection to a MySQL server.
connection_id | Retrieves the connection id associated to the current session.
current_character_set | Returns the character set used by this connection.
execute | Executes a text query or prepared statement.
format_opts | Returns format options suitable to format SQL according to the current connection configuration.
get_executor | Retrieves the executor associated to this object.
meta_mode | Returns the current metadata mode that this connection is using.
operator= | Move assignment.
ping | Checks whether the server is alive.
prepare_statement | Prepares a statement server-side.
read_resultset_head | Reads metadata for subsequent resultsets in a multi-resultset operation.
read_some_rows | Reads a batch of rows.
reset_connection | Resets server-side session state, like variables and prepared statements.
run_pipeline | Runs a set of pipelined requests.
set_character_set | Sets the connection's character set, as per SET NAMES.
set_meta_mode | Sets the metadata mode.
start_execution | Starts a SQL execution as a multi-function operation.
uses_ssl | Returns whether the connection negotiated the use of SSL or not.
~any_connection [destructor] | Destructor.

##### Description

Represents a connection to a MySQL server. This is the main I/O object that this library implements. It's logically comprised of session state and an internal stream (usually a socket). The stream is not directly accessible. It's constructed using the executor passed to the constructor.

This class supports establishing connections with servers using TCP, TCP over TLS and UNIX sockets.

The class is named `any_connection` because it's not templated on a `Stream` type, as opposed to `connection`. New code should prefer using `any_connection` whenever possible.

Compared to `connection`, this class:

- Is type-erased. The type of the connection doesn't depend on the transport being used.
- Is easier to connect, as `connect` and `async_connect` handle hostname resolution.
- Can always be re-connected after being used or encountering an error.
- Always uses `asio::any_io_executor`.
- Has the same level of performance.

This is a move-only type.

##### Single outstanding async operation per connection

At any given point in time, only one async operation can be outstanding per connection. If an async operation is initiated while another one is in progress, it will fail with `client_errc::operation_in_progress`.

##### Default completion tokens

The default completion token for all async operations in this class is `with_diagnostics(asio::deferred)`, which allows you to use `co_await` and have the expected exceptions thrown on error.

##### Thread safety

Distinct objects: safe.

Shared objects: unsafe.

This class is not thread-safe: for a single object, if you call its member functions concurrently from separate threads, you will get a race condition.

Convenience header `<boost/mysql.hpp>`