PL/Java, 1.0.0 beta.

With this release, the Pl/Java project has reached its second major milestone. It is now possible to write triggers and functions without any knowledge about the PostgreSQL backend internals. Instead of using Tuple, TupleDesc, and SPI functions, you use well known JDBC interfaces like Connection, PreparedStatement, and ResultSet. Jar files are stored in the database and can be loaded, changed, or removed using SQL standard procedure calls.

 

Two binary releases can be found in the download area. One for Windows (cygwin required until the Win32 native port of PostgreSQL is released), and one for Linux on Intel-platform. The reason for the limited set of binaries is that I have a limited set of machines. All code is plain C and Java and should be very portable.

How to get started

See to that you have a Java 1.4 and PostgreSQL 7.4 including its JDBC drivers installed on your machine. A JRE (runtime environment) will suffice if you use the binary distribution. You don’t need the JDK unless you plan to compile.

Postmaster configuration.

Get the PostgreSQL environment up and running. You will need to modify the postgresql.conf file so that:

a)      The postmaster accepts TCP/IP connections (needed for the JDBC driver). Simply uncomment the line that says:
# tcpip_socket = false
and then change the false to a true.

b)      Further down, you’ll find the entry for dynamic_library_path. Uncomment this entry too and change it so that the postmaster will find the shared library, i.e. the path must include the directory that contains the libpljava.so or pljava.dll (which one is depending on your OS).

c)      In order to see the logging from the tests, also change the log_min_messages to info.

 

The postgresql.conf have no entry to configure Java specific environment variables yet so you will need to make two external environment settings available to the postmaster process:

a)      The CLASSPATH must include the full path to pljava.jar.

b)      The LD_LIBRARY_PATH (Unix) or PATH (Windows) must be set so that the loader finds the shared libraries used by the JVM. A standard install on an Intel Linux box will need: LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/i386:$JAVA_HOME/jre/lib/i386/client.

 

With that in place, you are ready to start the postmaster.

 

Deploying the Pl/Java

Pl/Java adds a schema named SQLJ to the database (the naming is from the proposed SQL standard for Java backend mapping) and adds a couple of tables and functions to that schema. A deploy program exists that should be used for this purpose. In order to run this program, you must see to that the PostgreSQL jdbc driver package postgresql.jar and the deploy.jar file is in your CLASSPATH, then run:

 

java org.postgresql.pljava.deploy.Deployer

This will result in a list of options. Typically you would use something like:

 

java org.postgresql.pljava.deploy.Deployer –install –user <your name>

That’s all there’s to it. You are now ready to start using the Pl/Java system. If the server runs on a windows system you will need to add the option –windows. The reason for this is that PostgreSQL and Java dynamic loading uses different naming on Unix.

Run the example tests.

The tests are divided into two jar files. One is the client part, the org.postgresql.pljava.test.Tester class found in the test.jar. It contains some methods that executes SQL statements and prints the output (all contained there can of course also be executed from psql or any other client). The other is the example.jar which contains the sample code that runs in the backend. The latter must be installed in the database in order to function. An easy way to do this is to use psql and issue the command:

 

SELECT sqlj.install_jar(‘samples’, ‘file:///some/directory/example.jar’, true);

 

If this command succeeds, everything is working correctly. You may get a couple of errors here though.

-         A complaint that the class org.postgresql.pljava.internal.Oid cannot be found.
The probable cause of this is that the CLASSPATH seen by the postmaster is incorrect so that the pljava.jar is not found.

-         A complaint that the libpljava.so or pljava.dll cannot be found. Probable cause is that the Dynamic_library_path in the postgresql.conf file is incorrect.

 

Once loaded, you must also set the classpath used by the Pl/Java runtime. This classpath is set per schema (namespace). A schema that lacks a classpath will default to the classpath that has been set for the public schema. The tests will use the schema javatest. To define the classpath for this schema, simply use psql and issue the command:

 

SELECT sqlj.set_classpath(‘javatest’, ‘samples’);

 

The first argument is the name of the schema, the second is a colon separated list of jar names. The names must reflect jars that are installed in the system.

 

Now, you should be able to run the tests.