MySQL Connector/C++  8.0.15
MySQL connector library for C and C++ applications
Building Connector/C++ 8.0


To build Connector/C++, the following tools and libraries are required:

Build configuration

Only out-of-source builds are supported. To configure a build, execute cmake in a dedicated build location (not in the source directory):

$ cmake <Connector/C++ source location>

By default Connector/C++ is configured to build using OpenSSL libraries that should be installed on the build system. To build connector with OpenSSL installed in a non-standard location or to build it with WolfSSL, use the option

where <path> is the location of OpenSSL or WolfSSL installation (see Building with WolfSSL for more information).

If Boost libraries are required and cmake cannot find them, specify the correct location using the option:

By default a shared library is built. To build a static library, use the option:

The build system generated by cmake has install target which, by default, installs to /usr/local/mysql/connector-c++-8.0 (<User home>/MySQL/"MySQL Connector C++ 8.0" on Windows). To change this default install location use the option:

Building Connector/C++ with WolfSSL

Connector/C++ can be built with WolfSSL instead of the default OpenSSL libraries. If built that way, the WolfSSL code is statically linked in and there are no external dependencies on WolfSSL libraries. This is in contrast to the default build with OpenSSL libraries which are linked dynamically and become an external dependency of the connector library (see Using Connector/C++ 8.0)

Building Connector/C++ with WolfSSL library requires downloading the WolfSSL source package version 3.14.0 or newer from here: After setting -DWITH_SSL=<path to WolfSSL sources> Connector/C++ will build WolfSSL libraries and use them instead of OpenSSL.

Option WITH_SSL can be also used to point to a non-standard location where OpenSSL libraries are installed. Cmake detects whether WITH_SSL points to WolfSSL sources. If this is not the case, it will assume that OpenSSL should be used and that WITH_SSL points to OpenSSL install location.

Building and testing

A build can be started with the following cmake invocation in the build location:

$ cmake --build . --config CCC

where CCC is the build configuration to use, such as Release or Debug. It is also possible to omit the --config CCC option in which case the default Debug configuration will be used.

In what follows the same build configuration CCC must be used for all the steps such as installing the connector or building the test program.

After a successful build, the build location should contain the Connector/C++ shared library:

The number 1 in the library name is the major ABI version of the library. It is part of the library name so that different versions of the library can be used at the same time on a single system.

On Unix and macOS also appropriate symbolic links are created. On Windows the import library for the DLL is created at CCC/mysqlcppconn8.lib (the CCC/ subdirectory is named the same as the build configuration used).

In the case of a static library build, the output library names are:


To perform basic testing of the connector functionality, build and run one of the test programs included in the testapp/ subdirectory of the source location.

Before building test programs, Connector/C++ must be installed first. To install Connector/C++ to the default location (which could be set during the build configuration using CMAKE_INSTALL_PREFIX option), execute the following command in the build location:

$ cmake --build . --target install --config CCC
It is possible to change the CMAKE_INSTALL_PREFIX setting before doing the installation. To change it, issue the following command before building the install target:
$ cmake -DCMAKE_INSTALL_PREFIX=<new location> .

To build test programs, pick a build location and issue the following commands there:

$ cmake -DWITH_CONCPP=<Connector/C++ install location> <source location>/testapp
$ cmake --build . --config CCC

This should create the devapi_test and xapi_test executables in the run/ subdirectory of the build location. If testing static connector, pass the -DBUILD_STATIC=ON option when configuring test applications.

On Windows, if the connector was built with the static runtime by specifying the -DSTATIC_MSVCRT=yes configuration option (see below), the same option must be added to the build configuration of test programs.
The 32/64-bit Windows cmake generator ("Visual Studio 14 2015 Win64" vs "Visual Studio 14 2015") used to build test applications must match the one used to build the connector.

Before running test programs, ensure that a MySQL Server instance is running with X Plugin loaded into it. The easiest way of arranging this is to use the script from the MySQL Server distribution. In the mysql-test/ subdirectory of that distribution, invoke this command:

$ perl --start-and-exit --mysqld=--plugin-load=mysqlx

This should start a test server instance with X plugin loaded into it. When started like this, the plugin will listen on port 13009 instead of the standard 33060 one.

Now you can run one of the test programs and see the output similar to the one presented below. Test programs accept a connection-string argument. If the server was started as described above, run the test program with the following connection string as a parameter:

