Part 3- How to install mysql-connector-c++ in Windows | Mac | SunOS | RHEL-Red Hat/Fedora Linux?

Connecting to MySQL

A connection to MySQL is established by retrieving an instance of sql::Connection from a sql::mysql::MySQL_Driver object. A sql::mysql::MySQL_Driver object is returned by sql::mysql::MySQL_Driver::get_mysql_driver_instance().

sql::mysql::MySQL_Driver *driver;
sql::Connection *con;

driver = sql::mysql::MySQL_Driver::Instance();
con = driver->connect("tcp://127.0.0.1:3306", "user", "password");

delete con;

Make sure that you free the sql::Connection object as soon as you do not need it any more. But do not explicitly free the driver object!

(See also: examples/connect.cpp)

[edit] Running a simple query

For running simple queries you can use the methods sql::Statement::execute(), sql::Statement::executeQuery() and sql::Statement::executeUpdate(). sql::Statement::execute() should be used if your query does not return a result set or if your query returns more than one result set. See the examples/ directory for more on this.

sql::mysql::MySQL_Driver *driver;
sql::Connection *con;
sql::Statement *stmt

driver = sql::mysql::get_mysql_driver_instance();
con = driver->connect("tcp://127.0.0.1:3306", "user", "password");

stmt = con->createStatement();
stmt->execute("USE " EXAMPLE_DB);
stmt->execute("DROP TABLE IF EXISTS test");
stmt->execute("CREATE TABLE test(id INT, label CHAR(1))");
stmt->execute("INSERT INTO test(id, label) VALUES (1, 'a')");

delete stmt;
delete con;

Note that you have to free sql::Statement and sql::Connection objects explicitly using delete.

(See also: example/statement.cpp)

[edit] Fetching results

The API for fetching result sets is identical for (simple) statments and prepared statements. If your query returns one result set you should use sql::Statement::executeQuery() or sql::PreparedStatement::executeQuery() to run your query. Both methods return sql::ResultSet objects. The preview version does buffer all result sets on the client to support cursors.

// ...
sql::Connection *con;
sql::Statement *stmt
sql::ResultSet  *res;
// ...
stmt = con->createStatement();
// ...

res = stmt->executeQuery("SELECT id, label FROM test ORDER BY id ASC");
while (res->next()) {  
  // You can use either numeric offsets...
  cout << "id = " << res->getInt(0);
  // ... or column names for accessing results. The latter is recommended.
  cout << ", label = '" << res->getString("label") << "'" << endl;
}

delete res;
delete stmt;
delete con;

Note that you have to free sql::Statement, sql::Connection and sql::ResultSet objects explicitly using delete.

The usage of cursors is demonstrated in the examples contained in the download package (examples/statement.cpp, examples/resultset.cpp).

[edit] Using Prepared Statements

If you are not familiar with Prepared Statements on MySQL have an extra look at the source code comments and explanations in the file examples/prepared_statement.cpp!

sql::PreparedStatement is created by passing a SQL query to sql::Connection::prepareStatement(). As sql::PreparedStatement is derived from sql::Statement, you will feel familiar with the API once you have learned how to use (simple) statements (sql::Statement). For example, the syntax for fetching results is identical.

// ...
sql::Connection *con;
sql::PreparedStatement *prep_stmt
// ...

prep_stmt = con->prepareStatement("INSERT INTO test(id, label) VALUES (?, ?)");

prep_stmt->setInt(1, 1);
prep_stmt->setString(2, "a");
prep_stmt->execute();

prep_stmt->setInt(1, 2);
prep_stmt->setString(2, "b");
prep_stmt->execute();

delete prep_stmt;
delete con;

As usual, you have to free sql::PreparedStatement and sql::Connection objects explicitly.

[edit] References

See the JDBC overview for information on JDBC 4.0. You might also want to have a look at the examples/ directory of the download package.

• MySQL Reference Manual - Connector/C++

[edit] Tentative 1.1.1 GA TODO

