MySQL Connector/C++ Release Notes
If an application tries to obtain a result set from a statement that does not produce one, an exception occurs. For applications that do not catch such exceptions, Connector/C++ now produces a more informative error message to indicate why the exception occurred. (Bug #28591814, Bug #92263)
For applications that use the legacy JDBC API (that is, not X DevAPI or X DevAPI for C), it is now possible when creating a new session to specify multiple hosts to be tried until a successful connection is established. A list of hosts can be given in the session creation options.
The new OPT_MULTI_HOST
option is disabled by
default for backward compatibility, but if enabled in the
ConnectionOptionsMap
parameter passed to
connect()
calls, it permits other map
parameters to specify multiple hosts. Examples:
sql::ConnectOptionsMap opts; opts["hostName"]="host1,host2:13001,localhost:13000"; opts["schema"]="test"; opts["OPT_MULTI_HOST"] = true; opts["userName"]="user
"; opts["password"]="password
"; driver->connect(opts);
sql::ConnectOptionsMap opts; opts["hostName"]="tcp://host1,host2:13001,localhost:13000/test"; opts["OPT_MULTI_HOST"] = true; opts["userName"]="user
"; opts["password"]="password
"; driver->connect(opts);
sql::ConnectOptionsMap opts; opts["hostName"]="mysql://host1,host2:13001,localhost:13000/test"; opts["OPT_MULTI_HOST"] = true; opts["userName"]="user
"; opts["password"]="password
"; driver->connect(opts);
Port values are host specific. If a host is specified without a port number, the default port is used.
These rules apply:
If OPT_MULTI_HOST
is disabled and
multiple hosts are specified, an error occurs.
If OPT_MULTI_HOST
is disabled and a
single host that resolves to multiple hosts is specified,
the first host is used for backward compatibility.
If OPT_MULTI_HOST
is enabled and multiple
hosts are specified, one of them is randomly chosen as the
connection target. If the target fails, another host is
randomly chosen from those that remain. If all targets fail,
an error occurs.
The hostName
parameter can accept a URI
that contains a list of comma-separated hosts. The URI
scheme can be mysql://
, which works like
tcp://
. The URI scheme can also be
omitted, so the parameter can be a list of comma-separated
hosts.
The connect()
syntax that takes URI,
user, and password parameters does not permit multiple hosts
because in that case OPT_MULTI_HOST
is
disabled.
(WL #13322)
Connector/C++ now is compatible with MSVC 2019, while retaining compatibility with MSVC 2017:
Previously, Connector/C++ binary distributions were compatible with projects built using MSVC 2017 or 2015. Binary distributions now are compatible with projects built using MSVC 2019 (using either dynamic or static connector libraries) or MSVC 2017 (using dynamic connector libraries). Building using MSVC 2015 might work, but is not supported.
Previously, Connector/C++ source distributions could be built using MSVC 2017 or 2015. Source distributions now can be built using MSVC 2019 or 2017. Building using MSVC 2015 might work, but is not supported.
Previously, the MSI installer accepted the Visual C++ Redistributable for Visual Studio 2017 or 2015. The MSI installer now accepts the Visual C++ Redistributable for Visual Studio 2019 or 2017.
(WL #13563)
For X DevAPI or X DevAPI for C applications, Connector/C++ now provides options that enable specifying the permitted TLS protocols and ciphersuites for TLS connection negotiation:
TLS protocols must be chosen from this list: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. (TLSv1.3 requires that both the server and Connector/C++ be compiled with OpenSSL 1.1.1 or higher.)
Ciphersuite values must be IANA ciphersuite names.
TLS protocols and ciphersuites now may be specified in these contexts:
Connection strings permit tls-versions
and tls-ciphersuites
options. The
tls-versions
value is a list of one or
more comma-separated TLS protocol versions. The
tls-ciphersuites
value is a list of one
or more comma-separated ciphersuite names. Examples:
...?tls-versions=[TLSv1.3]&... ...?tls-versions=[TLSv1.2,TLSv1.3]&... ...?tls-ciphersuites=[ TLS_DHE_PSK_WITH_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256 ]&...
SessionSettings
objects permit
TLS_VERSIONS
and
TLS_CIPHERSUITES
options. Each value is
either a string containing one or more comma-separated items
or a container with strings (that is, any type that can be
iterated with a loop that yields string values).
Example of single string values:
Session s(..., TLS_VERSIONS, "TLSv1.2,TLSv1.3", TLS_CIPHERSUITES, "TLS_DHE_PSK_WITH_AES_128_GCM_SHA256,TLS_CHACHA20_POLY1305_SHA256", ...);
Example of string container values:
std::list<std::string> tls_versions = { "TLSv1.2", "TLSv1.3" }; std::list<std::string> ciphers = { "TLS_DHE_PSK_WITH_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256" }; Session s(..., TLS_VERSIONS, tls_versions TLS_CIPHERSUITES, ciphers, ...); Session s(..., TLS_VERSIONS, std::vector{"TLSv1.2","TLSv1.3"}, TLS_CIPHERSUITES, std::vector{"TLS_DHE_PSK_WITH_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256"}, ...);
mysqlx_session_option_set()
and friends
permit MYSQLX_OPT_TLS_VERSIONS
and
MYSQLX_OPT_TLS_CIPHERSUITES
session
option constants, together with the corresponding
OPT_TLS_VERSIONS()
and
OPT_TLS_CIPHERSUITES()
macros.
MYSQLX_OPT_TLS_VERSIONS
and
MYSQLX_OPT_TLS_CIPHERSUITES
accept a
string containing one or more comma-separated items.
Examples:
mysqlx_session_option_set(opts, ..., OPT_TLS_VERSIONS("TLSv1.2,TLSv1.3"), OPT_TLS_CIPHERSUITES( "TLS_DHE_PSK_WITH_AES_128_GCM_SHA256,TLS_CHACHA20_POLY1305_SHA256" ), ...)
For more information about TLS protocols and ciphersuites in MySQL, see Encrypted Connection TLS Protocols and Ciphers. (Bug #28964583, Bug #93299, WL #12755)
For X DevAPI or X DevAPI for C applications, when creating a new connection (given by a connection string or other means), if the connection data contains several target hosts that have no explicit priority assigned, the behavior of the failover logic now is the same as if all those target hosts have the same priority. That is, the next candidate for making a connection is chosen randomly from the remaining available hosts.
This is a change from previous behavior, where hosts with no explicit priority were assigned implicit decreasing priorities and tried in the same order as listed in the connection data. (WL #13497)
Connector/C++ now supports the use of DNS SRV records to specify multiple hosts:
Session and session-pool creation accepts a URI scheme of
mysqlx+srv://
that enables the DNS SRV
feature in connect strings. Example:
mysqlx+srv://_mysql._tcp.host1.example.com/db?options
For X DevAPI, mysqlx::Session
objects
permit a SessionOption::DNS_SRV
entry to
enable use of a DNS SRV record to specify available
services. Example:
mysqlx::Session sess( SessionOption::HOST, "_mysql._tcp.host1.example.com", SessionOption::DNS_SRV, true, SessionOption::USER, "user
", SessionOption::PWD, "password
");
Similarly, for X DevAPI for C, the
mysqlx_session_option_set()
function
permits an OPT_DNS_SRV()
option in the
argument list. Example:
mysqlx_session_option_set(opt, OPT_HOST("_mysql._tcp.host1.example.com"), OPT_DNS_SRV(true) OPT_USER("user
"), OPT_PWD("password
"), PARAM_END));
For applications that use the legacy JDBC API (that is, not
X DevAPI or X DevAPI for C), connection maps permit an
OPT_DNS_SRV
element. A map should specify
the host for SRV lookup as a full lookup name and without a
port. Example:
sql::ConnectOptionsMap opts; opts["hostName"] = "_mysql._tcp.host1.example.com"; opts["OPT_DNS_SRV"] = true; opts["userName"] = "user
"; opts["password"] = "password
"; driver->connect(opts);
In legacy applications, DNS SRV resolution cannot be enabled in URI connect strings because parameters are not supported in such strings.
(WL #13344, WL #13402)