Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Handshake parameters

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.

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 ways of authentication with the server, in what is called pluggable authentication. The decission of which authentication plugin to use is made in a per-user basis. This information is stored in the mysql.user table. In addition to this, 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:

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

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

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.

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

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.


PrevUpHomeNext