Developing Your Own Backends

Even if your database is not supported directly by one of the backends, take a look on ODBC backend, and see how well your database driver behaves with it. It may solve the problem for you.

Before you begin make sure you are familiar with CppDB library and know how to use it. Take a look to the source code of existing backends, it is good to take a look on PostgreSQL and Sqlite3 backends implementations.

What Need to Implement

You need to implement following 3 classes:

1. cppdb::backend::connection - the object that holds connection to the database - similar to cppdb::session.
2. cppdb::backend::statement - the object that holds prepared (or unprepared) statement - similar to cppdb::statement
3. cppdb::backend::result - the object that holds the result of query - similar to cppdb::result

You may safely assume that:

• As long as result exists, the statement that created it would exist.
• As long as statement exists, the connection that created it would exist.

The frontend classes make sure that this happens.

Making Loadable Module

You need to implement a single entry point in your library with the following prototype. It is very important to make the entry point function extern "C" so it would be resolved using dlsym or GetProcAddress functions and it should be marked as "__declspec(dllexport)" if it is compiled as Windows DLL.

It should be named it as cppdb_xyz_get_connection where xyz is the name of your backend.

It should receive as a parameter a const reference to cppdb::connection_info returning newly created connection.

For example, in sqlite3 backend this function looks like this:

extern "C" {
        CPPDB_DRIVER_API cppdb::backend::connection *cppdb_sqlite3_get_connection(cppdb::connection_info const &cs)
        {
                return new cppdb::sqlite3_backend::connection(cs);
        }
}

The shared object or DLL themselves should be named as cppdb_xyz - so under Linux it would be libcppdb_xyz.so and under Windows MSVC it would be "cppdb_xyz.dll". It is also good idea to give it same soname as the libcppdb.so itself as it would allow keeping several backend versions for several versions of libcppdb in future as CppDB always tries to load a module as "libcppdb_xyz.so.V" and only then "libcppdb_xyz.so" where V is the current CppDB library soname.

Making Statically Linked only Module

Of course if you want to link your module statically only, you do not have to create this single entry point function, you may derive from cppdb::backend::driver class such as its open() function would return a new connection object and in_use() function would always return true so the module would not be "unloaded".

Such module can be installed using cppdb::driver_manager driver_manager singleton class using its install_driver() member function. For example:

 class my_cool_sql_driver {
 public:
    cppdb::backend::connection *open(cppdb::connection_info const &ci) {
       return new my_cool_sql::connection(ci);
    }
    bool in_use() { return true; }
 };
 ...
 cppdb::driver_manager::instance().install_driver("mycoolsql",new my_cool_sql_driver());

Of course if you have the extern "C" function as shown above you can do the same trick using cppdb::backend::static_driver.

 extern "C" {
    cppdb::backend::connection *my_cool_sql_open(cppdb::connection_info const &ci) {
       return new my_cool_sql::connection(ci);
    }
 }
 ...
 cppdb::driver_manager::instance().install_driver("mycoolsql",new cppdb::backend::static_driver(my_cool_sql_open));

Tips

• Use functions from utils.h and numeric_util.h they are very helpful especially in converting data to and from textual representation.
• When converting numbers to strings and backwards make sure you are using std::locale::classic(), otherwise when inserting 12345.678 you may accidentally get "12.345,678" which is probably not what you want. Do it as following:

    std::ostringstream ss;
    ss.imbue(std::locale::classic());
    ss << number;
    std::string text_value = ss.str();
  

  And do the same for parsing.
• Try to reduce memory coping as much as possible when handing large texts and objects, remember that when std::string is binded it remains valid till actual statement execution so it is likely that you can just keep a reference on it rather then copying the string itself.
• Don't bother too much about statements caching or connection pooling. Front-end classes do this for you.