cpdo  cpdo

See also: TableOfContents

Welcome to cpdo, a database access abstraction library for C

cpdo is a database access abstraction API written in C and modeled heavily after the PHP PDO API.

This web site is a Fossil source code repository, containing the source code, bug tracker, etc., for this project. As of 2011-May-17, the wiki is maintained at a separate site.

To be able to download the code or use most of the hyperlinks on this site, you must click the /login link and log in as "anonymous" with the password shown on the screen. This is to avoid that bots download every version of every file in the repository, or traverse the whole history of every source file.

Code State: "functional enough for use", with only a few (possibly) relevant bits missing, but young and beta, only lightly tested "in the wild." The cpdo_sqlite3 and cpdo_mysql5 drivers seem to work as expected, but the API stills needs a few finishing touches. (As of April 2011, the cson project makes use of cpdo to create JSON data and store persistent application session data.)

License: the core library is released under a dual Public Domain/MIT license, free for any use without legal restrictions. Specific drivers may have arbitrary licenses, likely inherited from the underlying 3rd-party driver. (i've actually seen people release MySQL-based code as Public Domain, BSD, or under some other non-viral terms. If you don't think that's odd then go read the GNU GPL v2 a few times.)

Author: Stephan Beal

Downloading: See the download page.

Requirements:

  • Whatever dependencies your chosen database driver(s) require(s).
  • C99, or C89 plus the C99-specified stdint.h and inttypes.h headers (for fixed-size integer types and their portable printf/scanf format specifiers). There may be one or two minor features which will not compile warning-free (and are disabled automatically if possible) in C89 mode on 32-bit builds because of portability problems involving int64_t. e.g. the cpdo_mysql5 driver does custom int64-to-string conversions in that configuration. (The core library itself has no such "missing" features.)

Primary Features

  • Modeled heavily after the PHP PDO API, a commonly-used database access abstraction API, and supports most of the same operations.
  • Includes a C++ wrapper.
  • Can abstract access to essentially arbitrary database APIs using a model familiar to many coders.
  • Implemented in portable ANSI C. It will compile in C89 or C++ mode but requires 2 C99 headers (inttypes.h and stdint.h). The code is portable and compiles cleanly in with tcc and gcc with all warnings (and gcc's -pedantic) turned on.
  • Well-documented, in the form of API docs and the wiki pages.
  • Includes drivers for sqlite3 and MySQL 5.
  • Supports float, double, signed integer (8- to 64 bits), string, and blob data. (i'd like to avoid adding unsigned numeric support, because it would add about 8 functions to the cpdo_stmt class' API, but could possibly be convinced to add it if shown a good reason to do so.)
  • Adds very little memory overhead and does surprisingly little extra copying of data between the client and server (in particular with the cpdo_mysql5 driver).
  • Has some support for binding driver-specific types, at least for fetching purposes. e.g. MySQL TIME/DATE/TIMESTAMP fields can be fetched as strings. (Yes, that's more difficult than it sounds, thank you very much.) Some infrastructure exists for binding db-specific types, but the API isn't quite there yet (and i'm not 100% sure it will work as i envision it).
  • Very thorough error checking/handling. All errors are reported to the client (who ignores them at his own peril), and the library can always fail without crashing when used as documented, even in the face of out-of-memory errors.
  • Free of memory leaks (or that's what valgrind keeps telling me).
  • Small and builds quickly - the "amalgamation build", including the sqlite3 and mysql drivers, compiles in well under a second with gcc on my machine (a 2.somethingGHz PC) and about 5 times faster using tcc.

Primary Misfeatures

  • Young and Beta. (It was born on the weekend of 2011-01-29.)
  • Does not, and probably never will, support advanced DB-specific features like seekable cursors, random access to blob record data, etc.
  • It does no string encoding/decoding itself, but generally expects string data to be valid UTF8.
  • It does not, and probably never will, have an API for working with UTF16 (like sqlite3 does).

See also: the TODO page.

Lastest News

Please see News page.