PG'OCaml provides an interface to PostgreSQL databases for OCaml applications. It uses Camlp4 to extend the OCaml syntax, enabling one to directly embed SQL statements inside the OCaml code. Moreover, it uses the describe feature of PostgreSQL to obtain type information about the database. This allows PG'OCaml to check at compile-time if the program is indeed consistent with the database structure. This type-safe database access is the primary advantage that PG'OCaml has over other PostgreSQL bindings for OCaml.
let () = let dbh = PGOCaml.connect () in let insert name salary email = PGSQL(dbh) "insert into employees (name, salary, email) values ($name, $salary, $?email)" in insert "Ann" 10_000_l None; insert "Bob" 45_000_l None; insert "Jim" 20_000_l None; insert "Mary" 30_000_l (Some "firstname.lastname@example.org"); let print_row (id, name, salary, email) = let email = match email with Some email -> email | None -> "-" in Printf.printf "%ld %S %ld %S\n" id name salary email in let rows = PGSQL(dbh) "select id, name, salary, email from employees" in List.iter print_row rows; PGOCaml.close dbh
The latest version is 2.2, released on 2015-04-08. Note that PG'OCaml comes in two varieties,
described below. Most users should pick the
pgocaml variant, since it is the only
one actively developed.
This variant is the successor to the older versions of PG'OCaml, developed by Richard W.M. Jones. The code base is unchanged and the API remains the same. If you have your own patches to PG'OCaml, then for compatibility reasons this is the code you want. Note, however, that this branch is no longer updated with new features, and no version higher than 1.3 is available.
Download pgocaml-classic-1.3.tgz (For OCaml >= 3.10)
Download pgocaml-classic-0.8.tgz (If you are still using OCaml < 3.10)
This branch began as a contribution by Jérôme Vouillon, and refactors PG'OCaml's internals and API to work in a monadic style (a compatibility mode with the old API is also available). Though flexible enough to be used with any monad, the most obvious use of this branch is to integrate PG'OCaml with an application that uses the light-weight threads of the Lwt library (a common example are applications developed to run with the Ocsigen web server). Furthermore, it includes a compatibility interface that allows you to write applications in a non-monadic fashion or to link existing applications without requiring any changes to their code. This branch is the only one actively developed, and the one recommended for all users!
Download pgocaml-2.2.tgz (Note: it requires OCaml >= 3.10)
You can also obtain the latest development snapshot from the project's page at GitHub.
PG'OCaml Copyright © 2006 Merjis Ltd, Richard W.M. Jones (email@example.com)
This software is distributed under the GNU LGPL with
the OCaml linking exception. Please see the file
for full license.
There are packages of PG'OCaml available in OPAM and in the repositories of some Linux distributions. This is the easiest way of installing the library. Check the following list for your distro: (please let us know of others)
If there are no binary packages available for your distro or you prefer to compile it yourself anyway, note that PG'OCaml has the following requirements: (all dependencies are available on the major distros)
The build system uses OASIS.
Issue the customary
make install to build and perform a findlib installation.
You may consult the current Changelog for an up-to-date summary of the changes in each release and on the Git master.
The preferred method of interaction between developers and users is via the pgocaml-general mailing-list. You are welcome to send us patches, suggestions, or error reports. However, please do so on the mailing-list.
Dario Teixeira wrote a tutorial for PG'OCaml: pgoctut.pdf
There is also the API documentation included with the package (issue
make doc), although it is rather sparse.
(This documentation is also available online,
for your convenience.)
Also see the source for COCANWIKI.
Please note that this is not the first or only PostgreSQL binding for OCaml. Here are some others you may wish to consider:
PG'OCAML is different from the above bindings:
crypt(3)isn't implemented, because we're not aware of any implementation of this function in OCaml. Anyway, crypt is insecure.
/usr/include/postgresql/catalog/pg_type.hto find the OID for your type, edit
pGOCaml.ml:name_of_typefunction to add the appropriate OID to type name mapping, and then add two functions
string_of_typeto perform the translation to and from strings.
It is fairly common to construct SQL statements from string fragments, as in this pseudocode example:
let order_clause = match key, reverse with | `Author, false -> "author asc" | `Author, true -> "author desc" | `Title, false -> "title asc" | `Title, true -> "title desc" in let sql = "select title, author from books order by " ^ order_clause
Such statement-building is not currently permitted by PG'OCaml, unless you ditch the Camlp4 extension and use the low-level, unsafe interface. It would be nice to have some sort of "fragment constructor" operator to allow the above to be expressed in a type-safe way. However because it is not possible to compile the fragments, it doesn't look like such a constructor could be written. If anyone has any ideas about this, please contact us.