[C++ Toolkit ANNOUNCE] NCBI database API: the "driver" part is ready

[Denis Vakatov]

  "NCBI database API (DBAPI)"
  is a new C++ Toolkit project to provide the means to seamlessly
  connect to and communicate with various RDBMS
  (such as Sybase, MS SQL Server, etc.) using different underlying
  client libraries (such as CTLIB, DBLIB, FreeTDS, etc.).

  Here is an announcement about the "driver" part of the DBAPI.


------------

The "driver" part of the DBAPI has been written and incorporated
into the C++ Toolkit. Presently, it includes the following
(relatively stable and working) parts:

  1) Public API and docs -- for regular users
  2) Driver API -- for driver developers (includes a small test API)
  3) Implementation of 3 drivers -- for CTLIB, DBLIB and FreeTDS

Note 1.  Presently, we have only UNIX based DBAPI drivers implemented,
         however the works are underway to implement more drivers, in
         particular for MS Windows with MS SQL server and a "bridge"
         driver to provide built-in client/server functionality
         (by Victor Sapojnikov, see below).

Note 2.  The "driver" public API, however portable, is a relatively low-level,
         and there is a higher level API (by Michael Kholodov) under
         active development right now -- it is expected to be
         finished in a matter of weeks.


***** ON-LINE DOCS

  http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/libs.html#ref_TableDBAPI_DRIVER
  http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/libs/dbapi_driver.html



***** PUBLIC INTERFACES

  http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/include/dbapi/driver/

 public.hpp     --  Context, connection, command and result classes
 types.hpp      --  Data types (e.g. CDB_Int, CDB_DateTime, CDB_Text)
 exception.hpp  --  Exceptions and error handling



***** EXAMPLES

Generic code for all test examples:

  http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/src/dbapi/driver/samples/dbapi_driver_samples.cpp


Driver-specific tests calling the generic code ("dbapi_driver_samples.cpp")
for implemented (CTLIB, DBLIB and FreTDS) drivers:

  http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/src/dbapi/driver/ctlib/samples/
  http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/src/dbapi/driver/dblib/samples/
  http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/src/dbapi/driver/ftds/samples/

   ctl_lang.cpp
   ctl_sp_who.cpp



***** CAVEATS

"DBLIB" driver --
    Text/image operations fail when working with MS SQL server,
    because MS SQL server sends text/image length in the reverse byte order,
    and this cannot be fixed (as it was fixed for FreeTDS) as we do not
    have access to the DBLIB source code.

"FreeTDS" driver --
    1) BCP operations do not work at all. 
    2) The "compute results" functionality (like from SELECT ... AVERAGE ...)
       does not work as the current FreeTDS implementation cannot decipher
       the "compute results" specific result set returned by server.
    3) RPC is implemened via a language call, so it will work only if
       the OpenServer it's communicating with has language handler installed
       (and it's not installed on some NCBI OpenServers).
    4) The FreeTDS client library (the one using TDS protocol version 7.0)
       presently installed in NCBI at "/netopt/Sybase/clients-mssql/current"
       was tweaked to work with the MS SQL server and significantly optimized
       (by Eugene Yaschenko). However it will not work with Sybase server.
    5) Another, earlier non-tweaked version of FreeTDS client library
       theoretically should be able to work with both MS SQL and SYBASE servers
       (using TDS protocol version 4.2), however it was not thoroughly tested
       and can be pretty slow.



***** CREDITS (major)

Vladimir Soussov --
   Principal designer of the "driver" part of the NCBI DB API.
   Author of the first working draft of generic API and library,
   CTLIB and DBLIB drivers, and test suite.
   Author of the FreeTDS driver. Author of the driver docs.

Denis Vakatov --
   Put up the original proposal for developing the NCBI DB API, held first
   meetings to discuss the overall DBAPI concepts and structure.
   Later, performed a major revamp (in collaboration with Vladimir Soussov)
   of the generic API and CTLIB driver code, and incorporated them into the
   NCBI C++ Toolkit. Added to some of the docs.

Anton Lavrentiev --
   Performed a major revamp (in collaboration with Vladimir Soussov) of
   DBLIB driver code, reorganized test suite.



***** ON-GOING DEVELOPMENTS and FUTURE PLANS

Victor Sapojnikov --
   [in progress] Port DBLIB driver to work under MS Windows with MS SQL server.
   [future plan] Design and implement a "bridge" driver
                 using "NCBI compact protocol" (written by V.Soussov) as
                 communication protocol.

Vladimir Soussov --
   [in progress] Write a (sketchy) documentation/overview on the public
                 part of the "driver" layer of DB API. 

Anton Butanaev --
   [future plan] Design and implement the "user" layer of DB API.

Vladimir Soussov, Anton Butanaev --
   [future plan] Implement "MySQL" driver.

Michael Kholodov --
   [in progress] Design and implement the "mini-driver" layer of DB API.
                 The working draft already exists.
                 Revise the "mini-driver" API (w/Denis Vakatov).