Connecting to Database

Connection Strings

Connection String Format

CppDB connection string consists of the following parts:

1. Driver Name separated from rest of the string with ":"
2. Set of key = value pairs separated with ";" symbol. Where value can be put in single quotation marks ' and double quotation mark represents a single one (like in SQL syntax).

For example

mysql:database=test;user=joe;password='d''eep secret'

Represent a driver "mysql", user "joe" and password "d'eep secret".

There are special keys that used as internal cppdb options rather then connection options. Such keys are always start with @ symbol. For example "@use_prepared=off".

Special Options

These are CppDB special key values that are used as meta data for the connection:

• @stmt_cache_size - integer - the maximal number of cached statements. Default is 64.
  Each time new statement is created it is stored back in cache for future reuse and thus next time when the statement is created it would be fetched from cache rather then being prepared again. It gives significant performance boost for query and statements execution. The cache is handled using LRU queue.
• @use_prepared - "on" or "off" by default create prepared statements or ordinary statements. Default is "on".
• @pool_size - integer - the size of connection pool. Default is 0 - no connection pooling.
  This provides connection pool for efficient connection reuse that significantly improves the performance.
• @pool_max_idle - integer - the number if seconds to keep idle connection in pool. Default 600 - 10 minutes.
  This is useful for keeping maximal amount of time for holding an idle connection in pool.
• @modules_path - string - the path to search cppdb modules (drivers) in.
  Several paths can be given, under POSIX platform they should be separated using ':' symbol and under Windows (not Cygwin) it should be ';' symbol. For example:
  

  mydriver:@modules_path=/opt/cppd/lib:/usr/local/lib;database=foo
  mydriver:@modules_path='c:/cppdb/lib;c:/mydrv';database=foo
  

• @module - string - the path to loadable cppdb module (shared object or dll).
  The explicit path to cppdb driver, for example "mydriver:@module=/opt/lib/libmy.so"

Connection

Connecting to the database can be done using either by creating a session object with connection string parameter cppdb::session::session(std::string const &) or by calling cppdb::session::open() function.

When the connection established first time for specific driver, it loads its shared object or dll and makes it available for you. If you want to unload the drivers that are not used any more you should call cppdb::driver_manager::collect_unused(). And if all drivers that do not have opened connections will be closed.

Note:

If you use connection pooling you would also want to call cppdb::connections_manager::gc() to remove all sessions that were idle for long period of time.

Both classes cppdb::connections_manager and cppdb::driver_manager are singleton classes that used for connection management and pooling and in fact, cppdb::session::open() just calls cppdb::connections_manager::open() to get the underlying cppdb::backend::connection object.