Boost C++ Libraries

This section discusses several aspects regarding the establishment of a connection with the MySQL server, including a detailed description of the parameters in handshake_params.

Authentication

The parameters handshake_params::username and handshake_params::password 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 mysql.user table. Additionally, servers define a default authentication plugin (see authentication_policy and default_authentication_plugin). The default plugin will be used for newly created users, and may affect how the handshake works.

Boost.MySQL implements the two most common authentication plugins:

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 connection::handshake or connection::connect) and you specify a user with an unsupported authentication plugin, the operation will fail.

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

Connect with database

The parameter handshake_params::database 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.

Connection encoding and collation

When establishing a connection, you specify a numeric collation ID parameter (handshake_params::connection_collation), 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 <boost/mysql/mysql_collations.hpp> and <boost/mysql/mariadb_collations.hpp>. 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.

	Warning
	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 "SET NAMES" statement.

SSL/TLS

When establising a connection, you can specify a ssl_mode 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.