$ run/devapi_test mysqlx://root@
$ run/xapi_test mysqlx://root@

This invocation uses the root user account without any password and assumes that there is a test schema in the server (these assumptions hold for a server started using

If everything goes well, devapi_test should produce output similar to this:

Creating session on mysqlx://root@ ...
Session accepted, creating collection...
Inserting documents...
- added doc with id: AA71B4BF6B72E511BD76001E684A06F0
- added doc with id: 2885B4BF6B72E511BD76001E684A06F0
- added doc with id: 3492B4BF6B72E511BD76001E684A06F0
- added doc with id: myuuid-1
Fetching documents...
doc#0: {"_id": "AEFD9C44EB77E5116134001E684A06F0", "age": 3, "date": {"day": 20, "month": "Apr"}, "name": "baz"}
field `_id`: AEFD9C44EB77E5116134001E684A06F0
field `age`: 3
field `date`: <document>
field `name`: baz
name: baz
- date field
date `day`: 20
date `month`: Apr
month: Apr
day: 20
doc#1: {"_id": "A0ABC08DAABAD1110C120800273BD115", "age": 2, "name": "bar", "toys": ["car", "ball"]}
field `_id`: A0ABC08DAABAD1110C120800273BD115
field `age`: 2
field `name`: bar
field `toys`: <array with 2 element(s)>
name: bar
- toys:

Building legacy C++ JDBC4 library

Apart from the new APIs introduced in version 8.0 of the connector (X DevAPI and X DevAPI for C), Connector/C++ also supports the legacy API based on JDBC4. This legacy API is implemented as a separate library with base name mysqlcppconn as opposed to mysqlcppconn8 library implementing the new APIs.

To build the legacy library specify the -DWITH_JDBC=ON option during the cmake configuration step. This option is disabled by default. If specified, additional build dependencies must be satisfied:

The code implementing the legacy connector is inside the jdbc/ subdirectory of the source tree. If sources are obtained from a git repository, this subdirectory must be fetched separately as a git sub-module. Invoke git submodule update --init to populate the contents of the jdbc/ subdirectory.

If everything goes well, after building the connector the build location should contain an additional legacy connector library:

If building static libraries, the static legacy library has name:

It is possible to build an additional test application jdbc_test for testing the legacy connector library. To do this, pass the -DWITH_JDBC=ON cmake option when configuring the build of test applications. Also, MYSQL_DIR or MYSQL_CONFIG_EXECUTABLE and WITH_BOOST must be set if cmake cannot find the required dependencies.

The connection-string argument that the jdbc_test application accepts must be in the form specified by the JDBC API. The user name is passed as the second argument. For example:

$ run/jdbc_test tcp:// root

Windows Notes

Connector/C++ uses the C++11 language and for that reason it is not possible to build it with Microsoft Visual Studio 2010 or earlier.

On Windows one can request that Connector/C++ uses the static runtime library (the /MT* compiler option) by setting the cmake option -DSTATIC_MSVCRT=yes. This might be necessary if code which uses Connector/C++ also uses the static runtime. If building the static library in this mode, the -mt suffix will be added to its name to distinguish it from a library built in /MD mode.

Selecting a cmake generator such as "Visual Studio 14 2015 Win64" vs "Visual Studio 14 2015" selects the 64-bit or 32-bit platform for which the connector is built. An application which uses Connector/C++ must be built for the same platform as the connector.

An application built using 'Debug', 'Release' or other MSVC build configuration needs to link against a Connector/C++ library built with the same configuration (as determined by the --config=CCC cmake option described above). The linker places the library built using the CCC configuration in a CCC/ subdirectory of the build location. Thus, when building an application that uses the connector library, one has to point the linker at the location containing a compatible build of the connector.

macOS Notes

On macOS, Connector/C++ is built using the clang compiler with the libc++ C++ runtime library. The same runtime library should be used by applications that link against Connector/C++. To arrange this, pass -stdlib=libc++ to the compiler and the linker invocations. Another option is to set the required deployment target and then the compiler defaults are changed accordingly. To define the deployment target, set the environment variable MACOSX_DEPLOYMENT_TARGET to the requested OS X version. Binary distributions of Connector/C++ are built with MACOSX_DEPLOYMENT_TARGET set to 10.12.

Building Connector/C++ with gcc or its libstdc++ runtime has not been tested and there is no support in the build system for using an alternative C++ runtime library.