]> Details about the libdbi driver providing support for &proper-name; backends David A. Parker Neon Goat Productions

david@neongoat.com

Document revision: $Id: dbd_pgsql.sgml,v 1.5 2005/09/20 22:35:29 mhoenicka Exp $ $Date: 2005/09/20 22:35:29 $ 0.2 2005-07-17 0.1 2003-4-17 2001-2003 David Parker, Neon Goat Productions Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in . libdbi is a database abstraction layer written in C. It implements a framework that can utilize separate driver libraries for specific database servers. The libdbi-drivers project provides the drivers necessary to talk to the supported database servers. This manual provides information about the &dbd-name; driver, which provides support for &proper-name; databases. The manual is intended for programmers who write applications linked against libdbi and who want their applications to use this database backend. Questions and comments about this driver should be sent to the libdbi-drivers-devel mailing list (see the website). Questions and comments about the libdbi library should be sent to the appropriate libdbi mailing list. This driver is maintained by &author-name;. PostgreSQL is an object-relational database management system (ORDBMS) based on POSTGRES, Version 4.2, developed at the University of California at Berkeley Computer Science Department. The POSTGRES project, led by Professor Michael Stonebraker, was sponsored by the Defense Advanced Research Projects Agency (DARPA), the Army Research Office (ARO), the National Science Foundation (NSF), and ESL, Inc. PostgreSQL is an open-source descendant of this original Berkeley code. It provides SQL92/SQL99 language support and other modern features. More information can be found from the &proper-name; website. This chapter describes the prerequisites and the procedures to build and install this driver from source code.

The following packages must be installed on your system: libdbi This library implements the core database abstraction layer, which provides your application with database backend functionality when paired with this driver. More information about libdbi, including mailing lists, documentation, bug reports, and downloads, is available from the libdbi website. libpq This is the C shared library to enable user programs to communicate with the PostgreSQL database backend. The backend can be on another machine and accessed through TCP/IP. This library is distributed as part of PostgreSQL, and can be found on their website. It may also be packaged independently for your operating system, depending on what you use. The current version of the dbd_pgsql driver was written and tested with libpq3 from PostgreSQL 8.0.1.

First you have to unpack the libdbi-drivers archive in a suitable directory. Unpacking will create a new subdirectory with the version number, such as libdbi-drivers-0.8.0 $ tar xfvz libdbi-drivers-0.8.0.tar.gz The libdbi-drivers project consists of several drivers that use a common build system. Therefore you must explicitly tell the configuration script that you want to build the &dbd-name; driver (you can list as many drivers as you want to build): $ cd libdbi-drivers-0.8.0 $ ./configure --with-&dbd-name; Run ./configure --help to find out about additional options and other available drivers. Then build the driver with the command: $ make Please note that you may have to invoke gmake, the GNU version of make, on some systems. Then install the driver with the command (you'll need root permissions to do this): $ make install To test the operation of the newly installed driver, use the command: $ make check This command creates and runs a test program that performs a few basic input and output tests. If for some reason you need to re-create the autoconf/automake-related files, try running ./autogen.sh. In some situations, the current stable autoconf/automake/libtool versions (as found in FreeBSD 4.7 and Debian 3.0) do not cooperate well, so it may be necessary to run the older autoconf 2.13. If necessary, edit autogen.sh so that it will catch the older autoconf version on your system.

Before you can initiate a connection, you must usually specify options that tell the database driver what to connect to. This driver supports the standard options of host, username, password, dbname, and port. You only need to set options that are specific to your application -- sensible defaults will be used for all unspecified options. This driver also offers the following non-standard options, and/or redefines the meaning of the following standard options: host If this begins with a slash, it specifies Unix-domain communication rather than TCP/IP communication; the value is the name of the directory in which the socket file is stored. port Port number to connect to at the server host, or socket file name extension for Unix-domain connections. encoding The IANA name of a character encoding which is to be used as the connection encoding. Input and output data will be silently converted from and to this character encoding, respectively. The list of available character encodings depends on your local PostgreSQL installation. If you set this option to "auto", the connection encoding will be the same as the database encoding. pgsql_options Trace/debug options to be sent to the server. pgsql_tty A file or tty for optional debug output from the backend. This chapter lists known peculiarities of the &dbd-name; driver. Wherever possible, nonstandard driver behavior is hidden by libdbi's abstractions, but occasionally special considerations must be taken or extra functionality may be utilized for particular drivers. PostgreSQL has no intrinsic concept of unsigned fields (although you can still use the "OID" type as an unsigned long, or define your own user-defined unsigned types). User-defined types are not handled specially. All unrecognized datatypes are preserved as strings. PostgreSQL does not support a 1-byte numeric datatype. &freedoc-license;