Please note: this is a tentative TODO. We do not promise everything listed below for a certain release. We try to make it, but we do not promise. We may, at any time, re-schedule tasks for other versions.

[edit] Coding

• [done] Prepare support for Visual Studio 2010
• [done] Prepare support for Connector/C (in addition to the MySQL Client Library)
• [ongoing] Bugfixes

[edit] QA

• (from Beta) [0/5 = 0%] Develop a set of micro benchmarks for performance regression testing
  • Low priority: may or may not make it into the release!
  • Connection performance
  • SELECT/INSERT using Statement
  • SELECT/INSERT using Prepared Statement
  • Fetching connection metadata
  • Fetching metadata associated with Statements
  • Fetching metadata associated with Prepared Statements
  • Write C/libmysql/Connector-C versions to compare performance for all of the above
  • Develop Win/Linux compatible test script that invokes the micro benchmarks and prints a comprehensive report

• Clone test set up to cover both Connector/C and libmysql

[edit] Other

• Build binaries using Connector/C instead of the MySQL Client Library

[edit] Documentation/Blogging/Publicity etc.

• Improve documentation
  • Add API reference section
  • Develop additional API examples
• (from 1.1.0) [low priority ] Blog posting: A threaded Connector/C++ client application

[edit] Known Bugs

See bugs.mysql.com.

[edit] Change History

[edit] MySQL Connector/C++ 1.1.1 GA (not yet released)

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

• Added MySQL_Connection::getLastStatementInfo() which returns back the value of the mysql_info() function of libmysql / Connector/C. (Andrey)

[edit] MySQL Connector/C++ 1.1.0 GA (13.09.2010)

• Added Driver::threadInit() and Driver::threadEnd() methods. Every thread of a threaded client must call Driver::threadInit() at the very start of the thread before it does anything else with Connector/C++ and every thread must call Driver::threadEnd() when it finishes. You can find an example demonstrating the use in examples/pthreads.cpp. It is strongly discouraged to share connections between threads. It is theoretically possible, if you set certain (undocumented) mutexes, but it is not supported at all. Use one connection per thread. Do not have two threads using the same connection at the same time. Please check the C API notes on threading on the MySQL manual. Connector/C++ wraps the C API. (Lawrin, Andrey, Ulf)
• Changed FindMySQL.cm so it looks for mysqlclient in the ENV{MySQL_DIR}\lib, as that is where it's located in (some) Connector/C distros, (Lawrin)
• Fixed bug in CmakeLists,txt - it didn't really use ENV{BOOST_ROOT}, boost wasn't searched in the directory set in that environment variable. (Lawrin)
• Fixed http://bugs.mysql.com/bug.php?id=51562 : error messages did not get reported properly if error occured after query execution and before fetching data within the underlying C API call mysql_use|store_result. (Andrey)
• BIT fields are now correctly decoded. (Andrey)
• Connection::getClientOption(const sql::SQLString & optionName, void * optionValue) now accepts the optionName values "metadataUseInfoSchema", "defaultStatementResultType", "defaultPreparedStatementResultType", "characterSetResults". In the previous version only "metadataUseInfoSchema" was allowed. The same is true for Connection::setClientOption().
• Fixed http://bugs.mysql.com/bug.php?id=45048 "prepared statements corrupt the heap". ResultBind is back in the prepared statement, but shared with the result set. (Andrey)
• get_driver_instance() is only available in dynamic library builds, static builds won't have this symbol. This is done, because someone might decided to load the dll with LoadLibrary/dlopen and needs an entry point to start using the library (some kind of a Driver Manager). For those, who don't use cmake for building you need to define mysqlcppconn_EXPORTS if you are loading dynamically and want to use that entry point. (Andrey)
• ABI change - added support for optional run-time dynamic loading of the MySQL Client Library. This is useful if you want to re-distribute a certain client library with the connector and make sure that it gets used. It also allows you to use a different client library for every connection. As it is an advanced feature it is not enabled by default. By default the MySQL Client Library will be linked at compile time just as in every version before.
• Fixed bug in ResultSetMetaData for normal statements and prepared ones, getScale() and getPrecision() did return wrong results. (Andrey)
• Fixed http://bugs.mysql.com/bug.php?id=45846 . Excluding dynamically generated and platform specific header files source packages generated using pack (Ulf).
• Connection map property OPT_RECONNECT is now of type boolean (was long long).
• We now check LDFLAGS, CXXFLAGS and CPPFLAGS from the environment for every binary we generate. (Ulf, Kent)
• Fixed http://bugs.mysql.com/bug.php?id=45843: cmake error if configuring an out of source build (when not calling cmake in the root directory). (Ulf)
• Fixed http://bugs.mysql.com/bug.php?id=44931: missing includes when using GCC 4.4. Note that GCC 4.4 is not yet in use for any official MySQL builds. (Ulf, Lawrin)
• Fixed a performance issue of Prepared Statements. Reading large result sets has been slow - think O(n^2). Patch by Frank Schoenheit from the OpenOffice.org Base team. (Ulf)
• Exchanged most use cases of std::auto_ptr with boost::scoped_ptr. Migrated from own solution to boost::scoped_array. In addition, migrated from another own solution to boost::shared_ptr/weak_ptr for guarding access around result sets. (Andrey)
• API incompatible change: ConnectPropertyVal is no more a struct by a typedef that uses boost::variant. This will break your build but is pretty easy to fix. If you had code like

 ---
 {
   sql::ConnectPropertyVal tmp;
   tmp.str.val=passwd.c_str();
   tmp.str.len=passwd.length();
   connection_properties["password"] = tmp;
 }
 ---
 Your new code you will like this:
 ---
 connection_properties["password"] = sql::ConnectPropertyVal(passwd);
 ---
 Which is simpler. (Andrey)

