Libzdb

Version 3.0

A small, easy to use Open Source Database Connection Pool Library with the following features:

  • Thread safe Database Connection Pool
  • Connect to multiple database systems
  • Zero runtime configuration, connect using a URL scheme
  • Supports MySQL, PostgreSQL, SQLite and Oracle
Download

Requirements: Runs on iOS, Linux, OS X, FreeBSD, Solaris, OpenBSD and other POSIX systems. A C99 compiler is required to build the library.

Compatible with and can be included in C++ or Objective-C projects

Compatible with and can be included in C++ or Objective-C projects.

Modern, Object Oriented API design. Fully documented.

The library is licensed under a Free Open Source Software License.

Used in M/Monit

- The M/Monit Team mmonit.com

Used in DBMail

dbmail.org

Used in Seafile

seafile.com
Can I use libzdb in my iOS or OS X app?

Yes, libzdb can be used from and included in any C, C++ or Objective-C project. The Xcode project file used to develop libzdb is available from the repository and can be included in your own Xcode project.

Is the library thread-safe?

Libzdb is thread-safe and designed to be used in a multi-threaded program.

Is the connection pool dynamic?

Yes, the pool can be setup to dynamically change the number of Connections in the pool depending on the load.

Are previous versions available?

Click the d icon in the footer below to access previous versions of the library.

Public code repository?

The project is hosted at Bitbucket. Click the r icon in the footer below to visit the repository and browse the code online.

Are there plans to support additional database systems?

Libzdb currently supports SQLite, MySQL, PostgreSQL and Oracle. At the moment there are no plans to support additional database systems.

Libzdb API documentation
ConnectionPool URL Connection PreparedStatement ResultSet

Clickable API documentation

Connection URL:

The URL given to a Connection Pool at creation time specify a database connection on the standard URL format. The format of the connection URL is defined as:

database://[user:password@][host][:port]/database[?propertyName1][=propertyValue1][&propertyName2][=propertyValue2]...

The property names user and password are always recognized and specify how to login to the database. Other properties depends on the database server in question. User name and password can alternatively be specified in the auth-part of the URL. If port number is omitted, the default port number for the database server is used.

MySQL:

Here is an example on how to connect to a MySQL database server:

mysql://localhost:3306/test?user=root&password=swordfish

In this case the username, root and password, swordfish are specified as properties to the URL. An alternative is to use the auth-part of the URL to specify authentication information:

mysql://root:swordfish@localhost:3306/test

See mysql options for all properties that can be set for a mysql connection URL.

SQLite:

For a SQLite database the connection URL should simply specify a database file, since a SQLite database is just a file in the filesystem. SQLite uses pragma commands for performance tuning and other special purpose database commands. Pragma syntax on the form, name=value can be added as properties to the URL and will be set when the Connection is created. In addition to pragmas, the following properties are supported:

  • heap_limit=value [KB] - Make SQLite auto-release unused memory if memory usage goes above the specified value.

An URL for connecting to a SQLite database might look like:

sqlite:///var/sqlite/test.db?synchronous=normal&heap_limit=8000&foreign_keys=on

PostgreSQL:

The URL for connecting to a PostgreSQL database server might look like:

postgresql://localhost:5432/test?user=root&password=swordfish

As with the MySQL URL, the username and password are specified as properties to the URL. Likewise, the auth-part of the URL can be used instead to specify the username and the password:

postgresql://root:swordfish@localhost/test?use-ssl=true

In this example we have also omitted the port number to the server, in which case the default port number, 5432, for PostgreSQL is used. In addition we have added an extra parameter to the URL, so connection to the server is done over a secure SSL connection.

See postgresql options for all properties that can be set for a postgresql connection URL.

Oracle:

The URL for connecting to an Oracle database server might look like:

oracle://localhost:1521/test?user=scott&password=tiger

The auth-part of the URL can be used instead to specify the username and the password. In addition, you may specify a service name in the URL instead if you have setup a tnsnames.ora configuration file.

oracle:///servicename?user=scott&password=tiger

Examples:

To obtain a connection pool for a MySQL database, the code below can be used. The exact same code can be used for PostgreSQL, SQLite and Oracle, the only change needed is to modify the Connection URL. Here we connect to the database test on localhost and start the pool with the default 5 initial connections.

ConnectionPool, Connection and ResultSet:

URL_T url = URL_new("mysql://localhost/test?user=root&password=swordfish");
ConnectionPool_T pool = ConnectionPool_new(url);
ConnectionPool_start(pool);

Connection_T con = ConnectionPool_getConnection(pool);
ResultSet_T result = Connection_executeQuery(con, 
                     "select id, name, image from employee where salary > %d", aNumber);
while (ResultSet_next(result)) 
{
     int id = ResultSet_getInt(result, 1);
     const char *name = ResultSet_getString(result, 2);
     int blobSize;
     const void *image = ResultSet_getBlob(result, 3, &blobSize);
     [..]
}
                

Here is another example where a generated result is selected and printed:

