3.22 Changes in MySQL Connector/C++ 8.0.16 (2019-04-25, General Availability)

Character Set Support

Connector/C++ supports all Unicode character sets for connections to servers for MySQL 8.0.14 and higher, but previously had Unicode support limited to the utf8 character set for servers older than MySQL 8.0.14. Connector/C++ now supports all Unicode character sets for older servers, including utf8mb4, utf16, utf16le, utf32, and ucs2. (Bug #28966038, WL #12196)

Compilation Notes

Thanks to Daniël van Eeden, who contributed a code change to use the stdbool.h header file rather than a bool typedef. (Bug #29167120, Bug #93803)
Thanks to Daniël van Eeden, who contributed a code change to use lib instead of lib64 on 64-bit FreeBSD. (Bug #29167098, Bug #93801)
Previously, for Connector/C++ applications that used the legacy JDBC API, source files had to use this set of #include directives:
```
#include <jdbc/mysql_driver.h>
#include <jdbc/mysql_connection.h>
#include <jdbc/cppconn/*.h>
```
Now a single #include directive suffices:
```
#include <mysql/jdbc.h>
```
(WL #12786)

Configuration Notes

Thanks to Daniël van Eeden, who contributed a code change to build the documentation as part of the all target if Connector/C++ is configured with -DWITH_DOC=ON. (Bug #29167107, Bug #93802)
Previously, for Connector/C++ 8.0 applications that use the legacy JDBC connector, only static linking to the MySQL client library was supported. The MYSQLCLIENT_STATIC_LINKING and MYSQLCLIENT_STATIC_BINDING CMake options are now available to permit dynamic linking. By default, MYSQLCLIENT_STATIC_LINKING is enabled, to use static linking to the client library. Disable this option to use dynamic linking. If MYSQLCLIENT_STATIC_LINKING is enabled, MYSQLCLIENT_STATIC_BINDING may also be used. If MYSQLCLIENT_STATIC_BINDING is enabled (the default), Connector/C++ is linked to the shared MySQL client library. Otherwise, the shared MySQL client library is loaded and mapped at runtime. (WL #12730)
Connector/C++ 8.0 configuration now requires a minimum CMake version of 3.0. (WL #12753)

Packaging Notes

Connector/C++ debug packages are now available for Linux and Windows. The packages enable symbolic debugging using tools such as gdb on Linux and windbg on Windows, as well as obtaining symbolic information about connector code locations from application crash dumps. Use of the debug packages requires that you have installed and configured the Connector/C++ sources. (Bug #29117059, Bug #93645, Bug #26128420, Bug #86415, WL #12263)
For improved GitHub friendliness, Community Connector/C++ source distributions now include a CONTRIBUTING.md markdown file that contains guidelines intended to be helpful to contributors. (WL #12791)
The Protobuf sources bundled in the Connector/C++ source tree were updated to Protobuf 3.6.1. (Only the parts needed for Connector/C++ are included, to reduce compilation time.) (WL #12889)

Prepared Statement Notes

For X DevAPI and X DevAPI for C, performance for statements that are executed repeatedly (two or more times) is improved by using server-side prepared statements for the second and subsequent executions. This happens internally; applications need take no action and API behavior should be the same as previously. For statements that change, repreparation occurs as needed. Providing different data values or different OFFSET or LIMIT clause values does not count as a change. Instead, the new values are passed to a new invocation of the previously prepared statement. (WL #12149)

X DevAPI Notes

For X DevAPI and X DevAPI for C applications, Connector/C++ now supports the ability to send connection attributes (key-value pairs that application programs can pass to the server at connect time). Connector/C++ defines a default set of attributes, which can be disabled or enabled. In addition, applications can specify attributes to be passed in addition to the default attributes. The default behavior is to send the default attribute set.
- For X DevAPI applications, specify connection attributes as a connection-attributes parameter in a connection string, or by using a SessionOption::CONNECTION_ATTRIBUTES option for the SessionSettings constructor.
  The connection-attributes parameter value must be empty (the same as specifying true), a Boolean value (true or false to enable or disable the default attribute set), or a list or zero or more key=value specifiers separated by commas (to be sent in addition to the default attribute set). Within a list, a missing key value evaluates as an empty string. Examples:
```
"mysqlx://user@host?connection-attributes"
"mysqlx://user@host?connection-attributes=true"
"mysqlx://user@host?connection-attributes=false"
"mysqlx://user@host?connection-attributes=[attr1=val1,attr2,attr3=]"
"mysqlx://user@host?connection-attributes=[]"
```
  The SessionOption::CONNECTION_ATTRIBUTES option value must be a Boolean value (true or false to enable or disable the default attribute set), or a DbDoc or JSON string (to be sent in addition to the default attribute set). Examples:
```
  Session sess(..., SessionOption::CONNECTION_ATTRIBUTES, false);
  Session sess(..., SessionOption::CONNECTION_ATTRIBUTES, attr_doc );
  Session sess(..., SessionOption::CONNECTION_ATTRIBUTES,
    R"({ "attr1": "val1", "attr2" : "val2" })"
  );
```
- For X DevAPI for C applications, specify connection attributes using the OPT_CONNECTION_ATTRIBUTES() macro for the mysqlx_session_option_set() function. The option value must be null (to disable the default attribute set) or a JSON string (to be sent in addition to the default attribute set). Examples:
```
mysqlx_session_option_set(opts, OPT_CONNECTION_ATTRIBUTES(nullptr));
mysqlx_session_option_set(opts,
  OPT_CONNECTION_ATTRIBUTES("{ \"attr1\": \"val1\", \"attr2\" : \"val2\" }")
);
```
Application-defined attribute names cannot begin with _ because such names are reserved for internal attributes.
If connection attributes are not specified in a valid way, an error occurs and the connection attempt fails.
For general information about connection attributes, see Performance Schema Connection Attribute Tables. (WL #12495)

X DevAPI for C Notes

The signatures for several X DevAPI for C functions have been changed to enable better error information to be returned to applications by means of a mysqlx_error_t handle. These functions are affected:
```
mysqlx_client_t*
mysqlx_get_client_from_url(
  const char *conn_string,
  const char *client_opts,
  mysqlx_error_t **error
)
 
mysqlx_client_t*
mysqlx_get_client_from_options(
  mysqlx_session_options_t *opt,
  mysqlx_error_t **error
)

mysqlx_session_t*
mysqlx_get_session(
  const char *host, int port,
  const char *user, const char *password,
  const char *database,
  mysqlx_error_t **error
)

mysqlx_session_t*
mysqlx_get_session_from_url(
  const char *conn_string,
  mysqlx_error_t **error
)

mysqlx_session_t*
mysqlx_get_session_from_options(
  mysqlx_session_options_t *opt,
  mysqlx_error_t **error
)

mysqlx_session_t *
mysqlx_get_session_from_client(
  mysqlx_client_t *cli,
  mysqlx_error_t **error
)
```
The final argument in each case is a mysqlx_error_t handle into which Connector/C++ stores error information. If the argument is a null pointer, Connector/C++ ignores it. The application is responsible to free non-null handles by passing them to mysqlx_free().
The signature for mysqlx_free() has also been changed to accept a void * argument so that it can accept a handle of any type. Consequently, other type-specific free functions, such as mysqlx_free_options(), are no longer needed and are deprecated.
The preceding modifications change the Connector/C++ API, which has these implications:
- The modifications change the ABI, so the ABI version is changed from 1 to 2. This changes the connector library names.
- X DevAPI for C applications to be compiled against the new API must be modified to use the new function signatures. (X DevAPI applications should build without change.)
- Applications built against the old ABI will not run with the new connector library.
- The API change and ABI version change do not affect the legacy JDBC interface, so library names for the legacy JDBC connector library do not change and legacy application need not be changed.
- It is possible to install both the old and new libraries. However, installers may remove the old libraries, so they may need to be re-added manually after installing the new libraries.
(WL #11654, WL #12751)

Functionality Added or Changed

Thanks to Daniël van Eeden, who contributed documentation for the mysqlx_column_get_collation() function and various corrections to the developer documentation. (Bug #29123114, Bug #93665, Bug #29115285, Bug #93640, Bug #29122490, Bug #93663)
Connector/C++ now has improved support for resetting sessions in connection pools. Returning a session to the pool drops session-related objects such as temporary tables, session variables, and transactions, but the connection remains open and authenticated so that reauthentication is not required when the session is reused. (WL #12497)

Bugs Fixed

Previously, for the SSL_MODE_VERIFY_IDENTITY connection option, Connector/C++ checked whether the host name that it used for connecting matched the Common Name value in the certificate but not the Subject Alternative Name value. Now, if used with OpenSSL 1.0.2 or higher, Connector/C++ checks whether the host name matches either the Subject Alternative Name value or the Common Name value in the server certificate. (Bug #28964313, Bug #93301)
After repeated calls, mysqlx_get_session_from_client() could hang. (Bug #28587287)
The SessionSettings/ClientSettings iterator implementation was incomplete. (Bug #28502574)