MySQL Connector/C++  8.0.11
MySQL connector library for C and C++ applications
Using Connector/C++ 8.0

Connector/C++ 8.0 implements new APIs for accessing document store of MySQL Server 8: X DevAPI for applications written in C++11 and XAPI for applications written in plain C. The same APIs can be also used to execute traditional SQL queries. Connector/C++ 8.0 also implements the legacy C++ API based on JDBC4 which is backward compatible with version 1.1 of the connector.

The choice of the API is done by including appropriate public headers. For X DevAPI include:

#include <mysqlx/xdevapi.h>

For XAPI include:

#include <mysqlx/xapi.h>

And for legacy API include:

#include <jdbc/mysql_driver.h>
#include <jdbc/mysql_connection.h>
#include <jdbc/cppconn/*.h>

The preceding include directives work under the assumption that the include path contains $MYSQL_CPPCONN_DIR/include, where $MYSQL_CPPCONN_DIR is the location where Connector/C++ was installed. Pass the -I $MYSQL_CPPCONN_DIR/include option on the compiler invocation line to ensure this.

Note
The legacy code that uses Connector/C++ 1.1 has includes of the form
#include <mysql_driver.h>
#include <mysql_connection.h>
#include <cppconn/*.h>
To build such code with Connector/C++ 8 without modifying it, add $MYSQL_CPPCONN_DIR/include/jdbc to the include path.

The X DevAPI uses C++11 language features. For that reason enable C++11 support in the compiler using the -std=c++11 option when building code that uses X DevAPI. This is not needed for XAPI (which is a plain C API) nor for the legacy JDBC API which is based on plain C++.

Note
The legacy API requires Boost headers. The location of these headers needs to be added to the include path to correctly compile legacy code. Only the headers from Boost are needed – the Boost libraries are not used during linking phase.

Using the shared library

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

This library implements the new X DevAPI and XAPI. Connector/C++ 8.0 also includes the legacy connector library libmsysqlcppconn(.so/.dylib/.dll) which implements the legacy JDBC4 API.

To build code that uses new APIs, add -lmysqlcppconn8 to the linker options (add -lmysqlcppconn when building legacy code). This requires that $MYSQL_CONCPP_DIR/lib or $MYSQL_CONCPP_DIR/lib64 (the latter on a 64-bit platform) is added to the linker path (-L $MYSQL_CPPCONN_DIR/lib64 linker option).

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 which versions of the compiler are ABI compatible with each other.

An example Makefile to build an application which uses Connector/C++ X DevAPI, with sources in app.cc is shown below:

MYSQL_CONCPP_DIR= ...
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn8
CXXFLAGS = -std=c++11
app : app.cc

It generates the following compiler invocation:

g++ -std=c++11 -I .../include -L .../lib64 app.cc -lmysqlcppconn8 -o app
Note
For linking against the legacy C++ JDBC4 library the library name is -lmysqlcppconn. Also, the option -std=c++11 could be omitted unless the user code utilizes C++11.

The connector can be also used with plain C code written against XAPI. An example Makefile to build a plain C application from sources in app.c might look like this:

MYSQL_CONCPP_DIR= ...
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn8
app : app.c

which generates the following compiler invocation:

cc -I .../include -L .../lib64 app.c -lmysqlcppconn8 -o app

Note that the resulting code, even though it is compiled as plain C, will depend on the C++ runtime (libstdc++).

Note
When running an application which uses the shared Connector/C++ library, the library and its runtime dependencies must be found by the dynamic linker. The dynamic linker must be properly configured to find Connector/C++ libraries and their dependencies.
Connector/C++ libraries built by MySQL depend on OpenSSL libraries. The latter must be installed on the system in order to run code that links against Connector/C++ libraries. Another option is to put OpenSSL libraries in the same location as Connector/C++. In this case the dynamic linker should find them next to the connector library. See also Windows Notes and macOS Notes.
It is possible to build Connector/C++ libraries without OpenSSL, using internal implementation of TLS connections. In this case the OpenSSL libraries are not required at runtime.

Using the static library

It is possible to link your application with the static connector library. This way there is no runtime dependency on the connector and the resulting binary can run on systems where Connector/C++ is not installed.

Note
However, even when linking statically, the resulting code still depends on OpenSSL libraries and all other runtime dependencies of the Connector/C++ library.

When compiling code which is linked with the connector library statically, define STATIC_CONCPP macro before including Connector/C++ public headers. This macro adjusts API declarations in the headers for usage with the static library.

Note
For the legacy API, one defines CPPCONN_PUBLIC_FUNC as empty macro instead (the same way as when using static Connector/C++ 1.1 library)

The static library names are:

The legacy static library names are libmysqlcppconn-static.a and mysqlcppconn-static.lib, respectively.

An example Makefile to build a C++ application that links to the connector library statically is shown below:

MYSQL_CONCPP_DIR= ...
CPPFLAGS = -DSTATIC_CONCPP -I $(MYSQL_CONCPP_DIR)/include
LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread
CXXFLAGS = -std=c++11
app : app.cc

It generates the following compiler invocation:

g++ -std=c++11 -DSTATIC_CONCPP -I .../include app.cc .../lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread -o app
Note
For linking against the legacy C++ JDBC4 library the library name is -lmysqlcppconn. Also, the option -std=c++11 could be omitted unless the user code utilizes C++11.

Note that we need to add to the compile line the OpenSSL libraries and the pthread library on which Connector/C++ code depends. Otherwise linker reports unresolved symbols.

