[/
    Copyright (c) 2019-2023 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
   
    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]

[section:connparams Handshake parameters]
[nochunk]

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

[section:auth Authentication]

The parameters [refmem handshake_params username] and
[refmem handshake_params password] are mandatory. The
password is provided to __Self__ 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 [mysqllink pluggable-authentication.html
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 [mysqllink server-system-variables.html#sysvar_authentication_policy `authentication_policy`] and
[mysqllink server-system-variables.html#sysvar_default_authentication_plugin
`default_authentication_plugin`]). The default plugin will
be used for newly created users, and may affect how the handshake works.

__Self__ implements the two most common authentication plugins:

* [mysqllink native-pluggable-authentication.html `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.
* [mysqllink caching-sha2-pluggable-authentication.html
  `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 [refmem connection handshake] or
[refmem 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 __Self__ are not supported, regardless
    of the actual plugin the concrete user employs. This limitation
    may be lifted in the future.
]

[endsect]

[section:database Connect with database]

The parameter [refmem 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.

[endsect]

[section:collation Connection encoding and collation]

When establishing a connection, you specify a numeric collation ID
parameter ([refmem 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 [include_file boost/mysql/mysql_collations.hpp] and 
[include_file 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 [link mysql.charsets 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.
]

[endsect]

[section:ssl SSL/TLS]

When establising a connection, you can specify a [reflink ssl_mode]
value to configure whether to use SSL/TLS or not. As explained in
[link mysql.ssl.negotiation this section], this parameters can be
employed to configure SSL negotiation. This value is ignored if the
underlying stream does not support SSL.

[endsect]


[endsect] [/ connparams]