MySQL Connector/C++ 8.0.17 has been released

Dear MySQL users,

MySQL Connector/C++ 8.0.17 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.17, see the “Generally Available (GA)
Releases” tab at

https://dev.mysql.com/downloads/connector/cpp/

==================================================

Changes in MySQL Connector/C++ 8.0.17 (2019-07-22, General
Availability)


     * Character Set Support

     * Compilation Notes

     * Configuration Notes

     * Function and Operator Notes

     * X DevAPI Notes

     * Functionality Added or Changed

     * Bugs Fixed

Character Set Support


     * Connector/C++ now supports the new utf8mb4_0900_bin
       collation added for the utf8mb4 Unicode character set in
       MySQL 8.0.17. For more information about this collation,
       see Unicode Character Sets
(https://dev.mysql.com/doc/refman/8.0/en/charset-unicode-sets.html).

Compilation Notes


     * Connector/C++ now compiles cleanly using the C++14
       compiler. This includes MSVC 2017. Binary distributions
       from Oracle are still built in C++11 mode using MSVC 2015
       for compatibility reasons.

Configuration Notes


     * The maximum permitted length of host names throughout
       Connector/C++ has been raised to 255 ASCII characters, up
       from the previous limit of 60 characters. Applications
       that expect host names to be a maximum of 60 characters
       should be adjusted to account for this change.

Function and Operator Notes


     * Connector/C++ now supports the OVERLAPS and NOT OVERLAPS
       operators for expressions on JSON arrays or objects:
expr OVERLAPS expr
expr NOT OVERLAPS expr

       Suppose that a collection has these contents:
[{
   “_id”: “1”,
   “list”: [1, 4]
 }, {
   “_id”: “2”,
   “list”: [4, 7]
}]

       This operation:
auto res = collection.find(“[1, 2, 3] OVERLAPS $.list”).fields(“_id”).
execute();
res.fetchAll();

       Should return:
[{ “_id”: “1” }]

       This operation:
auto res = collection.find(“$.list OVERLAPS [4]”).fields(“_id”).execut
e();
res.fetchAll();

       Should return:
[{ “_id”: “1” }, { “_id”: “2” }]

       An error occurs if an application uses either operator
       and the server does not support it.

X DevAPI Notes


     * For index specifications passed to the
       Collection::createIndex() method (for X DevAPI
       applications) or the mysqlx_collection_create_index()
       function (for X DevAPI for C applications), Connector/C++
       now supports indexing array fields. A single index field
       description can contain a new member name array that
       takes a Boolean value. If set to true, the field is
       assumed to contain arrays of elements of the given type.
       For example:
coll.createIndex(“idx”,
  R”({ “fields”: [{ “field”: “foo”, “type”: “INT”, “array”: true }] })

);

       In addition, the set of possible index field data types
       (used as values of member type in index field
       descriptions) is extended with type CHAR(N), where the
       length N is mandatory. For example:
coll.createIndex(“idx”,
  R”({ “fields”: [{ “field”: “foo”, “type”: “CHAR(10)” }] })”
);

Functionality Added or Changed


     * Previously, Connector/C++ reported INT in result set
       metadata for all integer result set columns, which
       required applications to check column lengths to
       determine particular integer types. The metadata now
       reports the more-specific TINYINT, SMALLINT, MEDIUMINT,
       INT, and or BIGINT types for integer columns. (Bug
       #29525077)

Bugs Fixed


     * Calling a method such as .fields() or .sort() on existing
       objects did not overwrite the effects of any previous
       call. (Bug #29402358)

     * When Connector/C++ applications reported connection
       attributes to the server upon establishing a new
       connection, some attributes were taken from the host on
       which Connector/C++ was built, not the host on which the
       application was being run. Now application host
       attributes are sent. (Bug #29394723)

     * Assignments of the following form on CollectionFind
       objects invoked a copy assignment operator, which was
       nonoptimal and prevented potential re-execution of
       statements using prepared statements:
find = find.limit(1);

       (Bug #29390170)

     * Legal constructs of this form failed to compile:
for (string id : res.getGeneratedIds()) { … }

       (Bug #29355100)

     * During build configuration, CMake could report an
       incorrect OpenSSL version. (Bug #29282948)

Enjoy and thanks for the support!

What is new in Connector/C++ 8.0

We are proud to announce that with version 8.0.11 the new MySQL Connector/C++ 8.0 series becomes GA! Connector/C++ 8.0 is your gateway to the new exciting features of MySQL Server 8.0 such as MySQL Document Store. It also lets you perform your usual database tasks in a simpler and more powerful way using new, modern APIs that bring to you the full advantage of modern C++ programming language.

The 8.0 series is a true milestone in the development of Connector/C++. We have not only added new APIs but also completely re-implemented the connector to create good foundation for future innovation and improvements.The new implementation of Connector/C++ is based entirely on the new X Protocol of MySQL Server 8.0 and is highly modular to allow rapid development of new features. For the first time we aligned our APIs with other MySQL connectors. Also, for the first time Connector/C++ is offering a plain C API for code written in C.

New APIs of Connector/C++ 8.0

Up to now Connector/C++ implemented a single API based on JDBC4 standard. While keeping the old API for backward compatibility, the 8.0 series introduces two new APIs that can be used for accessing MySQL database.

  • X DevAPI: a C++ implementation of the new, fluent CRUD API defined for accessing MySQL Document Store and relational data. The same API is also implemented by xshell and other connectors and provides a uniform interface to the MySQL database.
  • XAPI: a new plain C API with functionality similar to that of X DevAPI. This API allows applications written in plain C to have access to the new MySQL features such as Document Store (it might feel strange to have plain C API in a C++ connector but in fact plain C can be seen as a subset of the C++ language; also, placing both APIs in the same connector allows re-using common implementation components).

To give you a feeling of the new APIs, here is a sample code which opens a session, creates a document collection, adds a document to that collection and then lists documents in the collection.

The same thing implemented in plain C, using XAPI, looks as follows (for simplicity, error handling logic is omitted).

Note that the choice of the API is done by including appropriate public header: either <mysqlx/xdevapi.h> or <mysqlx/xapi.h>.

Apart from a CRUD style interface for accessing the MySQL Document Store, which is shared with other MySQL connectors, the new APIs give you full access to SQL and relational data, including transactions, parameter binding, row locking, convenient classes for representing query results and more. For example, the following code shows how to execute a plain SQL query against a relational table using X DevAPI. Similar code can be written using XAPI.

The new APIs can be used as a modern replacement for the previous, JDBC based API of Connector/C++ 1.1 and for the CAPI of the MySQL client library. The X DevAPI brings the advantage and power of modern C++ programming with support for language constructs such as iterators, range loops, method chaining, RAII, overloaded operators, custom type conversions etc. The plain C XAPI is also a major re-design of the traditional MySQL CAPI with automatic memory management, better separation of public interface from internal implementation and with functions for accessing the MySQL Document Store. Note however that these new APIs are implemented over X Protocol and for that reason they will not work with older versions of MySQL Server.

For more information check available documentation on MySQL Document Store and X DevAPI User Guide. See also reference documentation for the Connector/C++ implementation of X DevAPI and XAPI reference documentation.

Getting started with Connector/C++ 8.0

Installing Connector/C++ 8.0

To develop applications that use Connector/C++ 8.0 you need the following files

  • Public headers containing declarations for the APIs implemented by the connector.
  • Connector libraries that contain implementation of the APIs. There are actually two libraries shipped with Connector/C++ 8.0 – the main library with base name mysqlcppconn8, implementing the new APIs (X DevAPI and XAPI), and a legacy library with base name mysqlcppconn which is a drop-in replacement for the 1.1 connector library. Both static and shared variants of each library are shipped.

These files are distributed as TGZ or ZIP packages that you can unpack to the location of your choice. There are several options for how to use the connector during compile time and at run-time, all depending on the platform you are working on and whether you want to install connector locally or system-wide. Below is some basic information to get you started. For more details see usage instructions in the reference manual.

Building code which uses Connector/C++ 8.0

Building code that uses Connector/C++ requires correctly setting include path, so that connector’s public headers can be found by the compiler, and passing connector library to the linker invocation. Assuming that Connector/C++ was installed under $MYSQL_CPPCONN_DIR the include path should be set to $MYSQL_CPPCONN_DIR/include (for gcc use -I option, for MSVC the C/C++ > Additional Include Directories  project setting). After that X DevAPI or XAPI declarations can be loaded using #include <mysqlx/xdevapi.h> or #include <mysqlx/xapi.h> directive, respectively.

Note: The X DevAPI uses C++11 language features. For some compilers C++11 must be explicitly enabled. For example gcc needs option -std=c++11 to understand C++11. This is not required for MSVC nor for XAPI code (which is plain C)

Depending on the platform, the shared Connector/C++ library is named:

  • libmysqlcppconn8.so on Unix platforms (soname libmysqlcppconn8.so.1)
  • libmysqlcppconn8.dylib on the OSX platform (link name libmysqlcppconn8.1.dylib)
  • mysqlcppconn8-1-vs14.dll on Windows platforms (with import library vs14/mysqlcppconn8.lib)

You need to add this library to your compiler/linker invocation when building code that uses the connector  (for gcc add -lmysqlcppconn8 to the linker options, for MSVC add vs14/mysqlcppconn8.lib to Linker > Input > Additional Dependencies  setting of your project). You also need to specify path where the connector library can be found (for gcc use -L option, for MSVC Linker > Additional Library Directories  setting). Assuming that Connector/C++ was installed under $MYSQL_CONCPP_DIR the libraries can be found under $MYSQL_CONCPP_DIR/lib on 32-bit platforms and $MYSQL_CONCPP_DIR/lib64 on 64-bit platforms.

Example gcc invocation for building application with sources in app.cc might look as follows (assuming that environment variable MYSQL_CONCPP_DIR is set to the location where Connector/C++ was installed)

Due to ABI incompatiblities between different compiler versions, the code that uses Connector/C++ libraries should be built with the same compiler version as the connector itself. The information about compiler version used to build connector libraries can be found inside BUILDINFO.txt file distributed with the connector. In principle a different version of the compiler can be used provided that it is ABI compatible, but it is difficult to determine what versions of the compiler are ABI compatible with each other.

Running code which uses Connector/C++ 8.0

Code built against Connector/C++ depends on the shared connector library which must be found at run-time by the dynamic linker. It also requires OpenSSL libraries that are used by Connector/C++.  Here are example run-time dependencies shown by ldd for an application built with Connector/C++.

To be able to run such an application the dynamic linker must be able to find the connector library in its predefined locations. The easiest way of arranging this is to copy the shared connector library to the location of the executable. This method works for any operating system. Otherwise the exact way of registering Connector/C++ libraries with the dynamic linker depends on the operating system.

Note: For platforms such as Windows, that normally do not have OpenSSL libraries available, Connector/C++ packages include these libraries. Putting these libraries next to the connector ones usually ensures that the dynamic linker can find them at run-time.

Note: On Windows the executable will depend on the MSVC 2015 runtime DLLs, that need to be installed on the target system.

Note: Connector/C++ also ships static libraries that can be used to build applications that do not require shared connector libraries to be present on the target system. However, an application linked statically with Connector/C++ will still depend on shared OpenSSL libraries and on MSVC runtime in case of Windows.

In summary

MySQL 8 brings a lot of new, exciting features which allow you to work with your data in new ways, going beyond the traditional SQL paradigm. Connector/C++ 8.0 is a part of this story and it also invites you to exploring new ways of working with MySQL from your C++ or C code. It is a result of a long effort and we are eager to hear about your impressions of the new features we brought to you. Happy coding!