DBD::Pg  --  the DBI PostgreSQL interface for Perl

# $Id: README,v 1.56 2006/04/09 17:54:14 turnstep Exp $

DESCRIPTION:
------------

This is version 1.49 of DBD-Pg.  The web site for this interface is at:

	http://gborg.postgresql.org/project/dbdpg/projdisplay.php

For further information about DBI look at:

	http://dbi.perl.org/

For information about PostgreSQL, visit:

	http://www.postgresql.org/


COPYRIGHT:
----------

	Copyright (c) 2002-2006 PostgreSQL Global Development Group
	Portions Copyright (c) 2002 Jeffrey W. Baker
	Portions Copyright (c) 1997-2001 Edmund Mergl
	Portions Copyright (c) 1994-1997 Tim Bunce

You may distribute under the terms of either the GNU General Public
License or the Artistic License, as specified in the Perl README file.


HOW TO GET THE LATEST VERSION:
------------------------------

Use the following URL to look for new versions of this module: 

http://search.cpan.org/~dbdpg/


IF YOU HAVE PROBLEMS OR COMMENTS:
---------------------------------

Please send any problems and comments to 
<dbdpg-general@gborg.postgresql.org>

Please include what OS you are using, and the version of Perl, 
DBI, and DBD::Pg you are using. Also tell which version of 
PostgreSQL DBD::Pg was compiled against, and which version you 
are connecting to. The easiest way to gather all of this 
information is to run "make test", which outputs it all early in 
the tests.


BUG REPORTS
-----------

If you feel certain you have found a bug, you can file a bug report 
by visiting:
http://rt.cpan.org/Public/Dist/Display.html?Name=DBD-Pg
and selecting the "Report a new bug" link. Please check that the bug 
has not already been reported first.


REQUIREMENTS:
-------------

	build, test, and install Perl 5         (at least 5.6.1)
	build, test, and install the DBI module (at least 1.45)
	build, test, and install PostgreSQL     (at least 7.3)
	build, test, and install Test::Simple   (at least 0.30)

You must also have the pg_config executable installed (to check, type 
"which pg_config" on unix-like systems). If pg_config is not available, 
then you need to install the development package for PostgreSQL. For example 
on Debian: apt-get install postgresql-dev; on RedHat: yum postgresql-devel. 
This development package is needed even if you already have PostgreSQL up 
and running since DBD::Pg uses it for its installation.

INSTALLATION:
-------------

Before installing, please use the "cpansign -v" program to cryptographically 
verify that your copy of DBD::Pg is complete and valid. The program 
"cpansign" is part of Module::Signature, available from CPAN.

By default Makefile.PL uses App::Info to find the location of the
PostgreSQL library and include directories.  However, if you want to
control it yourself, define the environment variables POSTGRES_INCLUDE 
and POSTGRES_LIB, or define just POSTGRES_HOME. Note that if you have 
compiled PostgreSQL with SSL support, you must define the POSTGRES_LIB
environment variable and add "-lssl" to it, like this:

	export POSTGRES_LIB="/usr/local/pgsql/lib -lssl"

Now, take the usual steps to install DBD::Pg:

	1.   perl Makefile.PL
	2.   make
	3.   make test
	4.   make install

Do steps 1 to 3 as a normal user, not as root!


TESTING:
--------

The tests are designed to connect to a live database.  The following
environment variables must be set for the tests to run:

	DBI_DSN=dbi:Pg:dbname=<database>
	DBI_USER=<username>
	DBI_PASS=<password>

If you are running on a non-standard port, you must add it 
to the DBI_DSN variable like this:

	DBI_DSN='dbi:Pg:dbname=<database>;port=<port#>'

Put double quotes around the dbname if it has a semicolon 
or a space inside of it:

	DBI_DSN='dbi:Pg:dbname="<data;base>"'

The tests assume that a schema named "public" is available for 
7.3 and greater servers. To override this, set the environment 
variable DBD_SCHEMA to a valid schema before testing.

You can increase the verbosity of the tests by setting the 
environment variable TEST_VERBOSE. You can also enable tracing 
within the tests themselves by setting DBD_TRACE to whatever 
trace level you want. Be aware that setting the trace level can 
result in extremely verbose output.

When reporting test failures, please use TEST_VERBOSE=1, do *not* 
set DBD_TRACE unless requested, and send only the relevant sections.


TROUBLESHOOTING:
----------------

* Placeholder issues

If you find that some of your queries containing placeholders are no 
longer working, this may because DBD::Pg now uses the native PostgreSQL 
placeholders on the server itself whenever possible. Previously, DBD::Pg 
did a simple emulation of placeholders, so the rules were not as strict.
You should either rewrite your queries to make them legal SQL syntax for 
PostgreSQL, or turn off server-side prepares.

