DBD::PgPP
=========

DBD::PgPP - Pure-Perl DBI driver for the PostgreSQL database

DBD::PgPP is a pure-Perl client interface for the PostgreSQL database.  This
module implements the network protocol that allows a client to communicate
with a PostgreSQL server, so you don't need an external PostgreSQL client
library like libpq for it to work.  That means this module enables you to
connect to PostgreSQL server from platforms where there's no PostgreSQL
port, or where installing PostgreSQL is prohibitively hard.


DEPENDENCIES
------------

This module uses the following other modules and libraries:

  DBI
  IO::Socket (ships with supported Perl versions)
  Digest::MD5 (ships with supported Perl versions)


INSTALLATION
------------

To install this module, run the following:

   perl Makefile.PL
   make
   make test
   make install


TESTING
-------

The test suite requires access to a suitable PostgreSQL server; without
that, only an extremely limited form of testing is possible.

To tell the test suite how to find a PostgreSQL server, set the following
environment variables:

  DBI_DSN (required)
    A DBI "data source name" indicating the location of the database.  For
    example, to connect to the database named "abc" over a Unix-domain
    socket stored in /var/run/postgresql, use this DSN:

      export DBI_DSN='dbi:PgPP:dbname=abc;path=/var/run/postgresql'

    Or to connect to a database of the same name, using a TCP connection to
    pg.example.com, use this:

      export DBI_DSN='dbi:PgPP:dbname=abc;host=pg.example.com'

    See the DBD::PgPP documentation for full details on what can go into a
    DBD::PgPP DSN.

  DBI_USER (optional)
    The username to connect as; defaults to the database name

  DBI_PASS (optional)
    The password needed to allow the given user to authenticate to the
    server.  Some configurations of PostgreSQL allow connection without a
    password; you don't need to set a DBI_PASS in such cases.

Note that DBD::PgPP 0.05 and earlier versions used a different set of
environment variables for telling the test suite how to contact the
database.  The new variables are more flexible, more consistent with how
Perl code connects to a database, and more consistent with how other DBDs
(including DBD::Pg) accomplish the same task.


REPORTING BUGS
--------------

If you find what seems to be a bug in DBD::PgPP, please use RT to report it
to the maintainers:

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBD-PgPP

Please supply any information that could help with reproducing the bug.
For example, if the bug only appears when DBD::PgPP is used with certain
database schemas, a description (or even a dump) of the schema in question
would be useful.


MAINTENANCE
-----------

The current maintainer of DBD::PgPP no longer has cause to use it, and would
welcome the assistance of anyone who does -- or even a volunteer to take
over maintenance completely.

Even if you aren't in a position to do that, please report any bugs you
find; and if you want a new feature, please send tests for it (with or
without a sample implementation).

The code is hosted on GitHub, which should hopefully make it easy for others
to contribute.  The clone URL is:

  git://github.com/arc/dbd-pgpp.git

Feel free to fork and send me a pull request.


COPYRIGHT AND LICENCE
---------------------

Copyright (C) 2004 Hiroyuki OYAMA.  All rights reserved.
Copyright (C) 2004, 2005, 2009, 2010 Aaron Crane.  All rights reserved.

DBD::PgPP is free software; you can redistribute it and/or modify it under
the terms of Perl itself, that is to say, under the terms of either:

* The GNU General Public License as published by the Free Software Foundation;
  either version 2, or (at your option) any later version, or

* The "Artistic License" which comes with Perl.