Category: MySQLDevelopment

Connector C++

Contents


[edit] Introduction

MySQL Connector/C++ is a MySQL database connector for C++.

The MySQL Connector/C++ is licensed under the terms of the GPL, like most MySQL Connectors. There are special exceptions to the terms and conditions of the GPL as it is applied to this software, see FLOSS License Exception. If you need a non-GPL license for commercial distribution please contact us.

The MySQL Driver for C++ mimics the JDBC 4.0 API. However, Connector/C++ does not implement all of the JDBC 4.0 API. The Connector/C++ preview features the following classes:

The MySQL Connector/C++ implements a significant subset of JDBC 4.0. The JDBC API defines some 450 methods for the above mentioned classes. About 375 (= 80%) of them are implemented and available with the alpha release.

In total you will find about 570 being declared in Connector/C++ and approximately 460 of them being implemented, please check the simplified implementation statistics (1.0.3alpha, 1.0.2alpha for details. Please note, we remove method stubs from releases and you will find only fully implemented methods in a release.

The Driver for C++ can be used to connect to MySQL 5.1 or later. Note - its full functionality is not available when connecting to MySQL 5.0. You cannot connect to MySQL 4.1 or earlier.

[edit] Download

You can download the MySQL Connector/C++ at http://dev.mysql.com/downloads/connector/cpp/1.0.html

As of 1.0.4beta we offer both binary and source packages. Available binary packages:

Available source packages:


[edit] Source repository

The latest development version is also available through Launchpad at https://launchpad.net/mysql-connector-cpp .

Bazaar is used for the MySQL Connector/C++ code repository. You can check out the source using the bzr command line tool (current development branch): 

bzr branch lp:~mysql/mysql-connector-cpp/trunk

The source of the 1.0.1alpha release is available from the following branch: 

bzr branch lp:~andrey-mysql/mysql-connector-cpp/v1_0_1


[edit] Supported Platforms

The beta release has been successfully compiled and tested on the following platforms:

Future versions aim to support as many of the platforms for which commercial support is available for the latest GA version of the MySQL Server as possible. Please check the support policies at http://www.mysql.com/support/supportedplatforms/enterprise.html for details.

For sales related questions, for example on support or commercial licenses, please write to <sales@mysql.com>.

[edit] Advantages

Using MySQL Connector/C++ instead of the MySQL C API (MySQL Client Library) offers the following advantages for C++ users:

[edit] Status

MySQL Connector/C++ is available as production version. We kindly ask users and developers to try it out and provide us with feedback.

MySQL Workbench is using a pre-alpha code snapshot for its internal development version. The same is true for the MySQL Connector/OpenOffice.org.

[edit] Binary Installation

Unpack the archive into an appropriate directory.

If you plan to use a dynamically linked version of MySQL Connector/C++, make sure that your system can find the MySQL client library. Consult your operating system documentation on how do modify and expand the search patch for libraries. In case you cannot modify the library search path it may help to copy your application, the MySQL Connector/C++ library and the MySQL client library into the same directory. Most systems search for libraries in the current directory.

Please read also Connector C++ Binary Builds for notes on binary portability.

[edit] Windows MSI Installer

Windows users can choose between two binary packages: without installer (unzip in C:\) and Windows MSI Installer (x86).

Using the MSI Installer may be more comfortable. Running the MSI Installer does not require any administrative permissions because all it does is to copy files.

Image:Conn cpp installer welcome.png

Image:Conn cpp installer installation overview.png

The "Typical" installation consists of all required header files and the Release libraries. The only available "Custom" installation option allows you to install additional Debug versions of the driver libraries.

Image:Conn_cpp_installer_custom_setup.png


[edit] Source Installation

The MySQL Connector/C++ is based on the MySQL client libary (MySQL C API). Connector C/C++ is linked against the MySQL client library. You need to have the MySQL client library installed in order to compile the Connector/C++.

You also need to have the cross-platform build tool CMake 2.6.2 or newer. Check the README file for platform specific notes on Windows and SunOS.

Typically the MySQL client library gets installed by installing the MySQL Server. However, check your operating system documentation for other installation options. Please note also, that MySQL provides downloads for certain platforms which contain no more than the required client library.

[edit] Building on Unix, Solaris and Mac

1. Run CMake to build a Makefile 

me@host:/path/to/mysql-connector-cpp> cmake .
-- Check for working C compiler: /usr/local/bin/gcc
-- Check for working C compiler: /usr/local/bin/gcc -- works
[...]
-- Generating done
-- Build files have been written to: /path/to/mysql-connector-cpp/

  Read on at point 3.) in case of configure problems.