To change your queries, make sure that the type of each placholder can 
be determined by the PostgreSQL parser. So instead of:

  SELECT ?

use something like:

  SELECT ?::int

To turn off server-side prepares completely (with a loss of some performance 
and features), do this at the top of your scripts:

$dbh->{pg_server_prepare} = 0;

This can also be set for individual queries at the statment handle level: see 
the documentation for more details.

* PostgreSQL library issues:

If you are using the shared library libpq.so check if your dynamic
loader finds libpq.so. With Linux the command /sbin/ldconfig -v should
tell you where it finds libpq.so. If ldconfig does not find libpq.so,
either add an appropriate entry to /etc/ld.so.conf and re-run ldconfig
or add the path to the environment variable LD_LIBRARY_PATH.

A typical error message resulting from not finding libpq.so is: 

	install_driver(Pg) failed: Can't load './blib/arch/auto/DBD/Pg/Pg.so' 
	for module DBD::Pg: File not found at

If you get an error message like:

	perl: error while loading shared libraries:
	/usr/lib/perl5/site_perl/5.6.1/i386-linux/auto/DBD/Pg/Pg.so: undefined
	symbol: PQconnectdb

when you call DBI->connect, then your libpq.so was probably not seen at
build-time.  This should have caused 'make test' to fail; did you really
run it and look at the output? Check the setting of POSTGRES_LIB and
recompile DBD-Pg.
 

* Perl issues:

Some Linux distributions have incomplete perl installations.  If you have
compile errors like "XS_VERSION_BOOTCHECK undeclared", do:

	find .../lib/perl5 -name XSUB.h -print

If this file is not present, you need to recompile and re-install perl.


If you get a message about "use of uninitialized value in -d" when doing 
a "make install_vendor", you can work around this by adding a dummy value 
to the INSTALLVENDORBIN environment variable:

make install_vendor INSTALLVENDORBIN=/tmp
(thanks to Peter Eisentraut <peter_e at gmx.net>)


* SGI issues:

If you get segmentation faults, make sure you are using the malloc
which comes with perl when compiling perl (the default is not to).
(thanks to "David R. Noble" <drnoble at engsci.sandia.gov>)


* HP issues:

If you get error messages like:

	can't open shared library: .../lib/libpq.sl
	No such file or directory

when running the test script, try to replace the 'shared' option in the
LDDFLAGS with 'archive'.
(thanks to Dan Lauterbach <danla at dimensional.com>)


* FreeBSD issues:

If you get during "make test" the error message:

	'DBD driver has not implemented the AutoCommit attribute'

recompile the DBI module and the DBD-Pg module and disable optimization.
This error message is due to the broken optimization in gcc-2.7.2.1.


If you get compiler errors like:

	In function `XS_DBD__Pg__dr_discon_all_'
	`sv_yes' undeclared (first use in this function)

it may be because there is a 'patchlevel.h' file from another package 
(such as 'hdf') in your POSTGRES_INCLUDE dir.  The presence of this file 
prevents the compiler from finding the perl include file 
'mach/CORE/patchlevel.h'.  Do 'pg_config --includedir' to identify the 
POSTGRES_INCLUDE dir.  Rename patchlevel.h whilst you build DBD::Pg. 


* Sun issues:

If you get compile errors like:

	/usr/include/string.h:57: parse error before `]'

then you need to remove from pgsql/include/libpq-fe.h the define for
strerror, which clashes with the definition in the standard include
file.


* Win32 issues:

For installation, please see the README.win32 file.

Running DBD-Pg scripts on Win32 needs some configuration work
on the server side:

    o add a postgres user with the same name as the NT-User 
      (eg Administrator)
    o make sure, that your pg_hba.conf on the server is configured,
      such that a connection from another host will be accepted


* OS X issues:

You may need to add "-lssl" and "-lcrypto" to your LIB variable 
before compiling.
(thanks to <rob at cabrion dot com>)

If having problems compiling, try running:

env -i command

This trick stops 'command' from inheriting environment variables from 
the shell process, which more often than not fixes up such weird build 
errors without having to do anything else in particular.
(thanks to David Landgren <david at landgren dot net>)


* SCO issues:

If the 'make test' gives an error about a symbol not being found, 
you can correct the problem by manually running ld after the 
'make' command:

LD_RUN_PATH="/usr/local/pgsql/lib" ld -G -L/usr/local/lib Pg.o \
dbdimp.o -o blib/arch/auto/DBD/Pg/Pg.so -L/usr/local/pgsql/lib -lpq \
-L/opt/K/SKUNK2000/Gcc/2.95.2pl1/usr/local/lib/gcc-lib/i386-pc-sco3.2v5.0.5/2.95.2/ \
-lgcc

Once this is done, 'make test' succeeds properly.
(thanks to <jmore at remote-print.com>)