MySQL :: MySQL Connector/C++ Release Notes :: Changes in MySQL Connector/C++ 8.0.19 (2020-01-13, General Availability)

Error Handling

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)

Legacy (JDBC API) Notes

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)

Packaging Notes

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)

X DevAPI Notes

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)

Functionality Added or Changed

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)

Bugs Fixed

Connector/C++ failed to compile using Clang on Linux. (Bug #30450484)
Connector/C++ set the transaction isolation level to REPEATABLE READ at connect time, regardless of the current server setting. (Bug #22038313, Bug #78852, Bug #30294415)