ResultSet_T r = Connection_executeQuery(con, "SELECT count(*) FROM users");
printf("Number of users: %s\n", ResultSet_next(r) ? ResultSet_getString(r, 1) : "no users");
                

Prepared statement:

PreparedStatement_T p = Connection_prepareStatement(con, 
                        "INSERT INTO employee(name, picture) VALUES(?, ?)");
PreparedStatement_setString(p, 1, "Kamiya Kaoru");
PreparedStatement_setBlob(p, 2, jpeg, jpeg_size);
PreparedStatement_execute(p);
               

Here, we use a Prepared Statement to execute a query which returns a Result Set:

PreparedStatement_T p = Connection_prepareStatement(con, 
                        "SELECT id FROM employee WHERE name LIKE ?"); 
PreparedStatement_setString(p, 1, "%Kaoru%");
ResultSet_T r = PreparedStatement_executeQuery(p);
while (ResultSet_next(r))
       printf("employee.id = %d\n", ResultSet_getInt(r, 1));
               

More examples can be found by clicking the API documentation image above.

Version 3.0

Released on 06 Jan 2014
  • New: Methods for retrieving Date, Time, DateTime and TimeStamp column values from a ResultSet. PreparedStatement_setTimestamp for setting Unix timestamp.
  • New: ResultSet_isnull, can be used to explicit test if a column value in a Result Set is SQL null. A Result Set already returns the NULL pointer for string and blob types and 0 for primitive data types if column value is SQL null, but to differ between SQL null and the value NULL or 0, this method can be used.
  • New: PreparedStatement_getParameterCount, Returns the number of parameters in a prepared statement
  • New: It is now a checked runtime error for the url parameter given in ConnectionPool_new to be NULL.
  • New: No longer require flex installed as the generated file is part of the distribution.
  • Fixed: Oracle: memory corruption in OracleResultSet when a Blob value is retrieved as a String

Version 2.12

Released on 03 Sep 2013
  • New: PreparedStatement_rowsChanged added to PreparedStatement.h
  • Fixed: Oracle: OCIPing is used to check Oracle connections and to ensure that the Pool returns connected connections. Thanks to Pavlo Lavrenenko.

Version 2.11/3

Released on 05 Jun 2013
  • New: License Exception added to allow the library to be linked and distributed together with OpenSSL.
  • New: Throw SQLException if a database access error occurs when ResultSet_next() is called. Previously, access errors could be masked as end of result set. Thanks to JiaQiang Xu.
  • Fixed: (Volodymyr Tarasenko) Possible mem leak in Oracle's blob operation fixed.
  • Fixed: MySQL: A ResultSet bind memory error could occur if string or blob columns of different size caused successive buffer reallocation. Thanks to Ryan Addams for discovering the problem.
  • New: Added support for the new bytea hex encoding format introduced in PostgreSQL 9.0.
  • Fixed: MySQL: A Result Set with two or more columns larger than 256 bytes would cause libzdb to truncate the second column to 256 bytes in the first row. Thanks to Me from China for bug report and patch.
  • Fixed: Improved Build Configuration. Thanks to Johan Bergström for report.

Version 2.10/.6

Released on 29 Oct 2012
  • New: Libzdb is now compatible with and can be included in C++ or Objective-C(++) projects.
  • Fixed: Oracle: Fixed a connection parameter bug. Thanks to l00106600
  • Fixed: Oracle: Fixed a GCC C99 compile issue. Thanks to Stas Oginsky
  • New: MySQL: Improved error reporting
  • New: Automatically unescape the following URL components: credentials, path and parameter values
  • New: Connection Pool start now throws an SQLException instead of calling abort handler if starting the pool failed. Thanks to Christopher O'Hara
  • Fixed: MySQL: Using a stored procedure which returned a result set would freeze the connection until it was reaped. Thanks to Jesse White
  • Fixed: MySQL: Ensure that the library can be restarted after it was stopped without leaking resources. Only applicable for MySQL which could leak memory on runtime restart. Thanks to Axel Steiner

Version 2.9

Released on 15 Aug 2011
  • New: SQLite: Unescape path to allow for (white-)space in database file URL path. Thanks to Jonas Schnelli
  • Fixed: SQLite: Use sqlite3_open_v2 instead of sqlite3_enable_shared_cache which is deprecated in OS X Lion
  • Fixed: Oracle: Fixed a problem with ResultSet not returning all data.

Version 2.8/.1

Released on 15 Feb 2011
  • New: PostgreSQL: Allow sending application name to the server for logging. Thanks to Chris Mayo. See the PostgreSQL URL property, application-name.
  • Fixed: Oracle: Fixed a ResultSet memory leak
  • Fixed: Oracle: Fixed a transaction related memory leak

Questions or comments?

If you have questions or comments about the software or documentation please subscribe to the libzdb general mailing list and post your questions there.

Open Source

Libzdb is open source. It's hosted, developed, and maintained on Bitbucket.

Reporting a bug

If you believe you have found a bug, please use the issue tracker to report the problem. Remember to include the necessary information that will enable us to understand and reproduce this problem.