Dear MySQL users,
MySQL Connector/C++ 8.0.16 is a new release version of the MySQL Connector/C++ 8.0 series.
Connector/C++ 8.0 can be used to access MySQL implementing Document Store or in a traditional way, using SQL queries. It allows writing both C++ and plain C applications using X DevAPI and X DevAPI for C. It also supports the legacy API of Connector/C++ 1.1 based on JDBC4.
To learn more about how to write applications using X DevAPI, see “X DevAPI User Guide” at
https://dev.mysql.com/doc/x-devapi-userguide/en/
See also “X DevAPI Reference” at
https://dev.mysql.com/doc/dev/connector-cpp/devapi_ref.html
and “X DevAPI for C Reference” at
https://dev.mysql.com/doc/dev/connector-cpp/xapi_ref.html
For generic information on using Connector/C++ 8.0, see
https://dev.mysql.com/doc/dev/connector-cpp/
For general documentation about how to get started using MySQL as a document store, see
http://dev.mysql.com/doc/refman/8.0/en/document-store.html
To download MySQL Connector/C++ 8.0.16, see the “Generally Available (GA) Releases” tab at
https://dev.mysql.com/downloads/connector/cpp/
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)
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>
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.
* Connector/C++ 8.0 configuration now requires a minimum
CMake version of 3.0.
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)
* For improved GitHub friendliness, Community Connector/C++
source distributions now include a CONTRIBUTING.md
markdown file. CONTRIBUTING.md 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.)
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.
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
(http://dev.mysql.com/doc/refman/8.0/en/performance-schema-connection-attribute-tables.html).
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.
Functionality Added or Changed
* Thanks to Daniël van Eeden, who contributed documentation
for the mysqlx_column_get_collation() function and
various corrections in 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.
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)
Enjoy and thanks for the support!
On Behalf of Oracle/MySQL Release Engineering Team,
Kent Boortz