2. Use make to build the libraries 

me@host:/path/to/mysql-connector-cpp> make clean
me@host:/path/to/mysql-connector-cpp> make
[  1%] Building CXX object driver/CMakeFiles/mysqlcppconn.dir/mysql_connection.o
[  3%] Building CXX object driver/CMakeFiles/mysqlcppconn.dir/mysql_constructed_resultset.o
[...]
[100%] Building CXX object examples/CMakeFiles/statement.dir/statement.o
Linking CXX executable statement

If all goes well, you will find the Connector/C++ library in /path/to/cppconn/libmysqlcppconn.so . In case of problems read on below before you ask for assistance.

3. CMake options: MySQL installation path, debug version and more

In case of configure and/or compile problems check the list of CMake options: 

me@host:/path/to/mysql-connector-cpp> cmake -L
[...]
CMAKE_BACKWARDS_COMPATIBILITY:STRING=2.4
CMAKE_BUILD_TYPE:STRING=
CMAKE_INSTALL_PREFIX:PATH=/usr/local
EXECUTABLE_OUTPUT_PATH:PATH=
LIBRARY_OUTPUT_PATH:PATH=
MYSQLCPPCONN_GCOV_ENABLE:BOOL=0
MYSQLCPPCONN_TRACE_ENABLE:BOOL=0
MYSQL_CONFIG_EXECUTABLE:FILEPATH=/usr/bin/mysql_config

For example, if your MySQL Server installation path is not /usr/local/mysql and you want to build a debug version of the MySQL Connector/C++ use: 

me@host:/path/to/mysql-connector-cpp> cmake -D CMAKE_BUILD_TYPE:STRING=Debug -D MYSQL_CONFIG_EXECUTABLE=/path/to/my/mysql/server/bin/mysql_config .

Verify your settings with cmake -L: 

me@host:/path/to/mysql-connector-cpp> cmake -L
[...]
CMAKE_BACKWARDS_COMPATIBILITY:STRING=2.4
CMAKE_BUILD_TYPE:STRING=
CMAKE_INSTALL_PREFIX:PATH=/usr/local
EXECUTABLE_OUTPUT_PATH:PATH=
LIBRARY_OUTPUT_PATH:PATH=
MYSQLCPPCONN_GCOV_ENABLE:BOOL=0
MYSQLCPPCONN_TRACE_ENABLE:BOOL=0
MYSQL_CONFIG_EXECUTABLE=/path/to/my/mysql/server/bin/mysql_config

Procees with make clean; make as described at point 2.)

[edit] Building on Windows

The basic steps for building the driver on Windows are the same as on Unix: use CMake 2.6.2 or newer to generate build files for your compiler and compile the driver using your compiler.

We are sorry but we cannot formally support other compilers than Microsoft Visual Studio 2003 and above.

Thanks to CMake it is easy for you to try out other compilers. However, you may experience compile warnings, compile errors or linking issues not detected by Visual Studio. We appreciate your patches to fix any of them.

Consult the CMake manual or check cmake --help to find out which build systems are supported by your CMake version. 

C:\>cmake --help
cmake version 2.6-patch 2
Usage
[...]
Generators

The following generators are available on this platform:
  Borland Makefiles           = Generates Borland makefiles.
  MSYS Makefiles              = Generates MSYS makefiles.
  MinGW Makefiles             = Generates a make file for use with
                                mingw32-make.
  NMake Makefiles             = Generates NMake makefiles.
  Unix Makefiles              = Generates standard UNIX makefiles.
  Visual Studio 6             = Generates Visual Studio 6 project files.
  Visual Studio 7             = Generates Visual Studio .NET 2002 project
                                files.
  Visual Studio 7 .NET 2003   = Generates Visual Studio .NET 2003 project
                                files.
  Visual Studio 8 2005        = Generates Visual Studio .NET 2005 project
                                files.
  Visual Studio 8 2005 Win64  = Generates Visual Studio .NET 2005 Win64
                                project files.
  Visual Studio 9 2008        = Generates Visual Studio 9 2008 project fil
  Visual Studio 9 2008 Win64  = Generates Visual Studio 9 2008 Win64 proje
                                files.
[...]

It is likely that your cmake binary will support more compilers ("generators") than supported by MySQL Connector/C++. We have built the driver using the following generators:

Please see the above Installation instructions for Unix, Solaris and Mac for troubleshooting and configuration hints.

1. Run CMake to generate build files for your "generator"

1.1 Visual Studio 

