SOCI Documentation

About SOCI

SOCI is the C++ Database Access Library.

SOCI was initially developed in the environment where Oracle was the main database technology in use. As a wrapper for the native OCI API (Oracle Call Interface), the name "Simple Oracle Call Interface" was quite obvious - until the 2.0 release, when the internal architecture was largely redesigned to allow the use of backends that support other database servers. We have kept the same name to indicate that Oracle is the main supported technology in the sense that the library includes only those features that were naturally implemented in Oracle. With the 2.1 release of the library, two new backends were added (MySQL and SQLite3) and we decided to drop the original full name so that new users looking for a library supporting any of these simpler libraries are not discouraged by seeing "Oracle" somewhere in the name. The other possible interpretation was "Syntax Oriented Call Interface", which stresses the fact that SOCI was built to support the most natural and easy interface for the user that is similar to the Embedded SQL concept (see below). But on the other hand, SOCI also provides other features (like object-relational mapping) and as a whole it is not just "emulator" of the Embedded SQL. With all these considerations in mind, SOCI is just "SOCI - The C++ Database Access Library".

Still, Oracle is considered to be the main driving server technology in terms of the set of features that are supported by the library. This also means that backends for other servers might need to work around some of the imposed idioms and protocols, but already available and well-working PostgreSQL, MySQL and SQLite3 backends show that it's actually not that bad and the abstractions provided by the library are actually very universal. Of course, some of the features that were provided for Oracle might not be supported for all other servers, but we think that it's better to have one leading technology (where at least one group is fully happy) instead of some "common denominator" for all databases (where nobody is happy).

The following (complete!) example is purposedly provided without any explanation.

#include <soci/core/soci.h>
#include <soci/core/soci-oracle.h>
#include <iostream>
#include <istream>
#include <ostream>
#include <string>
#include <exception>

bool getName(string &name) {
    std::cout << "Enter name: ";
    return std::cin >> name;
}

int main() {
    try {
        soci::session sql(oracle, "service=mydb user=john password=secret");

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

        std::cout << "We have " << count << " entries in the phonebook.\n";

        std::string name;
        while (getName(name)) {
            std::string phone;
            soci::indicator ind;
            sql << "select phone from phonebook where name = :name",
                soci::into(phone, ind), soci::use(name);

            if (ind == i_ok) {
                cout << "The phone number is " << phone << '\n';
            } else {
                std::cout << "There is no phone for " << name << std::endl;
            }
        }

    } catch (std::exception const &e) {
        std::cerr << "Error: " << e.what() << '\n';
    }
}

SOCI makes an extensive use of existing open-source libraries for increased functionality, speed and accuracy. In particular Boost (Boost) library is used. SOCI should work on GNU/Linux, Sun Solaris, Microsoft Windows (with Cygwin, MinGW/MSYS, or Microsoft Visual C++ .NET) and Mac OS X operating systems.

Next (Library structure, files and compilation)

Copyright © 2004-2009 Maciej Sobczak, Stephen Hutton