Chapter 7. JDBC Interface

JDBC is a core API of Java 1.1 (and later) that provides Java applications with a standard set of interfaces through which database access can be done.

Red Hat Database provides type 4 JDBC drivers. Type 4 indicates that the driver is written in pure Java, and communicates with the database using the database's own network protocol. Because of this, the driver is platform independent; it can be used on any system that Java supports.

This chapter describes how to set up the JDBC drivers included with Red Hat Database and how to use the JDBC API. Red Hat Database's extensions to the JDBC driver are also described.

If you require further information on how to use JDBC, you can find the JDBC specification and tutorials at: http://java.sun.com/products/jdbc

Setting up the JDBC Driver

Requirements for Java/JDBC

To use Java/JDBC with Red Hat Database, you need a Java development kit (for application developers) or a Java runtime environment (for end-users) along with a JDBC driver. Software development kits and runtime environments are available from Sun (http://java.sun.com) and IBM (http://www-106.ibm.com/developerworks/java/), among others.

Getting the Driver

Red Hat Database ships with two drivers: one for JDBC version 1 and one for JDBC version 2. The version 1 driver is meant to be used in Java 1 environments (Java 1.1.x) while the version 2 driver is meant to be used in Java 2 environments (Java 1.2.x and Java 1.3.x). The drivers are contained in the rh-postgresql-jdbc package. Refer to the Red Hat Database Getting Started / Installation Guide for details on installing the package.

Note

As of Red Hat Database 7.1.3, the drivers are installed in the /usr/share/pgsql/java directory. The rh-pgsql-jdbc1.jar file is the JDBC 1 driver and rh-pgsql-jdbc2.jar is the JDBC 2 driver.

As Red Hat Database is powered by PostgreSQL, the drivers that are included with it are the PostgreSQL JDBC drivers. PostgreSQL's JDBC drivers are an open-source project and thus they are constantly being refined and improved. You can always find the most up-to-date drivers at http://jdbc.postgresql.org, PostgreSQL's JDBC home page.

As the drivers are written in pure Java, they will work with any Java system out of the box. Because there is no need to compile them yourself unless you are doing development work on the drivers, we will not cover building the drivers from source code.

Installing the Driver

The Red Hat Database JDBC drivers are distributed as jar archives. Once you have chosen one from the rh-postgresql-jdbc package, there is no need to unpack it. From hereon in, we will refer to the driver archive as rh-pgsql-jdbc2.jar.

Once you have obtained a driver you must make it available to your runtime environment. There are a couple of ways of doing this. The first method involves modifying your system's CLASSPATH environment variable. This can be done by modifying your shell's startup script or by passing a parameter to the java and javac programs when you run them. For example, if a user is using the bash shell, the following line could be put in their .bashrc file:

export CLASSPATH=/usr/share/pgsql/rh-pgsql-jdbc2.jar:.

Alternatively, either of the following could be used for running a Java program:
$ CLASSPATH=/usr/share/pgsql/rh-pgsql-jdbc2.jar:. java Bar
$ java -cp /usr/share/pgsql/rh-pgsql-jdbc2.jar:. Bar

Also included in the CLASSPATH is "." to indicate to java/javac that it should also look in the current directory for classes. This is useful when trying to run programs that have not been packaged into jar files.

The second method involves copying rh-pgsql-jdbc2.jar into the lib/ext directory of your runtime's tree. For example, if your runtime was installed in /usr/local/java/jre1.3.1, you could copy the driver to the /usr/local/java/jre1.3.1/lib/ext directory. If you had a developer's kit installed in /usr/local/java/jdk1.3.1, you would copy rh-pgsql-jdbc2.jar to the /usr/local/java/jdk1.3.1/jre/lib/ext directory. With this method, there is no need to modify the CLASSPATH variable.

Setting up Red Hat Database

The Red Hat Database JDBC driver uses TCP/IP to communicate with database servers. Thus in order to successfully use the driver, your Red Hat Database server needs to be configured to accept TCP/IP connections. This is done by setting the tcpip_socket setting to true in your postgresql.conf file and restarting the server. Refer to the Red Hat Database Administrator and User's Guide for more information on making this change.