C:\path_to_mysql_cpp>cmake -G "Visual Studio 9 2008"
-- Check for working C compiler: cl
-- Check for working C compiler: cl -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: cl
-- Check for working CXX compiler: cl -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- ENV{MYSQL_DIR} =
-- MySQL Include dir: C:/Programme/MySQL/MySQL Server 5.1/include
-- MySQL Library    : C:/Progams/MySQL/MySQL Server 5.1/lib/opt/mysqlclient.lib
-- MySQL Library dir: C:/Progams/MySQL/MySQL Server 5.1/lib/opt
-- MySQL CFLAGS:
-- MySQL Link flags:
-- MySQL Include dir: C:/Progams/MySQL/MySQL Server 5.1/include
-- MySQL Library dir: C:/Progams/MySQL/MySQL Server 5.1/lib/opt
-- MySQL CFLAGS:
-- MySQL Link flags:
-- Configuring cppconn
-- Configuring test cases
-- Looking for isinf
-- Looking for isinf - not found
-- Looking for isinf
-- Looking for isinf - not found.
-- Looking for finite
-- Looking for finite - not found.
-- Configuring C/J junit tests port
-- Configuring examples
-- Configuring done
-- Generating done
-- Build files have been written to: C:\path_to_mysql_cpp
C:\path_to_mysql_cpp>dir *.sln *.vcproj
[...]
19.11.2008  12:16            23.332 MYSQLCPPCONN.sln
[...]
19.11.2008  12:16            27.564 ALL_BUILD.vcproj
19.11.2008  12:16            27.869 INSTALL.vcproj
19.11.2008  12:16            28.073 PACKAGE.vcproj
19.11.2008  12:16            27.495 ZERO_CHECK.vcproj

1.2 NMake 

C:\path_to_mysql_cpp>cmake -G "NMake Makefiles"
-- The C compiler identification is MSVC
-- The CXX compiler identification is MSVC
[...]
-- Build files have been written to: C:\path_to_mysql_cpp


2. Use your compiler to build the MySQL Conenctor/C++

2.1 Visual Studio - GUI

Open the newly generated project files in the Visual Studio GUI or use a Visual Studio command line to build the driver. The project files contain a variety of different configurations. Among them debug and non-debug versions.

2.2 Visual Studio - NMake 

C:\path_to_mysql_cpp>nmake
	
Microsoft (R) Program Maintenance Utility Version 9.00.30729.01
Copyright (C) Microsoft Corporation.  All rights reserved.
	
Scanning dependencies of target mysqlcppconn
[  2%] Building CXX object driver/CMakeFiles/mysqlcppconn.dir/mysql_connection.obj
mysql_connection.cpp
[...]
Linking CXX executable statement.exe
[100%] Built target statement

[edit] Platform Notes on Building

All distributions contain a README file. At the end of the README file contained in a binary distribution you will find the settings used to build the binaries.

If you experience build issues on a platform, it may help to check the settings we use on the platform to build the binary by downloading the binary package.

We have summarized further details at the wiki page Connector C++ Binary Builds.

[edit] Getting Started: Usage Examples

The download package contains usage examples in the directory examples/. The examples explain the basic usage of the following classes:

The examples cover:

The examples on this wiki page are only code snippets. The code snippets provide a brief overview on the API. They are not complete programs. Please check the examples/ directory for complete programs.

The examples will be compiled as part of a normal build (e.g. during make).

[edit] 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.

[edit] Tentative 1.0.6 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.

M4 (Milestone 4) has been the internal name of 1.0.5 GA.

[edit] Coding

[edit] QA

[edit] Other

[edit] Documentation/Blogging/Publicity etc.

[edit] Known Bugs

There are no known bugs.

[edit] Change History

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

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

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

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

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

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

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

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.

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

First public release.

[edit] Feature requests

[edit] Comparison with MySQL++

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

[edit] Contact

For general discussion of the MySQL Connector/C++ please use the C/C++ community forum or join the MySQL Connector/C++ mailing list.

Bugs can be reported at http://bugs.mysql.com.

For Licensing questions, and to purchase MySQL Products and Services, please Contact MySQL.

[edit] Who's who?

Retrieved from "http://forge.mysql.com/wiki/Connector_C%2B%2B"

This page has been accessed 41,216 times. This page was last modified 16:02, 13 September 2009.

Find

Browse
MySQLForge
Main Page
Current events
Recent changes
Random page
Help
Edit
Edit this page
Editing help
This page
Discuss this page
Post a comment
Printable version
Context
Page history
What links here
Related changes
My pages
Special pages
New pages
File list
Statistics
Bug reports
More...