# &proper-name; Driver Notes

## Preface

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;.

## Introduction

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.

## Installation

This chapter describes the prerequisites and the procedures to build and install this driver from source code.

### Prerequisites

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.

### Build and install the driver

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.

## Driver options

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`, `timeout`, and `port`, as well as PostgreSQL-specific options. You only need to set options that are specific to your application -- sensible defaults will be used for all unspecified 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. The default behavior when `host` is not specified is to connect to a Unix-domain socket in /tmp (or whatever socket directory was specified when PostgreSQL was built).

port

- Port number to connect to at the server host, or socket file name extension for Unix-domain connections.

username

- The name of the user accessing the database.

password

- The password of the user accessing the database.

dbname

- The name of the database used for the initial connection. If your program must be able to connect to a fresh PostgreSQL installation, use the system database `template1`.

timeout (numeric)

- The connection timeout in seconds. If the option is not specified, or if it is 0 (zero), stale connections never time out.

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_foo

- Pass option `foo` directly to libpq. For valid options, refer to the libpq documentation.

## &proper-name;-specific Peculiarities

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;