README
1DBD::PgPP
2=========
3
4DBD::PgPP - Pure-Perl DBI driver for the PostgreSQL database
5
6DBD::PgPP is a pure-Perl client interface for the PostgreSQL database. This
7module implements the network protocol that allows a client to communicate
8with a PostgreSQL server, so you don't need an external PostgreSQL client
9library like libpq for it to work. That means this module enables you to
10connect to PostgreSQL server from platforms where there's no PostgreSQL
11port, or where installing PostgreSQL is prohibitively hard.
12
13
14DEPENDENCIES
15------------
16
17This module uses the following other modules and libraries:
18
19 DBI
20 IO::Socket (ships with supported Perl versions)
21 Digest::MD5 (ships with supported Perl versions)
22
23
24INSTALLATION
25------------
26
27To install this module, run the following:
28
29 perl Makefile.PL
30 make
31 make test
32 make install
33
34
35TESTING
36-------
37
38The test suite requires access to a suitable PostgreSQL server; without
39that, only an extremely limited form of testing is possible.
40
41To tell the test suite how to find a PostgreSQL server, set the following
42environment variables:
43
44 DBI_DSN (required)
45 A DBI "data source name" indicating the location of the database. For
46 example, to connect to the database named "abc" over a Unix-domain
47 socket stored in /var/run/postgresql, use this DSN:
48
49 export DBI_DSN='dbi:PgPP:dbname=abc;path=/var/run/postgresql'
50
51 Or to connect to a database of the same name, using a TCP connection to
52 pg.example.com, use this:
53
54 export DBI_DSN='dbi:PgPP:dbname=abc;host=pg.example.com'
55
56 See the DBD::PgPP documentation for full details on what can go into a
57 DBD::PgPP DSN.
58
59 DBI_USER (optional)
60 The username to connect as; defaults to the database name
61
62 DBI_PASS (optional)
63 The password needed to allow the given user to authenticate to the
64 server. Some configurations of PostgreSQL allow connection without a
65 password; you don't need to set a DBI_PASS in such cases.
66
67Note that DBD::PgPP 0.05 and earlier versions used a different set of
68environment variables for telling the test suite how to contact the
69database. The new variables are more flexible, more consistent with how
70Perl code connects to a database, and more consistent with how other DBDs
71(including DBD::Pg) accomplish the same task.
72
73
74REPORTING BUGS
75--------------
76
77If you find what seems to be a bug in DBD::PgPP, please use RT to report it
78to the maintainers:
79
80 http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBD-PgPP
81
82Please supply any information that could help with reproducing the bug.
83For example, if the bug only appears when DBD::PgPP is used with certain
84database schemas, a description (or even a dump) of the schema in question
85would be useful.
86
87
88MAINTENANCE
89-----------
90
91The current maintainer of DBD::PgPP no longer has cause to use it, and would
92welcome the assistance of anyone who does -- or even a volunteer to take
93over maintenance completely.
94
95Even if you aren't in a position to do that, please report any bugs you
96find; and if you want a new feature, please send tests for it (with or
97without a sample implementation).
98
99The code is hosted on GitHub, which should hopefully make it easy for others
100to contribute. The clone URL is:
101
102 git://github.com/arc/dbd-pgpp.git
103
104Feel free to fork and send me a pull request.
105
106
107COPYRIGHT AND LICENCE
108---------------------
109
110Copyright (C) 2004 Hiroyuki OYAMA. All rights reserved.
111Copyright (C) 2004, 2005, 2009, 2010 Aaron Crane. All rights reserved.
112
113DBD::PgPP is free software; you can redistribute it and/or modify it under
114the terms of Perl itself, that is to say, under the terms of either:
115
116* The GNU General Public License as published by the Free Software Foundation;
117 either version 2, or (at your option) any later version, or
118
119* The "Artistic License" which comes with Perl.
120