Introduction 

Welcome to libpqxx, a C++ API to the PostgreSQL database management system.

There are many similar libraries for PostgreSQL and for other databases, some
of them database-independent.  Most of these, however, are fairly C-like in
their programming style, and fail to take advantage of the full power of the C++
language as it has matured since the acceptance of the Standard in 1996.  What 
libpqxx brings you is effective use of templates to reduce the inconvenience of
dealing with type conversions; of standard C++ strings to keep you from having 
to worry about buffer allocation and overflow attacks; of exceptions to take
the tedious and error-prone plumbing around error handling out of your hands;
of constructors and destructors to bring resource management under control; and
even basic object-orientation to give you some extra reliability features that
would be hard to get with most other database interfaces.

This package requires PostgreSQL to be installed--including the C headers for 
client development.  The library builds on top of PostgreSQL's standard C API, 
libpq.


Getting Started

All of this applies only to operating systems that are either part of, or
closely resemble, or support the standard interfaces of the Unix family.  This 
includes MacOS X (starting with 10.2, a.k.a. Jaguar) as well as Linux, the
various BSD systems, etc.  Windows users should skip to the Building on Windows
section.


To get started quickly on a Unix-like system, do:

./configure	# (plus suitable arguments, to set up the build environment)
make		# (to build the library)

# (set environment for regression test--IMPORTANT, see under "make check" below)
# (this example assumes a dedicated libpqxx test database called pqxx)
export PGDATABASE=pqxx

make check	# (to run the library's self-test suite; see below)
make install	# (with superuser privileges, to install the library; see below)

Once this has succeeded, you should be able to link your own programs with 
libpqxx.


1. Configure

But first, a word on those "suitable arguments."  These may or may not be
needed on your particular system, so do try omitting them at first.  The most 
important options are:

--with-postgres=<path>
to indicate the base PostgreSQL library and include path.  The build procedure 
expects to find subdirectories include/ and lib/ there.  If, for instance, you
have the PostgreSQL headers and libraries in /usr/local/pgsql/include/ and
/usr/local/pgsql/libs/ respectively, all you need to specify this to the
configure script is "--with-postgres=/usr/local/pgsql".  If your PostgreSQL
directories aren't laid out in this way, read on.

--with-postgres-include=<path>
to indicate just the PostgreSQL include path.  This is not needed if you use 
the --with-postgres option.  If, for instance, the PostgreSQL headers are not 
in your standard include path but in /usr/local/include/postgresql/, then what 
you need to specify is "--with-postgres=/usr/local/include/postgresql".

--with-postgres-lib=<path>
to indicate the path to PostgreSQL's libpq library.  If, for instance, this
library is in /usr/local/postgresql/lib, then you need to specify the configure
option "--with-postgres-lib=/usr/local/postgresql/lib/".

Sensible defaults have been provided for Debian and RedHat systems, among 
others.  If your system requires different settings, please let me know.


2. Make

One problem some people run into at this stage is that the header files for
PostgreSQL need the OpenSSL header files to work.  If this happens to you, make
sure openssl is installed and try again.

Otherwise, if the "make" part of the build procedure fails, you're probably
using a different compiler or compiler version than I am.  If your C++ compiler
is more than a few years old (say, gcc prior to 2.95 or Visual C++ up to 6.0),
just forget it.  It won't work until you get an up-to-date compiler.

If, on the other hand, you're using a shiny new compiler and you're getting
errors or warnings, please let me know about them so I can fix them.  


3. Make Check

This part is optional.  It is recommended that you do this, but there is one
Very Important Caveat that could affect your existing data.  See below.

This is where you compile and run the regression test that typically exercises 
all public methods in the library.  Obviously something or other will have to go
wrong at this point, right?

Indeed.  The "make check" procedure needs a database to play with.  In this
database, it will create two tables "events" and "orgevents," as well as some
tables for its own use whose names are prefixed with pqxx.  CAUTION: if this
database already contains tables with any of these names, either the check will
fail, or worse, the original data will be erased.

So choose your test database with caution.  Obviously the safest thing to do is
to set up a separate database for this.

To direct the regression test to the right database, set the following
environment variables as needed before running "make check":

	PGDATABASE	(name of database; defaults to your user name)
	PGHOST		(database server; defaults to local machine)
	PGPORT		(PostgreSQL port to connect to; default is 5432)
	PGUSER		(your PostgreSQL user ID; defaults to your login name)

This should get you through the regression test to ensure that everything's
working properly.  If it isn't, and it's not something you can fix by tweaking
your PostgreSQL setup, let me know about it and I'll try to fix it.


4. Make Install

This is supposed to install the libpqxx library and header files to your
system.  It took me some time to get this to actually work, so please take care
to check that it really does work and that especially the headers are really
installed to your system.

The library and headers are installed to a new directory /usr/local/pqxx/ by 
default, in their respective subdirectories include/ and lib/.  This will 
probably change in the near future.

Assuming this succeeds, you should now be able to build your own programs by
adding /usr/local/pqxx/include to your include path, and /usr/local/pqxx/lib to
your library search path.  See the documentation and the test programs for more
information on using libpqxx.

One other thing here that may not work is that, if you link with the dynamic
version of the library, your program may fail to run because the run-time 
loader cannot find the library.  You can get around this by (i) linking to the
static version of the library, or (ii) adding a link in /usr/local/lib to the
dynamic libpqxx library, or (iii) adding libpqxx's lib/ directory to your
loader's search path.  This is in decreasing order of preference, so try (i)
first, and only resort to (iii) if both (i) and (ii) fail.

Enjoy!


Building on Windows

Project files for Visual C++ are provided.  These are not actively maintained,
however, so they may need some tweaking.  Also, you'll probably need at least
version 7 of that compiler, earlier versions being too severely flawed to build
serious post-1996 C++ code.  The library is also known to build with Intel's 
compiler running as a Visual C++ plugin, but the details are beyond me.

Instead of going this route, you may want to try if the Unix build procedure
works for you instead, e.g. using the Cygwin tools.  If it doesn't, you'll need
to manually edit the compile-time configuration file include/pqxx/config.h to 
define the features your system, compiler, and PostgreSQL versions support.  
Normally the configure script would do this for you.

If you're using Microsoft's compiler, you'll probably need to define the
preprocessor macro NO_PARTIAL_CLASS_TEMPLATE_SPECIALISATION in the config.h file
to work around what appears to be a compiler bug in Visual C++.NET.

Good luck!

