| Home | Libraries | People | FAQ | More

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

Establishes a connection to a MySQL server.

###### Synopsis

    template<
        class CompletionToken = with_diagnostics_t<asio::deferred_t>>
    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, the operation 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)`.

###### Executor

Intermediate completion handlers, as well as the final handler, are executed using `token`'s associated executor, or `this->get_executor()` if the token doesn't have an associated executor.

If the final handler has an associated immediate executor, and the operation completes immediately, the final handler is dispatched to it. Otherwise, the final handler is called as if it was submitted using `asio::post`, and is never be called inline from within this function.