• Fixed a bug in PS, which in combination of preparing a stored procedures without any parameters was leading to exception, which was a problem, and was leading to another problem which manifested itself with double free. All similar code snippets in the Connector were fixed. (Andrey)

• The driver makes use of some Boost components (http://www.boost.org). You need to have Boost 1.34.0 or newer installed on your system in order to compile the driver from source. Binary distributions have no additional dependencies over 1.0.5.

[edit] MySQL Connector/C++ 1.0.5 GA (21.04.2009)

• Changed the interface of sql::ConnectionMetaData, sql::ResultSetMetaData and sql::ParameterMetaData to have a protected destructor. In this way the client code doesn't need, and won't be able, to destruct the metadata objects returned by the connector. The connector will handle their destruction. This enables statements like: connection->getMetaData->getSchema(); without the result of leaking memory because we lost the pointer returned by getMetaData(). (Lawrin, Andrey)
• Large overhaul of the code to improve the memory management to not leak in exceptional situations. Big improvement compared to Beta1. (Andrey)
• Fixed the interface of sql::Driver and sql::Connection so they accept the options map by alias instead of by value. (Andrey)
• Changed the return type of sql::SQLException::getSQLState() from std::string to const char * to be consistent with std::exception::what(). (Andrey)
• Implemented getResultSetType() and setResultSetType() for Statement. Used are TYPE_FORWARD_ONLY, which means unbuffered result set and TYPE_SCROLL_INSENSITIVE, which means buffered result set. (Andrey)
• Implemented getResultSetType() for PreparedStatement. The setter is not implemented because currently PreparedStatement can't do refetching and storing the result means the bind buffers will be correct. (Andrey)
• Added "defaultStatementResultType" to MySQL_Connection::setClientOption() as an option. Also the method now returns `sql::Connection *`. (Andrey)
• Added Result::getType() and implemented it in the three result set classes.(Andrey)
• Enabled tracing functionality when building with VC8 and up (VS2005 and up). (Andrey)
• Added better support for named pipes, on Windows. Use pipe:// and add the path to the pipe. Shared memory connections are currently not supported. (Andrey)
• Fixed a bug in MySQL_Connection::setSessionVariable() which led to exception being thrown. (Andrey)
• The driver makes use of some Boost components (http://www.boost.org). You need to have Boost 1.3.4 or newer installed on your system in order to compile the driver from source. Binary installations have no additional dependency over 1.0.5.

[edit] MySQL Connector/C++ 1.0.4 Beta (31.03.2009)

• Prepared support for upcoming Connector/C. (Georg)
• Added Windows GUI (MSI) installer. (Georg)
• Bumping up CMake minimum version requirement from 2.4.2 to 2.6.2. We need the latest version for Windows. (Lawrin)
• Added "metadataUseInfoSchema" to connection propery map which allows you to control the use of the INFORMATION_SCHEMA for meta data. (Andrey)
• Fixed a bug in all implementations of ResultSet::relative() which was giving wrong return value although positioning was working correctly. (Andrey)
• Fixed a leak in MySQL_PreparedResultSet when the result was containing a BLOB column. Andrey)
• Implemented MySQL_ConnectionMetaData::supportsConvert(from, to). (Andrey)
• Introduced sql::DataType::YEAR to complement MySQL's YEAR type. (Andrey)
• Introduced PreparedStatement::getMetaData(). (Andrey)
• Introduced ResultSetMetaData::isZerofill(), which is not in the JDBC specification. (Andrey)
• Fixed all implementations of ResultSet::isNull() to check whether the current position is on a real row, not isBeforeFirst() nor isAfterLast(), like all getXXX methods do. (Andrey)
• Implementation for MySQL_DatabaseMetaData::getProcedures() when INFORMATION_SCHEMA is asked not to be used. (Andrey)
• Removed MySQL_DatabaseMetaData::getProcedureColumns() from the interface. Until now it was returning always an empty result set. Full implementation will be added at a later stage. (Andrey)
• Changed a bunch of methods of DatabaseMetaData()::getXXX, which returned `int` to return `unsigned int` because it makes more sense. (Andrey)

[edit] MySQL Connector/C++ 1.0.3 Alpha (03.03.2009)

• Added new tests at test/unit/classes. Those tests are mostly about code coverage. Most of the actual functionality of the driver is tested by the tests found at test/CJUnitPort. (Ulf)
• New data types added to the list returned by DatabaseMetaData::getTypeInfo(): FLOAT UNSIGED, 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(). (Andrey)
• MySQL_Driver::getPatchVersion introducted. (Andrey)
• Major performance improvements due to new buffered resultset implementation by Andrey. (Ulf)
• Addition of test/unit/README with instructions for writing bug/regression tests. (Ulf)
• Experimental support for STLPort. This feature may be removed again at any time later without prior warning! Check cmake -L for configuration instructions. (Andrey)
• Fixed a bug in MySQL_PreparedResultSet::getString(). Returned string had real data but the length was random. Now, the string is initialized with correct length and thus is binary safe. (Andrey)
• Added properties-enabled (map of key->value) methods for connecting, which add many connect options. (Andrey)
  • Driver::connect( map )
  • Connection::Connection( map )
• New BLOB implementation. Got rid of sql::Blob 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 one 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 own stream. Similar will be true for getBlob() where we can just copy data, if buffered result set, or stream, if we implement it. (Andrey)
• Implemented ResultSet::getBlob() which returns std::stream. (Andrey)
• Fixed MySQL_DatabaseMetaData::getTablePrivileges() to work correctly. Test cases added in the first unit testing framework. (Andrey)
• Implemented MySQL_Connection::setSessionVariable() for setting variables like sql_mode. (Andrey)
• Implemented MySQL_DatabaseMetaData::getColumnPrivileges(). (Andrey)
• cppconn/datatype.h changed and used again. Reimplemented the type subsystem to be more usable - more types for binary and non-binary strings. (Andrey)
• Implementation for MySQL_DatabaseMetaData::getImportedKeys() for MySQL versions before 5.1.16 using SHOW, and above using INFORMATION_SCHEMA. (Andrey)
• Implemented MySQL_ConnectionMetaData::getProcedureColumns(). (Andrey)
• make package_source packs now with bzip2. (Andrey)
• Re-added getTypeInfo() with information about all types supported by MySQL and the sql::DataType. (Andrey)
• Exchanged the implementation of MySQL_ConstructedResultSet to use more efficient non O(n) but O(1) access method. This should improve the speed with which the metadata result sets are used. Also, there is less copy during the construction of the result set, which means that all result sets returned from the metadata functions will be faster. (Andrey)
• Introduced, internally, sql::mysql::MyVal which has implicit constructors used in mysql_metadata.cpp to create result sets with more native data instead of always string (varchar). (Andrey)
• Renamed ResultSet::getLong() to ResultSet::getInt64(). resultset.h includes typdefs for Windows to be able to use int64_t. (Andrey)
• Introduced ResultSet::getUInt() and ResultSet::getUInt64(). (Andrey)
• Corrected handling of unsigned server types. Now returning correct values (Andrey)
• Fixed handling of numeric columns in ResultSetMetaData::isCaseSensitive to return false. (Andrey)
• Better implementation for ResultSetMetaData::isReadOnly. Values generated from views are read-only. Seems that these generated values don't have `db` in MYSQL_FIELD set, while all normal columns do have. (Andrey)
• Implemented MySQL_DatabaseMetaData::getExportedKeys(). (Andrey)
• Implemented MySQL_DatabaseMetaData::getCrossReference(). (Andrey)

[edit] MySQL Connector/C++ 1.0.2 Alpha (19. December 2008)

• Adding test/unit as a basis for general unit tests based on the new test framework, see test/unit/example for basic usage examples (Ulf)
• Fixed MySQL_PreparedStatement::setBlob() to really work. In the tests there is a simple example of a class implementing sql::Blob. (Andrey)
• Addition of a new unit test framework for JDBC compliance and regression testing. We now include our JDBC compliance tests in the releases (Lawrin)
• Implemented MySQL_ResultSetMetaData::getPrecision() and MySQL_Prepared_ResultSetMetaData::getPrecision(),updating example. (Andrey)
• Fixing bug in FLOAT handling. (Andrey)
• Fixing bug in getString(): getString() is binary safe now (Andrey), new example. (Ulf)
• Fixing bugs in MySQL_PreparedStatements: setBigInt() and setDatetime() have decremented the internal column index before forwarding the request. This resulted in double-decrement and wrong internal column index. Typical error message: setString() ... invalid "parameterIndex" (Ulf)
• Adding 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! We do no promise to maintain it. (Ulf)
• Fixed bugs in MySQL_DatabaseMetaData :all supportsCatalogXXXXX methods were returning `true` and all supportSchemaXXXX methods false, which is not as it should be. Now it is reversed, to be consistent with the rest. (Andrey)
• Implemented MySQL_PreparedStatement::clearParameters(). (Andrey)
• Fixed a bug in MySQL_ConnectionMetaData::getColumns() which was performing a cartesian product of the columns in the table times the columns matching columnNamePattern. example/connection_meta_schemaobj.cpp extended to cover the function. (Andrey)
• Fixed lame bug in MySQL_ConnectionMetaData::getIndexInfo() which did not work because the schema name wasn't included in the query sent to the server. (Andrey)
• Implemented MySQL_PreparedStatement::setNull(). (Andrey)
• Reverted implementation of MySQL_DatabaseMetaData::getTypeInfo(). Now unimplemented. In addition, removed cppconn/datatype.h for now till we havea proper implementation of the types.
• DATE, DATETIME and TIME are now being handled when calling MySQL_PreparedResultSet::getString(), ::getDouble, ::getInt(), ::getLong(), ::getBoolean()
• Fixed MySQL_PreparedStatementResultSet::getDouble() to return proper value when the underlying type is MYSQL_TYPE_FLOAT. (Andrey)
• Changed ResultSetMetaData::getColumnDisplaySize(), ::getPrecision(), ::getScale() to return unsigned int instead of signed int. (Andrey)
• Implemented getScale(), getPrecision() and getColumnDisplaySize() for MySQL_ResultSetMetaData and MySQL_Prepared_ResultSetMetaData. (Andrey)

[edit] MySQL Connector/C++ 1.0.1 Alpha (2. December 2008)

• New directory layout
• MySQL Workbench 5.1 using Connector/C++ for its database connectivity.
• Addition of Connector/J tests converted
• Changing sql::DbcException to implement the interface of JDBC's SQLException. And renamed it to sql::SQLException.
• Renamed sql::DbcInvalidArgument to sql::InvalidArgumentException
• Renamed sql::DbcMethodNotImplemented to sql::MethodNotImplementedException
• All tests changed to create TAP compliant output
• Introduction of experimental CPack support, see make help
• Metadata: switching to column names "TABLE_CAT" (was: TABLE_CATALOG) and "TABLE_SCHEM" (was: TABLE_SCHEMA) for JDBC compliance
• ConnectionMetaData::getImportedKeys(): PKTABLE_CATALOG -> PKTABLE_CAT, PKTABLE_SCHEMA -> PKTABLE_SCHEM, FKTABLE_CATALOG -> FKTABLE_CAT, FKTABLE_SCHEMA -> FKTABLE_SCHEM
• ConnectionMetaData::getPrimaryKeys(): COLUMN -> COLUMN_NAME, SEQUENCE -> KEY_SEQ, INDEX_NAME -> PK_NAME
• ConnectionMetaData::getProcedures: PROCEDURE_SCHEMA -> PROCEDURE_SCHEM
• ConnectionMetaData::getTables: TABLE_COMMENT -> REMARKS
• 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
• Adding experimental GCov support, cmake -DMYSQLCPPCONN_GCOV_ENABLE:BOOL=1
• ConnectionMetaData::getCatalogTerm() returns n/a, there is no counterpart to catalog in Connector/C++
• Addition of ConnectionMetaData::getSchemas() and Connection::setSchema().
• Driver Manager removed
• (n)make install works. You can change the default installation path. Read carefully the messages after executing cmake. Installed are the static and the dynamic version of the library, libmysqlcppconn as well as the generic interface cppconn + 2 MySQL specific headers:

mysql_driver.h (if you want to get your connections from the driver instead of instantiating a MySQL_Connection object. This makes your code pretty portable against the common interface)

mysql_connection.h - If you intend to link directly to the MySQL_Connection class and use its specifics not found in sql::Connection

However, you can make your application fully abstract by not using the two headers above but the generic headers.

• sql::mysql::MySQL_SQLException is gone. There is no distinction between server and client (= Connector) caused errors based on the type of the exception. However, you can still check the error code to figure out the reason.

[edit] MySQL Connector/C++ 1.0.0 Preview (5. August 2008)

First public release.

[edit] Feature requests

• Adapt STL (suggest details, if you can)
• Please consider C++ references for Statements, ResultSets, and exceptions, instead of pointers to heap memory. Considering the possible exceptions, it quickly becomes a hassle to ensure that everything is freed correctly. I think C++ programmers are accustomed to the compiler doing all of that for them.

[edit] Comparison with MySQL++

Connector/C++ and MySQL++ follow different approaches:

• Connector/C++ follows the JDBC 4.0 API
• MySQL++ uses a non-standard API
• The MySQL++ API is "C++-ish" and rich of C++ specific goodies

• Connector/C++ is licensed under the GPL (+ FLOSS License Exception)
• Connector/C++ is also available under a commercial license upon request
• MySQL++ uses LGPL

• Connector/C++ is available as a beta
• MySQL++ offers GA (General Availability) releases