...one of the most highly
regarded and expertly designed C++ library projects in the
world. — Herb Sutter and Andrei
This section discusses several aspects regarding the establishment of a connection
with the MySQL server, including a detailed description of the parameters in
are mandatory. The password is provided to Boost.MySQL
in plain text, but it is not sent like that to the server (see below for more
info). If your password is empty, just provide an empty string.
MySQL implements several methods of authentication with the server, in what
is called pluggable
authentication. The authentication plugin used is chosen on a per-user
basis. This information is stored in the
Additionally, servers define a default authentication plugin (see
default plugin will be used for newly created users, and may affect how the
Boost.MySQL implements the two most common authentication plugins:
mysql_native_password. Unless otherwise configured, this is the default plugin for MySQL 5.7 and MariaDB. It can be used over both TLS and non-TLS connections. It sends the password hashed, salted by a nonce.
caching_sha2_password. Unless otherwise configured, this is the default plugin for MySQL 8.0. It can only be used over TLS, which makes it less vulnerable. This is also the reason why all examples use TLS.
Other authentication plugins are not supported. Multi-factor authentication is not yet supported, either. If you require any other plugin, please file a feature request against the GitHub repository.
If you try to establish a connection (using
and you specify a user with an unsupported authentication plugin, the operation
Servers configured with a default authentication plugin not implemented in Boost.MySQL are not supported, regardless of the actual plugin the concrete user employs. This limitation may be lifted in the future.
is a string with the database name to connect to. If you specify it, your connection
will default to use that database, as if you had issued a
USE statement. You can leave it blank
to select no database. You can always employ a
USE statement to select a different
database after establishing the connection.
When establishing a connection, you specify a numeric collation ID parameter
which will determine the connection's character set and collation. This determines
the encoding of the strings sent to and received from the server. If left unspecified,
utf8mb4_general_ci will be
used, which is portable accross MySQL 5.x, MySQL 8.x and MariaDB.
Collation IDs are defined in
Some collations are portable between servers, while others are MySQL or MariaDB-specific,
and some IDs overlap. You may also define your own collations server-side.
This is why collations are specified as an integer, rather than an enumeration.
Please refer to this section for more info about character sets.
If you specify a collation ID that is unknown to the server (an old server
that doesn't recognize the newest collations), the handshake operation will
succeed but the connection will sillently fall back to the server's default
character set and collation. If you want to be sure, use a
When establising a connection, you can specify a
value to configure whether to use SSL/TLS or not. As explained in this
section, this parameters can be employed to configure SSL negotiation.
This value is ignored if the underlying stream does not support SSL.