| Home | Libraries | People | FAQ | More

###### any_connection::async_connect (1 of 2 overloads)

Establishes a connection to a MySQL server.

###### Synopsis

    template<
        class CompletionToken>
    auto
    async_connect(
        const connect_params& params,
        diagnostics& diag,
        CompletionToken&& token);

###### Description

This function performs the following:

- If a connection has already been established (by a previous call to `connect` or `async_connect`), closes it at the transport layer (by closing any underlying socket) and discards any protocol state associated to it. (If you require a clean close, call `close` or `async_close` before using this function).
- If the connection is configured to use TCP (`params.server_address.type() == address_type::host_and_port`), resolves the passed hostname to a set of endpoints. An empty hostname is equivalent to `"localhost"`.
- Establishes the physical connection (performing the TCP or UNIX socket connect).
- Performs the MySQL handshake to establish a session. If the connection is configured to use TLS, the TLS handshake is performed as part of this step.
- If any of the above steps fail, the TCP or UNIX socket connection is closed.

You can configure some options using the `connect_params` struct.

The decision to use TLS or not is performed using the following:

- If the transport is not TCP (`params.server_address.type() != address_type::host_and_port`), the connection will never use TLS.
- If the transport is TCP, and `params.ssl == ssl_mode::disable`, the connection will not use TLS.
- If the transport is TCP, and `params.ssl == ssl_mode::enable`, the connection will use TLS only if the server supports it.
- If the transport is TCP, and `params.ssl == ssl_mode::require`, the connection will always use TLS. If the server doesn't support it, this function will fail with `client_errc::server_doesnt_support_ssl`.

If `params.connection_collation` is within a set of well-known collations, this function sets the current character set, such that `current_character_set` returns a non-null value. The default collation (`utf8mb4_general_ci`) is the only one guaranteed to be in the set of well-known collations.

###### Object lifetimes

params needs to be kept alive until the operation completes, as no copies will be made by the library.

###### Handler signature

The handler signature for this operation is `void(boost::mysql::error_code)`.