MySQL Connector/C++ Changelog

What's new in MySQL Connector/C++ 8.1.0

Jul 19, 2023

Packaging Notes:
ZSTD sources bundled in the Connector/C++ source tree are upgraded to ZSTD 1.5.5. (Bug #35360566)
The Connector/C++ static library is most effective when the installed package is specific to the platform on which the final application is built. Accordingly, the following static connector libraries are no longer included in the generic Linux packages:
lib64/libmysqlcppconn-static.a
lib64/libmysqlcppconn8-static.a
Functionality Added or Changed:
For applications that use the legacy JDBC API (that is, not X DevAPI or X DevAPI for C) on Linux systems and use OpenTelemetry instrumentation, the connector adds query and connection spans to the trace generated by application code and forwards the current OpenTelemetry context to the server. By default, the connector generates spans only when an instrumented application links with the required OpenTelemetry SDK libraries and configures the trace exporter to send trace data to some destination. If the application code does not use instrumentation, then the legacy connector does not use it either.
Connector/C++ supports a new connection property option, OPT_OPENTELEMETRY, which has these values:
OTEL_DISABLED
OTEL_PREFERRED (default)
The OPT_OPENTELEMETRY option also accepts a Boolean value in which false corresponds to OTEL_DISABLED. false is the only accepted Boolean value for this option; setting it to true has no meaning and emits an error. For more information, see OpenTelemetry Tracing Support. (WL #15625)

New in MySQL Connector/C++ 8.0.33 (Apr 19, 2023)

Compilation Notes:
To simplify building the legacy JDBC connector with Linux distributions that do not ship static libraries, the MYSQLCLIENT_STATIC_LINKING default now is OFF (use dynamic linking to the client library). Previously, the default setting was ON and the binary distributions from Oracle are still built with static linking. (WL #15466)
Binary distributions from Oracle are built in C++17 mode. When building Connector/C++ from sources, the compilation now fails if the compiler used does not support C++17. To compile Connector/C++ applications that use X DevAPI (or if the code uses C++17), enable C++17 support in the compiler using the -std=c++17 option. (WL #15429)
Connector/C++ now compiles cleanly using Clang on Windows. (WL #15290)
Packaging Notes:
ZSTD sources bundled in the Connector/C++ source tree are upgraded to ZSTD 1.5.0. (Bug #34983529)
LZ4 sources bundled in the Connector/C++ source tree are upgraded to LZ4 1.9.4. (Bug #34983380)
ZLIB sources bundled in the Connector/C++ source tree are upgraded to ZLIB 1.2.13 to match the server. (Bug #34888141)
RapidJSON sources bundled in the Connector/C++ source tree are upgraded to RapidJSON 1.1.0 to match the server. (Bug #34842662)
Pluggable Authentication:
The Connector/C++ implementation of the authentication_oci_client plugin (together with libmysqlclient) now enables using a security-token file to support ephemeral key-pair authentication when integration with an external identity provider is needed for classic MySQL protocol connections. The Oracle Cloud Infrastructure CLI generates the ephemeral key pair and security token.
In addition, applications that use the legacy JDBC API now can set the new OPT_OCI_CLIENT_CONFIG_PROFILE connection option to specify which profile in the configuration file to use for authentication. It defaults to the [DEFAULT] profile. (WL #15481)
Functionality Added or Changed:
The Connector/C++ legacy JDBC connector now identifies itself through the following new connection attributes (in addition to the connection attributes obtained from the libmysql client library by default):
_connector_version to indicate the connector version (for example, 8.0.33).
_connector_license to indicate the license type of the connector, either GPL-2.0 or Commercial.
_connector_name with a constant value of mysql-connector-cpp.
The new attributes are not configurable by applications. Instead, the connector sets all of the attribute values, which it determines automatically after connecting to the server. If the libmysql client library or MySQL Server version being used lack support for query attributes, then returning related connection-attribute errors is not possible.
For general information about connection attributes, see Performance Schema Connection Attribute Tables. (WL #15425)
Bugs Fixed:
X DevAPI: Operations attempting to modify an entire document, for example,
coll.modify("_id = 1").set("$", R"({ "name": "bar" })").execute();
emitted a server error rather than modifying the document. An error is expected when passing in a string. To modify an entire document, the caller should pass in a DbDoc() document. For example:
coll.modify("_id = 1").set("$", DbDoc(R"({ "name": "bar" })")).execute();
(Bug #35046616)
X DevAPI: When a connection was made to MySQL Router, rather than directly to the server, closing a session using mysqlx_session_close was not possible. Now, the connector no longer waits for a reply to the call before closing the session. (Bug #107693, Bug #34338937)
Minimum CMake version required was changed to 3.12 from the previous version, which was deprecated and produced warnings. (Bug #20422957)

New in MySQL Connector/C++ 8.0.32 (Jan 26, 2023)

Functionality Added or Changed:
Removed distutils support, which is deprecated as of Python 3.10 and removed in Python 3.12.
Adopted type hint enforcement for function and class attributes with mypy; this is compliant with PEP 8 for module mysql.connector. The integration includes a git pre-commit hook for mypy.
On Windows, added a kerberos_auth_mode connection option that's set to either "SSPI" (default) or "GSSAPI". This allows choosing between SSPI and GSSAPI at runtime for the authentication_kerberos_client authentication plugin on Windows. Previously, only the SSPI mode was supported on Windows. For general usage information, see Kerberos Pluggable Authentication. This connection is ignored on other platforms, such as Linux, as they only support GSSAPI.
Limitation: GSSAPI can't be used with the pure Python implementation on Windows using authentication with a username and password, a limitation with the C library used by the python-gssapi package used by the pure Python implementation of Connector/Python.
Bugs Fixed:
Using USE_TZ=True in the Django settings would raise this exception: ValueError: Not naive datetime (tzinfo is already set).
Removed debug messages that showed authentication data. (Bug #34695103)
Updated the protobuf version requirement to version >= 3.11.0, <=3.20.3.
Connecting to MariaDB could fail with an unsupported character set because the default MySQL character collection is MySQL 8.0 specific. Now the 5.7 character set is used by default, but is switched to a 8.0 character set if the queried server is version 8.0.
Incorrect MySQLCursor.statement values were returned with cursor.execute(query_string, multi=True) under the following conditions: The query string contained two or more queries seperated by a semicolon, and the non-first query used a literal or identifier containing either an odd number of backticks, quotes, or double quotes.
On Windows, changed the security support provider (SSP) from Kerberos to Negotiate. Using Negotiate will then select either Kerberos or NTLM as the SSP.
On Windows, the Connector/Python MSI did would not detect and install with Python 3.11. The workaround is to use pip install mysql-connector-python instead.
When using a prepared cursor, if a datetime column contained 00:00:00 as the time, a Python date object was returned instead of datetime.
The MySQLCursor.executemany() method failed to batch insert data since the regular expression (RE) sentinel did not detect batch cases correctly; this meant using the one-on-one insert instead, which led to decreased performance.
Added a new init_command connection option; an SQL query that's immediately executed after the connection is established.
Russian characters were not handled correctly by the c-ext version's X DevAPI driver. String values are now encoded to their byte string representation before being sent to protobuf.
When fetching results from a prepared cursor using the pure Python implementation, it would fail if the VARBINARY column contained bytes that could not be decoded. The bytes are now returned if they cannot be decoded.
Fixed multiple reference leaks and removed redundant code.
The cursors (both pure and c-ext versions) uses a single SELECT query to retrieve procedure result parameters after a procedure call; but one SET call was used per parameter when setting the input parameters. This was optimized to always use a single SET call for one or multiple parameters.
Improved warning handling throughout the connector.
Added a new MySQLCursorPreparedDict class option that is similar to MySQLCursorPrepared; the difference is that the former returns a fetched row as a dictionary where column names are used as keys while the latter returns a row as a traditional record (tuple).
Enable the use of dictionaries as parameters in prepared statements using the '(param)s' format as placeholders.
Using MySQLConverter.escape() on datetime objects raised this error: TypeError: an integer is required. Now it does not attempt to escape values that are not bytes or string types.
Not all parameters were added to the INSERT statement when using INSERT IGNORE with cursor.executemany().

New in MySQL Connector/C++ 8.0.30 (Jul 26, 2022)

New in MySQL Connector/C++ 8.0.28 (Apr 26, 2022)

New in MySQL Connector/C++ 8.0.27 (Oct 19, 2021)

New in MySQL Connector/C++ 8.0.25 (Jul 20, 2021)

New in MySQL Connector/C++ 8.0.24 (Apr 20, 2021)

Connection Management Notes:
Previously, for client applications that use the legacy JDBC API (that is, not X DevAPI or X DevAPI for C), if the connection to the server was not used within the period specified by the wait_timeout system variable and the server closed the connection, the client received no notification of the reason. Typically, the client would see Lost connection to MySQL server during query (CR_SERVER_LOST) or MySQL server has gone away (CR_SERVER_GONE_ERROR).
In such cases, the server now writes the reason to the connection before closing it, and client receives a more informative error message, The client was disconnected by the server because of inactivity. See wait_timeout and interactive_timeout for configuring this behavior. (ER_CLIENT_INTERACTION_TIMEOUT).
The previous behavior still applies for client connections to older servers and connections to the server by older clients.
For connections made using X Plugin, if client with a connection to a server remains idle (not sending to the server) for longer than the relevant X Plugin timeout setting (read, write, or wait timeout), X Plugin closes the connection. If any of these timeouts occur, the plugin returns a warning notice with the error code ER_IO_READ_ERROR to the client application.
For such connections, X Plugin now also sends a warning notice if a connection is actively closed due to a server shutdown, or by the connection being killed from another client session. In the case of a server shutdown, the warning notice is sent to all authenticated X Protocol clients with open connections, with the ER_SERVER_SHUTDOWN error code. In the case of a killed connection, the warning notice is sent to the relevant client with the ER_SESSION_WAS_KILLED error code, unless the connection was killed during SQL execution, in which case a fatal error is returned with the ER_QUERY_INTERRUPTED error code.
If connection pooling is used and a connection close notice is received in a session as a result of a server shutdown, all other idle sessions that are connected to the same endpoint are removed from the pool.
Client applications can use the warning notices to display to users, or to analyze the reason for disconnection and decide whether to attempt reconnection to the same server, or to a different server.
Packaging Notes:
Connector/C++ packages now include sasl2 modules due to connection failures for accounts that use the authentication_ldap_sasl authentication plugin. (Bug #32175836)
Bugs Fixed:
Upon connecting to the server, Connector/C++ executed a number of SHOW [SESSION] VARIABLES statements to retrieve system variable values. Such statements involve locking in the server, so they are now avoided in favor of SELECT @@var_name statements.
Additionally, Connector/C++ was trying to fetch the value of the max_statement_time system variable, which has been renamed to max_execution_time. Connector/C++ now uses the correct variable name, with the result that getQueryTimeout() and setQueryTimeout() now work properly for both Statement and Prepared Statement objects. (Bug #28928712, Bug #93201)
DatabaseMetaData.getProcedures() failed when the metadataUseInfoSchema connection option was false. (Bug #24371558)

New in MySQL Connector/C++ 8.0.19 (Jan 13, 2020)

Error Handling:
If an application tries to obtain a result set from a statement that does not produce one, an exception occurs. For applications that do not catch such exceptions, Connector/C++ now produces a more informative error message to indicate why the exception occurred. (Bug #28591814, Bug #92263)
Legacy (JDBC API) Notes:
For applications that use the legacy JDBC API (that is, not X DevAPI or X DevAPI for C), it is now possible when creating a new session to specify multiple hosts to be tried until a successful connection is established. A list of hosts can be given in the session creation options.
X DevAPI Notes;
For X DevAPI or X DevAPI for C applications, Connector/C++ now provides options that enable specifying the permitted TLS protocols and ciphersuites for TLS connection negotiation:
TLS protocols must be chosen from this list: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. (TLSv1.3 requires that both the server and Connector/C++ be compiled with OpenSSL 1.1.1 or higher.)
Ciphersuite values must be IANA ciphersuite names.
For X DevAPI or X DevAPI for C applications, when creating a new connection (given by a connection string or other means), if the connection data contains several target hosts that have no explicit priority assigned, the behavior of the failover logic now is the same as if all those target hosts have the same priority. That is, the next candidate for making a connection is chosen randomly from the remaining available hosts.
This is a change from previous behavior, where hosts with no explicit priority were assigned implicit decreasing priorities and tried in the same order as listed in the connection data.
Functionality Added or Changed:
Connector/C++ now supports the use of DNS SRV records to specify multiple hosts:
Session and session-pool creation accepts a URI scheme of mysqlx+srv:// that enables the DNS SRV feature in connect strings.
For X DevAPI, mysqlx::Session objects permit a SessionOption::DNS_SRV entry to enable use of a DNS SRV record to specify available services.
Similarly, for X DevAPI for C, the mysqlx_session_option_set() function permits an OPT_DNS_SRV() option in the argument list.
For applications that use the legacy JDBC API (that is, not X DevAPI or X DevAPI for C), connection maps permit an OPT_DNS_SRV element. A map should specify the host for SRV lookup as a full lookup name and without a port.
Bugs Fixed:
Connector/C++ failed to compile using Clang on Linux. (Bug #30450484)
Connector/C++ set the transaction isolation level to REPEATABLE READ at connect time, regardless of the current server setting. (Bug #22038313, Bug #78852, Bug #30294415)

New in MySQL Connector/C++ 8.0.18 (Jan 13, 2020)

New in MySQL Connector/C++ 8.0.17 (Jul 22, 2019)

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.
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").execute();
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)

New in MySQL Connector/C++ 8.0.16 (Apr 25, 2019)

New in MySQL Connector/C++ 8.0.15 (Feb 1, 2019)

New in MySQL Connector/C++ 8.0.14 (Jan 21, 2019)

Configuration Notes:
These CMake options have been added to enable more fine-grained specification of installation directories. All are relative to CMAKE_INSTALL_PREFIX:
CMAKE_INSTALL_LIBDIR: Library installation directory.
CMAKE_INSTALL_INCLUDEDIR: Header file installation directory.
CMAKE_INSTALL_DOCDIR: Documentation installation directory.
Packaging Notes:
Previously, MySQL Connector/C++ binary distributions included a BUILDINFO.txt file that contained information about the build environment used to produce the distribution. Binary distributions now include a file named INFO_BIN that provides similar information, and an INFO_SRC file that provides information about the product version and the source repository from which the distribution was produced. Source distributions include the INFO_SRC file only.
MySQL Connector/C++ now is compatible with MSVC 2017, while retaining compatibility with MSVC 2015:
Previously, Connector/C++ binary distributions were compatible with projects built using MSVC 2015. Binary distributions now are compatible with projects built using MSVC 2017 or 2015. DLLs have a -vs14 suffix in their names to reflect that they are compatible with MSVC 2015, but can also be used in MSVC 2017 projects.
Previously, Connector/C++ source distributions could be built using MSVC 2015. Source distributions now can be built using MSVC 2017 or 2015.
Previously, the MSI installer accepted the Visual C++ Redistributable for Visual Studio 2015. The MSI installer now accepts the Visual C++ Redistributable for Visual Studio 2017 or 2015.
Installers for Connector/C++ are now available as Debian packages. See Installing Connector/C++ from a Binary Distribution.
X DevAPI Notes:
Connector/C++ now provides collection counting methods for applications that use X DevAPI for C:
mysqlx_collection_count(): The number of documents in a collection without filtering.
mysqlx_table_count(): The number of rows in a table without filtering.
mysqlx_get_count(): The number of remaining cached rows held at the moment. After a row is consumed by a fetch function, the number of cached rows decreases.
mysqlx_get_count() is similar in all respects to mysqlx_store_result() except that the behavior differs after fetching rows when reaching zero number of rows in the cache:
mysqlx_get_count() returns zero through the parameter and finishes with RESULT_OK.
mysqlx_store_result() does not return anything through the parameter (which remains unchanged) and finishes with RESULT_ERROR.

New in MySQL Connector/C++ 8.0.11 (May 1, 2018)

Functionality Added or Changed:
Incompatible Change: When documents without an _id attribute are added to a collection, the server now automatically generates IDs for them. The server determines the ID format, which should be considered opaque from the API perspective (they are no longer UUID-based). As before, no _id attribute is generated if a document already contains one. User-provided document IDs must not conflict with IDs of other documents in the collection.
This capability requires a MySQL 8.0 GA server. If the server does not support document ID generation, the document-add operation returns an error indicating that document IDs were missing.
For X DevAPI, the generated IDs resulting from a document-add operation can be obtained using the new Result.getGeneratedIds() method, which returns a list. For XAPI, the generated IDs can be obtained using the new mysqlx_fetch_generated_id() function, which returns IDs one by one for successive calls, until it returns NULL to indicate no more generated IDs are available. For both X DevAPI and XAPI, document IDs specified explicitly in added documents are not returned.
Incompatibility: The getGeneratedIds() method replaces getDocumentId() and getDocumentIds(), which are now removed. The mysqlx_fetch_generated_id() function replaces mysqlx_fetch_doc_id(), which is now removed.
A patch operation has been implemented that enables specifying a JSON-like object that describes the changes to apply to documents in a collection.
For X DevAPI, the CollectionModify operation supports a new patch() clause for patching documents. For XAPI, there are two new functions: mysqlx_collection_modify_patch() directly executes patching on documents in a collection that satisfy given criteria. mysqlx_set_modify_patch() adds a patch operation to a modify statement created with the mysql_collection_modify_new() function.
For connections to the server made using the legacy JDBC API (that is, not made using X DevAPI or XAPI), Connector/C++ 8.0 now supports an OPT_GET_SERVER_PUBLIC_KEY connection option that enables requesting the RSA public key from the server. For accounts that use the caching_sha2_password or sha256_password authentication plugin, this key can be used during the connection process for RSA key-pair based password exchange with TLS disabled. This capability requires a MySQL 8.0 GA server, and is supported only for Connector/C++ built using OpenSSL.
Bugs Fixed:
Single-document methods such as Collection.replaceOne() did not accept expr() as the document specification, but instead treated it as a plain JSON string. (Bug #27677910)
Compiling X DevAPI and XAPI test programs failed with an error. (Bug #27610760)
Connecting with an incorrect SSL_CA value could result in a memory leak. (Bug #27434254)
For debug builds, specifying a document as _id raised an assertion rather than producing an error. (Bug #27433969)

New in MySQL Connector/C++ 1.1.3 (May 16, 2013)

New in MySQL Connector/C++ 1.1.2 (May 16, 2013)

New in MySQL Connector/C++ 1.1.1 (May 16, 2013)

New in MySQL Connector/C++ 1.1.0 (May 16, 2013)

Functionality Added or Changed:
Incompatible Change: API incompatible change: ConnectPropertyVal is no longer a struct by a typedef that uses boost::variant. Code such as:
sql::ConnectPropertyVal tmp;
tmp.str.val=passwd.c_str();
tmp.str.len=passwd.length();
connection_properties["password"] = tmp;
Should be changed to:
connection_properties["password"] = sql::ConnectPropertyVal(passwd);
Connection::getClientOption(const sql::SQLString & optionName, void * optionValue) now accepts the optionName values metadataUseInfoSchema, defaultStatementResultType, defaultPreparedStatementResultType, and characterSetResults. In the previous version only metadataUseInfoSchema was permitted. The same options are available for Connection::setClientOption().
get_driver_instance() is now only available in dynamic library builds - static builds do not have this symbol. This was done to accommodate loading the DLL with LoadLibrary or dlopen. If you do not use CMake for building the source code you will need to define mysqlcppconn_EXPORTS if you are loading dynamically and want to use the get_driver_instance() entry point.
Connection map property OPT_RECONNECT was changed to be of type boolean from long long.
LDFLAGS, CXXFLAGS and CPPFLAGS are now checked from the environment for every binary generated.
Instances of std::auto_ptr have been changed to boost::scoped_ptr. Scoped array instances now use boost::scoped_array. Further, boost::shared_ptr and boost::weak_ptr are now used for guarding access around result sets.
Bugs Fixed:
Using Prepared Statements caused corruption of the heap. (Bug #45048)
Certain header files were incorrectly present in the source distribution. The fix excludes dynamically generated and platform specific header files from source packages generated using CPack. (Bug #45846)
CMake generated an error if configuring an out of source build, that is, when CMake was not called from the source root directory. (Bug #45843)
Missing includes when using GCC 4.4. Note that GCC 4.4 is not yet in use for any official MySQL Connector/C++ builds. (Bug #44931)
A bug was fixed in Prepared Statements. The bug occurred when a stored procedure was prepared without any parameters. This led to an exception. (Bug #44931)
Fixed bug in ResultSetMetaData for statements and prepared statements, getScale and getPrecision returned incorrect results.
Fixed a Prepared Statements performance issue. Reading large result sets was slow.