See also: [TableOfContents]
<h1>Welcome to cpdo, a database access abstraction library for C</h1>
cpdo is a database access abstraction API written in C and modeled heavily after the [http://php.net/manual/en/book.pdo.php| PHP PDO] API.
This web site is a [http://www.fossil-scm.org|Fossil] source code repository, containing the source code, bug tracker, etc., for this project. As of 2011-May-17, the wiki is maintained [http://fossil.wanderinghorse.net/wikis/cpdo/?page=cpdo|at a separate site].
<font color=blue><b>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.</b></font> This is to avoid that bots download every version of every file in the repository, or traverse the whole history of every source file.
<b>Code State:</b> "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, [http://fossil.wanderinghorse.net/repos/cson/|the cson project] makes use of cpdo to create JSON data and store persistent application session data.)
<b>License:</b> 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 [http://www.gnu.org/licenses/old-licenses/gpl-2.0.html|the GNU GPL v2] a few times.)
<b>Author:</b> [http://wanderinghorse.net|Stephan Beal]
<b>Downloading:</b> See the [download|download page].
* Whatever dependencies your chosen database driver(s) require(s).
* C99, or C89 plus the C99-specified <tt>stdint.h</tt> and <tt>inttypes.h</tt> 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 <em>C89</em> mode on 32-bit builds because of portability problems involving <tt>int64_t</tt>. e.g. the [cpdo_mysql5] driver does custom int64-to-string conversions in that configuration. (The core library itself has no such "missing" features.)
* Modeled heavily after the PHP PDO API, a commonly-used database access abstraction API, and supports most of the same operations.
* Includes a [cpdopp|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 (<tt>inttypes.h</tt> and <tt>stdint.h</tt>). The code is portable and compiles cleanly in with [http://bellard.org/tcc/|tcc] and gcc with all warnings (and gcc's <tt>-pedantic</tt>) turned on.
* Well-documented, in the form of API docs and the wiki pages.
* Includes drivers for [cpdo_sqlite3|sqlite3] and [cpdo_mysql5|MySQL 5].
* Supports float, double, <em>signed</em> integer (8- to 64 bits), string, and blob data. (i'd like to avoid adding <em>unsigned</em> numeric support, because it would add about 8 functions to the <tt>cpdo_stmt</tt> 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 <em>some</em> 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 - [AmalgamationBuild|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 <em>5 times faster</em> using [http://bellard.org/tcc/|tcc].
* 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: [TODOs|the TODO page].
Please see [News] page.