Building The Driver

First we need to configure the makefile system to recognize that we're using Java. Go into the top level of the PostgreSQL archive directory, and type "configure --with-java". This will regenerate Makefiles as necessary, and if necessariy, it will add support for Java.

Next is actually building the driver and implementations. In the src/interfaces/jdbc" directory, just type "make". This will build two jar files: postgresql.jar, containing the Driver class and other concrete implementations, and postgresql-examples.jar, containing compiled example classes.

Using the built driver

First, add "postgresql.jar" to your CLASSPATH. This can be done either by setting your CLASSPATH environment variable, or by passing it as an argument on the command line. For more information, see your JVM vendor's instructions for setting your classpath.

Then we need to ensure that the Driver gets registered. When the Driver class passes through the Java class loader, it registers itself with the "DriverManager" class so that JDBC will know what Driver to use when connecting to a specific type of database. For instance, when we connect to a PostgreSQL database, we'd obviously use the PostgreSQL Driver class.

To make sure that our Driver class passes through the class loader, you can do a lookup by class name:

try {
        Class.forName("org.postgresql.Driver");
} catch (ClassNotFoundException cnfe) {
        System.err.println("Couldn't find driver class:");
        cnfe.printStackTrace();
}

"Class.forName" is a method that finds a class by name. In this case, we look for the Driver. This causes the class loader to search through the CLASSPATH and find a class by that name. If it finds it, the class loader will then read in the binary description of the class. If it does not find it, it will throw a "ClassNotFoundException", in which case we print out an error message. If you reach this state, you either haven't built the driver correctly, or the built jar file is not in your classpath.

Once we've registered this class, we need to request a connection to a PostgreSQL database. We use a class called "DriverManager" to do this. The "DriverManager" class is responsible for handling JDBC URLs, finding an appropriate Driver, and then using that Driver to provide a Connection to the database.

JDBC URLs are of the following format:

jdbc:<type of driver>:<which database to connect to>

The first part, "jdbc", is constant. It just represents that we are connecting to a jdbc data source. The second part, "<type of driver>", represents what kind of database we want to connect to. In this case, this is "postgresql". This part of the URL allows the DriverManager to find the PostgreSQL Driver and use it to connect. The third part is passed off to the Driver, and then the Driver can use this to find the actual database. This part takes one of three formats:

databasename

//hostname/databasename

//hostname:portnumber/databasename

In the first case, the PostgreSQL database is running on the local machine, on the default port number. The "databasename" is the actual name of the database you created. The second case is used for when you want to specify a hostname and a database. This also uses the default port number. The third case allows you to specify a port number as well. Even if you use the first type of URL, the JDBC connection will always be made via TCP/IP.

For the purposes of the examples from now on, we'll be using the URL: "jdbc:postgresql://example/bookstore", meaning we are connecting to host "example" and database "bookstore". With that in mind, let's try to make a connection, using all we've learned so far:

import java.sql.DriverManager;
import java.sql.Connection;
import java.sql.SQLException;

public class Example1 {
    public static void main(String[] argv) {
        System.out.println("First we look up the Driver, to make sure it gets registered with the DriverManager.");
        
        try {
            Class.forName("org.postgresql.Driver");
        } catch (ClassNotFoundException cnfe) {
            System.out.println("We couldn't find the driver, so let's print a stack trace and exit.");
            cnfe.printStackTrace();
            System.exit(1);
        }
        
        System.out.println("Ok, if we get here, we registered the driver ok, so let's make a connection.");
        
        Connection c = null;
        
        try {
            // The second and third arguments are the username and password, respectively. They should be whatever
            // is necessary to connect to the database.
            c = DriverManager.getConnection("jdbc:postgresql://example/bookstore", "username", "password");
        } catch (SQLException se) {
            System.out.println("We couldn't connect: print out a stack trace and exit.");
            se.printStackTrace();
            System.exit(1);
        }
        
        if (c != null)
            System.out.println("Hooray! We connected to the database!");
        else
            System.out.println("We should never get to this state, but it's good to check anyway.");
    }
}

At this point we should be able to use this Connection object to do anything we want with the PostgreSQL database.