SOCI Logo Get SOCI at Fast, secure and Free Open Source software downloads

Connections and simple queries

Connecting to the database

The session class encapsulates the database connection and other backend-related details, which are common to all the statements that will be later executed. It has a couple of overloaded constructors.

The most basic one expects two parameters: the requested backend factory object and the generic connection string, which meaning is backend-dependent.


session sql(oracle, "service=orcl user=scott password=tiger");

Another example might be:

session sql(postgresql, "dbname=mydb");

Above, the sql object is a local (automatic) object that encapsulates the connection.

This session constructor either connects successfully, or throws an exception.

Another constructor allows to name backends at run-time and supports the dynamically loadable backends, which have to be compiled as shared libraries. The usage is similar to the above, but instead of providing the factory object, the backend name is expected:

session sql("postgresql", "dbname=mydb");

For convenience, the URL-like form that combines both the backend name with connection parameters is supported as well:

session sql("postgresql://dbname=mydb");

The last two constructors described above try to locate the shared library with the name (or libsoci_ABC.dll on Windows), where ABC is the backend name. In the above examples, the expected library name will be for Unix-like systems.

Environment configuration:

The SOCI_BACKENDS_PATH environment variable defines the set of paths where the shared libraries will be searched for. There can be many paths, separated by colons, and they are used from left to right until the library with the appropriate name is found. If this variable is not set or is empty, the current directory is used as a default path for dynamically loaded backends.

An alternative way to set up the session is to create it in the disconnected state and connect later:

session sql;

// some time later:, "dbname=mydb");

// or:"postgresql://dbname=mydb");

The rules for backend naming are the same as with the constructors described above.

The session can be also explicitly closed and reconnected, which can help with basic session error recovery. The reconnect function has no parameters and attempts to use the same values as those provided with earlier constructor or open calls.

See also the page devoted to multithreading for a detailed description of connection pools.

It is possible to have many active sessions at the same time, even using different backends.

Portability note:

The following backend factories are currently (as of 3.0.0 release) available:

The following backends are also available, with various levels of completeness:

Simple SQL statements

In many cases, the SQL query is intended to be executed only once, which means that statement parsing and execution can go together. The session class provides a special once member, which triggers parsing and execution of such one-time statements:

sql.once << "drop table persons";

For shorter syntax, the following form is also allowed:

sql << "drop table persons";

The IOStream-like interface is exactly what it looks like, so that the statement text can be composed of many parts, involving anything that is streamable (including custom classes, if they have appropriate operator<<):

string tableName = "persons";
sql << "drop table " << tableName;

int id = 123;
sql << "delete from companies where id = " << id;
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines
SourceForge Logo

Generated on Sun Oct 3 2010 17:42:17 for EXTRAS-SOCI by Doxygen 1.7.1