Author: Written by Peter T. Mount (<peter@retep.org.uk>), the author of the JDBC driver.
JDBC is a core API of Java 1.1 and later. It provides a standard set of interfaces to SQL-compliant databases.
Postgres provides a type 4 JDBC Driver. Type 4 indicates that the driver is written in Pure Java, and communicates in the database system's own network protocol. Because of this, the driver is platform independent; once compiled, the driver can be used on any system.
This chapter is not intended as a complete guide to JDBC programming, but should help to get you started. For more information refer to the standard JDBC API documentation. Also, take a look at the examples included with the source. The basic example is used here.
Precompiled versions of the driver are regularly made available on the PostgreSQL JDBC web site. Here we describe how to build the driver manually.
Starting with PostgreSQL version 7.1, the JDBC driver is built using Ant, a special tool for building Java-based packages. You should download Ant from the Ant web site and install it before proceeding. Precompiled Ant distributions are typically set up to read a file .antrc in the current user's home directory for configuration. For example, to use a different JDK than the default, this may work:
JAVA_HOME=/usr/local/sun-jdk1.3 JAVACMD=$JAVA_HOME/bin/java
The build the driver, add the --with-java option to your configure command line, e.g.,
$ ./configure --prefix=xxx --with-java ...This will build and install the driver along with the rest of the PostgreSQL package when you issue the gmake and gmake install commands. If you only want to build the driver and not the rest of PostgreSQL, change into the directory src/interfaces/jdbc and issue the respective make command there. Refer to the PostgreSQL installation instructions for more information about the configuration and build process.
Note: Do not try to build by calling javac directly, as the driver uses some dynamic loading techniques for performance reasons, and javac cannot cope. Do not try to run ant directly either, because some configuration information is communicated through the makefiles. Running ant directly without providing these parameters will result in a broken driver.
To use the driver, the jar archive postgresql.jar needs to be included in the class path, either by putting it in the CLASSPATH environment variable, or by using flags on the java command line. By default, the jar archive is installed in the directory /usr/local/pgsql/share/java. You may have it in a different directory if you used the --prefix option when you ran configure.
For instance, I have an application that uses the JDBC driver to access a large database containing astronomical objects. I have the application and the JDBC driver installed in the /usr/local/lib directory, and the Java JDK installed in /usr/local/jdk1.1.6. To run the application, I would use:
export CLASSPATH=/usr/local/lib/finder.jar(1):/usr/local/pgsql/share/java/postgresql.jar:. java uk.org.retep.finder.Main
Loading the driver from within the application is covered in Section 8.2.
Because Java can only use TCP/IP connections, the Postgres server must be configured to accept TCP/IP connections, for instance by supplying the -i option flag when starting the postmaster.
Also, the client authentication setup in the pg_hba.conf file may need to be configured. Refer to the Administrator's Guide for details. The JDBC Driver supports trust, ident, password, and crypt authentication methods.