MySQL Backend Reference

Prerequisites

Supported Versions

The SOCI MySQL backend should in principle work with every version of MySQL 3.x or newer. Some of features (transactions, stored functions) are not available when MySQL server doesn't support them.

Tested Platforms

MySQL versionOperating SystemCompiler
4.1.20Linux i686 2.6.17 (Fedora Core release 4)g++ 4.0.2
5.0.22Linux i686 2.6.15 (Ubuntu 6.06)g++ 4.0.3
5.0.18Mac OS X 10.4g++ 4.0.0
4.0.22Linux i686 2.6.10-gentoo-r6g++ 3.4.5

One other version of MySQL server that has been tested is 3.23.57.

Required Client Libraries

The SOCI MySQL backend requires MySQL's libmysqlclient client library.

Connecting to the Database

To establish a connection to a MySQL server, create a Session object using the mysql backend factory together with a connection string:

BackEndFactory const &backEnd = mysql;
Session sql(backEnd, "db=test user=root password='Ala ma kota'");

The set of parameters used in the connection string for MySQL is:

Once you have created a Session object as shown above, you can use it to access the database, for example:

int count;
sql << "select count(*) from invoices", into(count);

(See the SOCI basics and exchanging data documentation for general information on using the Session class.)

SOCI Feature Support

Dynamic Binding

The MySQL backend supports the use of the SOCI Row class, which facilitates retrieval of data whose type is not known at compile time.

When calling Row::get<T>(), the type you should pass as T depends upon the underlying database type.
For the MySQL backend, this type mapping is:

PostgreSQL Data Type SOCI Data Type Row::get<T> specializations
FLOAT, DOUBLE, DECIMAL and synonyms eDouble double
TINYINT, SMALLINT, INT, BIGINT (provided it's in the range) eInteger int
STRING/BINARY, VARCHAR/VARBINARY eString std::string
TIMESTAMP (works only with MySQL >= 5.0), DATE, TIME, DATETIME eDate std::tm

(See the dynamic resultset binding documentation for general information on using the Row class.)

Binding by Name

In addition to binding by position, the MySQL backend supports binding by name, via an overload of the use() function:

int id = 7;
sql << "select name from person where id = :id", use(id, "id")

It should be noted that parameter binding of any kind is supported only by means of emulation, since the underlying API used by the backend doesn't provide this feature.

Bulk Operations

The MySQL backend has full support for SOCI's bulk operations interface. This feature is also supported by emulation.

Transactions

Transactions are also supported by the MySQL backend. Please note, however, that transactions can only be used when the MySQL server supports them (it depends on options used during the compilation of the server; typically, but not always, servers >=4.0 support transactions and earlier versions do not) and only with appropriate table types.

BLOB Data Type

SOCI BLOB interface is not supported by the MySQL backend.

RowID Data Type

RowID is not supported by the MySQL backend.

Nested Statements

Nested statements are not supported by the MySQL backend.

Stored Procedures

MySQL version 5.0 and later supports two kinds of stored routines: stored procedures and stored functions (for details, please consult the MySQL documentation). Stored functions can be executed by using SOCI's Procedure class. There is currently no support for stored procedures.

Acessing the native database API

SOCI provides access to underlying datbabase APIs via several getBackEnd() functions, as described in the beyond SOCI documentation.

The MySQL backend provides the following concrete classes for native API access:

Accessor Function Concrete Class
SessionBackEnd* Session::getBackEnd() MySQLSessionBackEnd
StatementBackEnd* Statement::getBackEnd() MySQLStatementBackEnd

Backend-specific extensions

None.

Configuration options

None.