MySQL Connector/C++ Release Notes
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)
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>
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.
Connector/C++ 8.0 configuration now requires a minimum CMake version of 3.0.
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)
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.
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.)
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.
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.
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.
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.
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)