Note
Clearly, OpenSSL libraries are not needed if Connector/C++ is built without them. But Connector/C++ built and distributed by MySQL depends on OpenSSL.
The exact list of libraries required by Connector/C++ library depends on the platform. For example on Solaris socket, rt and nsl libraries might be needed.

When building plain C code it is important to additionally take care of connector's dependency on the C++ runtime, which is introduced by the connector library even though the code that uses it is plain C. One approach is to ensure that a C++ linker is used to build the final code. This approach is taken in the example Makefile below:

MYSQL_CONCPP_DIR= ...
CPPFLAGS = -DSTATIC_CONCPP -I $(MYSQL_CONCPP_DIR)/include
LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread
LINK.o = $(LINK.cc) # use C++ linker
app : app.o

With this Makefile the build process has two steps: first the application source in app.c is compiled using plain C compiler, then the final executable is linked using the C++ linker which takes care of the dependency on the C++ runtime:

cc -DSTATIC_CONCPP -I .../include -c -o app.o app.c
g++ -DSTATIC_CONCPP -I .../include app.o .../libmysqlcppconn8-static.a -lssl -lcrypto -lpthread -o app

Another approach is to use plain C compiler and linker, but add the C++ runtime library libstdc++ as an explicit input to the linker:

MYSQL_CONCPP_DIR= ...
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include
LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread -lstdc++
app : app.c

With this Makefile the compiler is invoked as follows:

cc -DSTATIC_CONCPP -I .../include app.c .../libmysqlcppconn8-static.a -lssl -lcrypto -lpthread -lstdc++ -o app
Note
Even if the application that uses Connector/C++ is written in plain C, the final executable will depend on the C++ runtime which must be installed on the target computer on which the application will run.

macOS Notes

The binary distribution of Connector/C++ for macOS is compiled using the macOS native clang compiler. For that reason an application that uses the connector should be built with the same clang compiler.

The clang compiler can use two different implementations of the C++ runtime library: either the native libc++ or the GNU libstdc++ library. It is important that an application uses the same runtime implementation as Connector/C++, that is, the native libc++. To ensure that, the -stdlib=libc++ option should be passed to the compiler and the linker invocations.

An example Makefile for macOS build is shown below.

MYSQL_CONCPP_DIR= ...
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn8
CXX = clang++ -stdlib=libc++
CXXFLAGS = -std=c++11
app : app.cc

Binary packages for macOS include OpenSSL libraries which are required by code linked with the connector. These libraries are installed in the same location as the connector libraries and should be found there by the dynamic linker.

Windows Notes

On Windows applications can be built in different modes (also called build configurations) which determine the type of the runtime library that is used by the final executable. An application can be built in a debug or a release mode. Then it can be built in a 32-bit or a 64-bit mode. Also, one can choose between the static (/MT) or the dynamic (/MD) runtime. Different versions of the MSVC compiler also use different versions of the runtime.

It is important to ensure that the compiler version and the build mode of an application matches the same parameters used when building the connector library. This is to ensure that the runtime library used by the connector and the application are the same.

The binary distribution of Connector/C++ 8.0 ships libraries built in the release mode using dynamic runtime (/MD). The libraries are built with MSVC 2015 (the exact compiler version can be found in BUILDINFO.txt file included in the package). Consequently the code that uses these libraries must be built with the same version of MSVC and in the '/MD' mode. To build your code in different mode you must build the connector library in the same mode first.

Note
When linking dynamically, it is possible to build your code in the debug mode even though the connector libraries are built in the release mode. In that case it will not be possible to step inside connector code during a debug session. To be able to do that, or to build in debug mode while linking to the connector statically, you must built the connector in the debug mode first (see ...).

There are separate 32-bit and 64-bit packages, each keeping libraries in lib/ and lib64/ folder, respectively. Package name also contains -vs14 suffix to indicate that the library is built with MSVC 2015 compiler. The same vsNN convention is used in library names to enable using libraries built with different versions of MSVC on the same system.

The dynamic connector library has name mysqlcppconn8-1-vs14.dll with import library vs14/mysqlcppconn8.lib in the vs14/ sub-folder. This sub-folder also contains the static version of the library vs14/mysqlcppconn8-static.lib. The 1 in the dynamic library name is the major ABI version number (in the future this will help using compatibility libraries with old ABI together with new libraries having a different ABI). The legacy connector library has name mysqlcppconn-7-vs14.dll with import library vs14/mysqlcppconn.lib and static version vs14/mysqlcppconn-static.lib.

When building code that uses Connector/C++ libraries add $MYSQL_CPPCONN_DIR/include as additional include folder and $MYSQL_CPPCONN_DIR/{lib,lib64}/vs14 as additional library folder in the project configuration. To use the dynamic library add mysqlcppconn8.lib to linker inputs (mysqlcppconn.lib for legacy code). For static linking add mysqlcppconn8-static.lib instead (mysqlcppconn-static.lib for legacy code). If linking statically, the linker must find the import libraries for the required OpenSSL libraries. They are present in the $MYSQL_CPPCONN_DIR/{lib,lib64}/vs14 folder if the connector was installed from the binary package provided by MySQL and the corresponding OpenSSL DLLs are present in the main library folder, next to the connector DLLs.

Note
An application which uses the shared connector library must be able to locate it, as well as its dependencies such as OpenSSL, at the runtime. The common way of arranging this is to put the required DLLs in the same location as the executable.