Configuration Notes

Security Notes

Spatial Data Support

Bugs Fixed

Binary distributions for this release of MySQL Connector/C++ were linked against libmysqlclient from MySQL 5.7.10, except for OS X 10.8/10.9, for which distributions were linked against MySQL 5.7.9. This enables Connector/C++ to take advantage of features present in recent client library versions. Some examples:

To build Connector/C++ from source, you must use either a General Availability version of MySQL 5.7 (5.7.9 or higher) or Connector/C 6.1.8 or higher. Set the MYSQL_DIR CMake option appropriately at configuration time as necessary. (Bug #22351273)

The linked OpenSSL library for Connector/C++ Commercial has been updated to version 1.0.1q. Issues fixed in the new OpenSSL version are described at http://www.openssl.org/news/vulnerabilities.html.

This change does not affect Oracle-produced MySQL Community builds of Connector/C++, which use the yaSSL library instead.

The required version of the Boost library for Connector/C++ builds has been raised to 1.56.0.

MySQL_Prepared_ResultSet::relative() failed to fetch the record due to a missing proxy->fetch() call. (Bug #21152054)

During Connector/C++ builds, the MySQL Server CXXFLAGS and CFLAGS values were used rather than the system default values. To specify explicitly to use the server values, enable the new USE_SERVER_CXXFLAGS CMake option. (Bug #77655, Bug #21391025)

Security Notes

Functionality Added or Changed

Bugs Fixed

Security Fix: Connector/C++ 1.1.6 Commercial upgrades the linked OpenSSL library to version 1.0.1m which has been publicly reported as not vulnerable to CVE-2015-0286. (CVE-2015-0286)

The std::auto_ptr class template is deprecated in C++11, and its usage has been replaced with boost::scoped_ptr/shared_ptr.

The CMAKE_ENABLE_C++11 CMake option has been added to permit enabling C++11 support. (Bug #75251)

Connector/C++ now provides macros to indicate the versions of libraries against which it was built: MYCPPCONN_STATIC_MYSQL_VERSION and MYCPPCONN_STATIC_MYSQL_VERSION_ID (MySQL client library version, string and numeric), and MYCPPCONN_BOOST_VERSION (Boost library version, numeric). (Bug #75250)

With defaultStatementResultType=FORWARD_ONLY and a row position after the last row, using getter methods such as getInt() or getString() resulted in a segmentation fault. (Bug #20085944)

For prepared statements, calling wasNull() before fetching data resulted in an assertion failure. (Bug #19938873)

Result sets from prepared statements were not freed. (Bug #18135088)

Connector/C++ failed to build against Boost-devel-1.41.0-25 on OLE6. (Bug #75063, Bug #20125824)

Configuration failed if the MYSQL_CONFIG_EXECUTABLE option was specified and the MySQL installation path contained the characters -m. Installation failed if the build directory was not in the top source directory. (Bug #73502, Bug #19447498)

For prepared statements, getString() did not return the fractional seconds part from temporal columns that had a fractional sections part. (Bug #68523, Bug #17218692)

For queries of the form SELECT MAX(bit_col) FROM table_with_bit_col, getString() returned an incorrect result. (Bug #66235, Bug #14520822)

For Connector/C++ builds from source, make install failed if only the static library had been built without the dynamic library. (Bug #52281, Bug #11759926)

Functionality Added or Changed

Bugs Fixed

MySQL_Prepared_Statement::getMoreResults() functionality has been implemented, so multiple result sets now can be fetched using a prepared statement. (Bug #19147677)

Connector/C++ now supports the defaultAuth, OPT_CONNECT_ATTR_DELETE, OPT_CONNECT_ATTR_RESET, OPT_LOCAL_INFILE, pluginDir, readDefaultFile, readDefaultGroup, and charsetDir connection options, which correspond to the MYSQL_DEFAULT_AUTH, MYSQL_OPT_CONNECT_ATTR_DELETE, MYSQL_OPT_CONNECT_ATTR_RESET, MYSQL_OPT_LOCAL_INFILE, MYSQL_PLUGIN_DIR, MYSQL_READ_DEFAULT_FILE, MYSQL_READ_DEFAULT_GROUP, and MYSQL_SET_CHARSET_DIR options for the mysql_options() C API function.

It is also possible to get and set the statement execution-time limit using the MySQL_Statement::getQueryTimeout() and MySQL_Statement::setQueryTimeout() methods. (Bug #73665, Bug #19479950)

These methods were added: Connection::isValid() checks whether the connection is alive, and Connection::reconnect() reconnects if the connection has gone down. (Bug #65640, Bug #14207722)

The Boost dependency was removed from the Connector/C++ API headers. These headers were using the boost::variant type, making it impossible to use Connector/C++ binaries without having Boost installed.

For installation from MSI packages, variant.h and version_info.h were missing from the include/cppconn folder. (Bug #19973637)

For several valid client options, getClientOption() did not return a value. (Bug #19940314)

A memory leak occurred when adding the OPT_CONNECT_ATTR_ADD parameter to the options list. (Bug #19938970)

getClientOption() raised an assertion if the specified option was not set at connect time. (Bug #19938922)

Several metadata flaws were corrected:

(Bug #19505348, Bug #19147897, Bug #19244736, Bug #19505421)

The LOCALHOST global variable was referenced at two places in C/C++ code, which could result in a double-free corruption error. (Bug #74616, Bug #19910311)

driver/version_info.h (containing version macros) was not included in the installed header files. (Bug #73795, Bug #19553971)

Several CMake issues were corrected:

(Bug #73427, Bug #19315635, Bug #19370844, Bug #19940663)

Connector/C++ issued a ping command every time isClosed() was called in a Connection, rather than just checking whether close() had been called earlier or when a fatal error occurred in an earlier operation. (Bug #69785, Bug #17186530)

With the result set type set to TYPE_FORWARD_ONLY, Statement::executeQuery() returns almost immediately, but MySQL_ResultSet::next() and MySQL_Prepared_ResultSet::next() returned false if the connection was lost rather than throwing an exception, making it impossible to distinguish loss of connection from normal end of the result set. MySQL_ResultSet::next() and MySQL_Prepared_ResultSet::next() now throw an exception when the connection is lost. (Bug #69031, Bug #18886278)

Connection objects shared internal state with Statement objects they spawned, preventing a connection close unless the Statement objects were destroyed first. A connection to the server now is closed by calling Connection::close() and invoking the Connection object destructor, without explicitly destroying the statement object.

Compilation Notes

Functionality Added or Changed

Bugs Fixed

Connector/C++ is now compiled and linked with Connector/C 6.1.5 rather than with libmysql.

Binary distributions of this Connector/C++ release were compiled using Boost 1.54.0. If you compile this Connector/C++ release from source, you must also use that Boost version.

Connector/C++ now supports the following connection options: sslVerify (boolean), sslCRL (string), and sslCRLPath (string). These correspond to the MYSQL_OPT_SSL_VERIFY_SERVER_CERT, MYSQL_OPT_SSL_CRL, and MYSQL_OPT_SSL_CRLPATH options for the mysql_options() C API function. (Bug #18461451)

Connector/C++ has new methods to provide schema, table, and column character set and collation metadata for result sets:

(Bug #72698, Bug #18803345)

Connector/C++ now supports the OPT_CONNECT_ATTR_ADD option, which accepts an std::map argument. This option corresponds to the MYSQL_OPT_CONNECT_ATTR_ADD option for mysql_options4(). (Bug #72697, Bug #18803313)

Connector/C++ now supports a useLegacyAuth connection option, which corresponds to the MYSQL_SECURE_AUTH option for the mysql_options() C API function, except that the sense is the logical negation. For example, to disable secure authentication, pass a useLegacyAuth value of true. (Bug #69492, Bug #16970753)

MySQL_ResultSetMetaData::getColumnTypeName() returned UNKNOWN for LONG_BLOB fields. (Bug #72700, Bug #18803414)

Definitions for character sets and collations were added (utf8mb4 in particular). (Bug #71606, Bug #18193771)

Connector/C++ version-information methods have been revised to return the correct values. (Bug #66975, Bug #14680878)

Functionality Added or Changed

Bugs Fixed

Connector/C++ now supports an OPT_ENABLE_CLEARTEXT_PLUGIN connection option. If true, it enables the client-side cleartext authentication plugin. This client-side plugin is required, for example, for accounts that use the PAM server-side authentication plugin. (Bug #16520952)

MySQL_ConnectionMetaData::getBestRowIdentifier() considered only PRIMARY KEY columns usable for row identifiers. It now also considers UNIQUE NOT NULL columns suitable for the same purpose. (Bug #16277170)

Connector/C++ applications now can handle connecting to the server using an account for which the password had expired. Connector/C++ now supports three new connection options:

A new file driver/mysql_error.h is being added to the MSI package. This file defines an enum DRIVER_ERROR, which contains the definition of deCL_CANT_HANDLE_EXP_PWD.

In addition to the preceding changes, these problems with Statement::executeUpdate were fixed:

For example code showing how to use the new options, see the file test/unit/bugs/bugs.cpp in the Connector/C++ distribution. (Bug #67325, Bug #15936764)

Functionality Added or Changed

Bugs Fixed

Connector/C++ is now built against libmysqlclient from MySQL 5.5.27, enabling support of authentification plugins and IPv6.

URI format has been extended to better fit IPv6 addresses. You can now use [] to separate the host part of the URI.

Added new method ResultSetMetaData::isNumeric() and implemented it in all classes that subclass from it.

Added MySQL_Connection::getLastStatementInfo() which returns back the value of the mysql_info() function of the MySQL Client Library (libmysqlclient).

Compiling with Visual Studio 2010 could fail with compilation errors if the source contained a #include <stdint.h> line. The errors were typically of the form cannot convert from 'type1' to 'type2'. (Bug #14113387, Bug #60307)

Fixed stores(Lower|Mixed)Case(Quoted)Identifiers methods.

A statement that did not raise any warning could return warnings from a previously executed statement.

DatabaseMetaData::getSQLKeywords() updated to match MySQL 5.5. Note that Connector/C++, just like Connector/J, returns the same list for every MySQL database version.

Functionality Added or Changed

Bugs Fixed

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);

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.

LDFLAGS, CXXFLAGS and CPPFLAGS are now checked from the environment for every binary generated.

The connection map property OPT_RECONNECT was changed to be of type boolean from long long.

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::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().

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)

Using Prepared Statements caused corruption of the heap. (Bug #45048)

Missing includes when using GCC 4.4. Note that GCC 4.4 is not yet in use for any official 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 a Prepared Statements performance issue. Reading large result sets was slow.

Fixed bug in ResultSetMetaData for statements and prepared statements, getScale and getPrecision returned incorrect results.

Functionality Added or Changed

Bugs Fixed

The interface of sql::ConnectionMetaData, sql::ResultSetMetaData and sql::ParameterMetaData was modified to have a protected destructor. As a result the client code has no need to destruct the metadata objects returned by the connector. Connector/C++ handles the required destruction. This enables statements such as:

connection->getMetaData->getSchema();

This avoids potential memory leaks that could occur as a result of losing the pointer returned by getMetaData().

Improved memory management. Handling of potential memory leak situations is more robust.

Changed the interface of sql::Driver and sql::Connection so they accept the options map by alias instead of by value.

Changed the return type of sql::SQLException::getSQLState() from std::string to const char * to be consistent with std::exception::what().

Implemented getResultSetType() and setResultSetType() for Statement. Uses TYPE_FORWARD_ONLY, which means unbuffered result set and TYPE_SCROLL_INSENSITIVE, which means buffered result set.

Implemented getResultSetType() for PreparedStatement. The setter is not implemented because currently PreparedStatement cannot do refetching. Storing the result means the bind buffers will be correct.

Added the option defaultStatementResultType to MySQL_Connection::setClientOption(). Also, the method now returns sql::Connection *.

Added Result::getType(). Implemented for the three result set classes.

Enabled tracing functionality when building with Microsoft Visual C++ 8 and later, which corresponds to Microsoft Visual Studio 2005 and later.

Added better support for named pipes, on Windows. Use pipe:// and add the path to the pipe. Shared memory connections are currently not supported.

A bug was fixed in MySQL_Connection::setSessionVariable(), which had been causing exceptions to be thrown.

Functionality Added or Changed

Bugs Fixed

An installer was added for the Windows operating system.

Minimum CMake version required was changed from 2.4.2 to 2.6.2. The latest version is required for building on Windows.

metadataUseInfoSchema was added to the connection property map, which enables control of the INFORMATION_SCHEMA for metadata.

Implemented MySQL_ConnectionMetaData::supportsConvert(from, to).

Added support for Connector/C.

Introduced ResultSetMetaData::isZerofill(), which is not in the JDBC specification.

A bug was fixed in all implementations of ResultSet::relative() which was giving a wrong return value although positioning was working correctly.

A leak was fixed in MySQL_PreparedResultSet, which occurred when the result contained a BLOB column.

Functionality Added or Changed

Bugs Fixed

Added new tests in test/unit/classes. Those tests are mostly about code coverage. Most of the actual functionality of the driver is tested by the tests found in test/CJUnitPort.

New data types added to the list returned by DatabaseMetaData::getTypeInfo() are FLOAT UNSIGNED, DECIMAL UNSIGNED, DOUBLE UNSIGNED. Those tests may not be in the JDBC specification. However, due to the change you should be able to look up every type and type name returned by, for example, ResultSetMetaData::getColumnTypeName().

MySQL_Driver::getPatchVersion introduced.

Major performance improvements due to new buffered ResultSet implementation.

Addition of test/unit/README with instructions for writing bug and regression tests.

Experimental support for STLPort. This feature may be removed again at any time later without prior warning! Type cmake -L for configuration instructions.

Added properties enabled methods for connecting, which add many connect options. This uses a dictionary (map) of key value pairs. Methods added are Driver::connect(map), and Connection::Connection(map).

New BLOB implementation. sql::Blob was removed in favor of std::istream. C++'s IOStream library is very powerful, similar to PHP's streams. It makes no sense to reinvent the wheel. For example, you can pass a std::istringstream object to setBlob() if the data is in memory, or just open a file std::fstream and let it stream to the DB, or write its own stream. This is also true for getBlob() where you can just copy data (if a buffered result set), or stream data (if implemented).

Implemented ResultSet::getBlob() which returns std::stream.

Fixed MySQL_DatabaseMetaData::getTablePrivileges(). Test cases were added in the first unit testing framework.

Implemented MySQL_Connection::setSessionVariable() for setting system variables such as sql_mode.

Implemented MySQL_DatabaseMetaData::getColumnPrivileges().

cppconn/datatype.h has changed and is now used again. Reimplemented the type subsystem to be more usable - more types for binary and nonbinary strings.

Implementation for MySQL_DatabaseMetaData::getImportedKeys() for MySQL versions before 5.1.16 using SHOW, and above using INFORMATION_SCHEMA.

Implemented MySQL_ConnectionMetaData::getProcedureColumns().

make package_source now packs with bzip2.

Re-added getTypeInfo() with information about all types supported by MySQL and the sql::DataType.

Changed the implementation of MySQL_ConstructedResultSet to use the more efficient O(1) access method. This should improve the speed with which the metadata result sets are used. Also, there is less copying during the construction of the result set, which means that all result sets returned from the metadata functions will be faster.

Introduced, internally, sql::mysql::MyVal which has implicit constructors. Used in mysql_metadata.cpp to create result sets with native data instead of always string (varchar).

Renamed ResultSet::getLong() to ResultSet::getInt64(). resultset.h includes typdefs for Windows to be able to use int64_t.

Introduced ResultSet::getUInt() and ResultSet::getUInt64().

Improved the implementation for ResultSetMetaData::isReadOnly(). Values generated from views are read only. These generated values don't have db in MYSQL_FIELD set, while all normal columns do have.

Implemented MySQL_DatabaseMetaData::getExportedKeys().

Implemented MySQL_DatabaseMetaData::getCrossReference().

Bug fixed in MySQL_PreparedResultSet::getString(). Returned string that had real data but the length was random. Now, the string is initialized with the correct length and thus is binary safe.

Corrected handling of unsigned server types to return correct values.

Fixed handling of numeric columns in ResultSetMetaData::isCaseSensitive to return false.

Functionality Added or Changed

Bugs Fixed

Implemented getScale(), getPrecision() and getColumnDisplaySize() for MySQL_ResultSetMetaData and MySQL_Prepared_ResultSetMetaData.

Changed ResultSetMetaData methods getColumnDisplaySize(), getPrecision(), getScale() to return unsigned int instead of signed int.

DATE, DATETIME and TIME are now being handled when calling the MySQL_PreparedResultSet methods getString(), getDouble(), getInt(), getLong(), getBoolean().

Reverted implementation of MySQL_DatabaseMetaData::getTypeInfo(). Now unimplemented. In addition, removed cppconn/datatype.h for now, until a more robust implementation of the types can be developed.

Implemented MySQL_PreparedStatement::setNull().

Implemented MySQL_PreparedStatement::clearParameters().

Added PHP script examples/cpp_trace_analyzer.php to filter the output of the debug trace. Please see the inline comments for documentation. This script is unsupported.

Implemented MySQL_ResultSetMetaData::getPrecision() and MySQL_Prepared_ResultSetMetaData::getPrecision(), updating example.

Added new unit test framework for JDBC compliance and regression testing.

Added test/unit as a basis for general unit tests using the new test framework, see test/unit/example for basic usage examples.

Fixed MySQL_PreparedStatementResultSet::getDouble() to return the correct value when the underlying type is MYSQL_TYPE_FLOAT.

Fixed bug in MySQL_ConnectionMetaData::getIndexInfo(). The method did not work because the schema name wasn't included in the query sent to the server.

Fixed a bug in MySQL_ConnectionMetaData::getColumns() which was performing a cartesian product of the columns in the table times the columns matching columnNamePattern. The example example/connection_meta_schemaobj.cpp was extended to cover the function.

Fixed bugs in MySQL_DatabaseMetaData. All supportsCatalogXXXXX methods were incorrectly returning true and all supportsSchemaXXXX methods were incorrectly returning false. Now supportsCatalogXXXXX returns false and supportsSchemaXXXXX returns true.

Fixed bugs in the MySQL_PreparedStatements methods setBigInt() and setDatetime(). They decremented the internal column index before forwarding the request. This resulted in a double-decrement and therefore the wrong internal column index. The error message generated was:

setString() ... invalid "parameterIndex"

Fixed a bug in getString(). getString() is now binary safe. A new example was also added.

Fixed bug in FLOAT handling.

Fixed MySQL_PreparedStatement::setBlob(). In the tests there is a simple example of a class implementing sql::Blob.

sql::mysql::MySQL_SQLException was removed. The distinction between server and client (connector) errors, based on the type of the exception, has been removed. However, the error code can still be checked to evaluate the error type.

Support for (n)make install was added. You can change the default installation path. Carefully read the messages displayed after executing cmake. The following are installed:

Driver Manager was removed.

Added ConnectionMetaData::getSchemas() and Connection::setSchema().

ConnectionMetaData::getCatalogTerm() returns not applicable, there is no counterpart to catalog in Connector/C++.

Added experimental GCov support, cmake -DMYSQLCPPCONN_GCOV_ENABLE:BOOL=1

All examples can be given optional connection parameters on the command line, for example:

examples/connect tcp://host:port user pass database

or

examples/connect unix:///path/to/mysql.sock user pass database

Renamed ConnectionMetaData::getTables: TABLE_COMMENT to REMARKS.

Renamed ConnectionMetaData::getProcedures: PROCEDURE_SCHEMA to PROCEDURE_SCHEM.

Renamed ConnectionMetaData::getPrimaryKeys(): COLUMN to COLUMN_NAME, SEQUENCE to KEY_SEQ, and INDEX_NAME to PK_NAME.

Renamed ConnectionMetaData::getImportedKeys(): PKTABLE_CATALOG to PKTABLE_CAT, PKTABLE_SCHEMA to PKTABLE_SCHEM, FKTABLE_CATALOG to FKTABLE_CAT, FKTABLE_SCHEMA to FKTABLE_SCHEM.

Changed metadata column name TABLE_CATALOG to TABLE_CAT and TABLE_SCHEMA to TABLE_SCHEM to ensure JDBC compliance.

Introduced experimental CPack support, see make help.

All tests changed to create TAP compliant output.

Renamed sql::DbcMethodNotImplemented to sql::MethodNotImplementedException

Renamed sql::DbcInvalidArgument to sql::InvalidArgumentException

Changed sql::DbcException to implement the interface of JDBC's SQLException. Renamed to sql::SQLException.

Converted Connector/J tests were added.

MySQL Workbench 5.1 changed to use Connector/C++ for its database connectivity.

New directory layout.