Installing PL/Java

The PL/Java extension is available as a package that you can download from the Pivotal Network and then install with the Package Manager utility (gppkg).

Note: For details on how to use PL/Java, see Using PL/Java.

Prerequisites

PL/Java is compatible with JDK 1.6 and 1.7.

Before you install PL/Java:

  1. Ensure that the $JAVA_HOME variable is set to the same path on the master and all the segments.
  2. Perform the following step on all machines to set up ldconfig for JDK:

    $ echo "$JAVA_HOME/jre/lib/amd64/server" > /etc/ld.so.conf.d/libjdk.conf
    $ ldconfig
    
  3. Make sure that your HAWQ cluster is running, you have sourced greenplum_path.sh and that your $GPHOME environment variable is set.

Install PL/Java

To install and use PL/Java:

  1. Install the PL/Java extension.
  2. Enable the language for each database.
  3. Install user-created JAR files containing Java methods on all HAWQ hosts.
  4. Add the name of the JAR file to the HAWQ pljava_classpath server configuration parameter in hawq-site.xml. This parameter value should contain a list of the installed JAR files.

Install the HAWQ PL/Java Extension

  1. Download the HDB Language Extensions tar.gz file from the Pivotal Network, and extract its contents.
  2. Copy the PL/Java extension package file to the HAWQ master host.
  3. On HAWQ master, install the software package by running the following command:

    $ gppkg -i pljava-x.x.x.x-x86_64.gppkg
    

    where x.x.x.x corresponds to the version of the package file that you are installing.

  4. Source the $GPHOME/greenplum_path.sh file.

  5. Restart the cluster:

    $ hawq restart cluster
    

Enable PL/Java and Install JAR Files

Perform the following steps as the gpadmin user:

  1. Enable PL/Java by running the $GPHOME/share/postgresql/pljava/install.sql SQL script in the databases that use PL/Java. For example, this example enables PL/Java on a database named testdb:

    $ psql -d testdb -f $GPHOME/share/postgresql/pljava/install.sql
    

    The install.sql script registers both the trusted and untrusted PL/Java.

  2. Copy your Java archives (JAR files) to $GPHOME/lib/postgresql/java/ on all the HAWQ hosts. This example uses the hawq scp utility to copy the myclasses.jar file:

    $ hawq scp -f hawq_hosts myclasses.jar =:$GPHOME/lib/postgresql/java/
    

    The hawq_hosts file contains a list of the HAWQ hosts.

  3. Set the pljava_classpath server configuration parameter in the hawq-site.xml configuration file. The parameter value is a colon (:) separated list of the JAR files containing the Java classes used in any PL/Java functions. For example:

    $ hawq config -c pljava_classpath -v \'examples.jar:myclasses.jar\' 
    
  4. Restart the HAWQ cluster:

    $ hawq restart cluster
    
  5. (Optional) Pivotal provides an examples.sql file containing sample PL/Java functions that you can use for testing. Run the commands in this file to create the test functions, which use the Java classes in examples.jar:

    $ psql -f $GPHOME/share/postgresql/pljava/examples.sql
    

Enabling PL/Java in the template1 Database

To enable the PL/Java extension in all new HAWQ databases, execute the following command:

$ psql template1 -f $GPHOME/share/postgresql/pljava/install.sql

Use this option only if you are certain you want to enable PL/Java in all new databases.

Configuring PL/Java VM Options

PL/Java JVM options can be configured via the pljava_vmoptions parameter in hawq-site.xml. For example, pljava_vmoptions=-Xmx512M sets the maximum heap size of the JVM. The default Xmx value is set to -Xmx64M.

Installing Custom JARS

  1. Copy the JAR file on the master host in $GPHOME/lib/postgresql/java.
  2. Copy the JAR file on all segments in the same location using hawq scp from master:

    $ cd $GPHOME/lib/postgresql/java
    $ hawq scp -f hawq_hosts myfunc.jar =:$GPHOME/lib/postgresql/java/
    
  3. Set pljava_classpath to include the newly-copied JAR file. From the psql session, execute set to affect the current session:

    psql> set pljava_classpath='myfunc.jar'; 
    
  4. To affect all sessions, use hawq config:

    $ hawq config -c pljava_classpath -v \'myfunc.jar\' 
    

Uninstall PL/Java

To uninstall PL/Java, you should:

  1. Remove PL/Java support from the database
  2. Uninstall the Java JAR files and software package

Remove PL/Java Support from the Database

For a database that no long requires the PL/Java language, remove support for PL/Java by running the uninstall.sql file as the gpadmin user. For example, the following command disables the PL/Java language in the specified database:

$ psql -d <dbname> -f $GPHOME/share/postgresql/pljava/uninstall.sql

Replace <dbname> with the name of the target database.

Uninstall the Java JAR files and Software Package

If no databases have PL/Java as a registered language, remove the Java JAR files and uninstall the PL/Java extension with the gppkg utility:

  1. Remove the pljava_classpath server configuration parameter in the hawq-site.xml file.
  2. Remove the JAR files from the $GPHOME/lib/postgresql/java/ directory of the HAWQ hosts.
  3. Use the gppkg utility with the -r option to uninstall the PL/Java extension. The following example uninstalls the PL/Java extension on a Linux system:

    $ gppkg -r pljava
    

    You can run the gppkg utility with the options -q --all to list all the currently installed extensions.

  4. After you uninstall the extension, restart the HAWQ cluster:

    $ hawq restart cluster