Documentation on pgJDBC

Setting up the JDBC Driver

Sun, 19 Jun 2022 22:46:55 +0530

This section describes the steps you need to take before you can write or run programs that use the JDBC interface.

Getting the Driver

Precompiled versions of the driver can be downloaded from the PostgreSQL® JDBC web site.

Initializing the Driver

Sun, 19 Jun 2022 22:46:55 +0530

This section describes how to load and initialize the JDBC driver in your programs.

Importing JDBC

Any source file that uses JDBC needs to import the java.sql package, using:

Using SSL

Sun, 19 Jun 2022 22:46:55 +0530

Configuring the PostgreSQL® server for SSL is covered in the main documentation, so it will not be repeated here. There are also instructions in the source certdir Before trying to access your SSL enabled server from Java, make sure you can get to it via psql. You should see output like the following if you have established a SSL connection.

$ ./bin/psql -h localhost -U postgres
psql (14.5)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
Type "help" for help.

postgres=#

Custom SSLSocketFactory

PostgreSQL® provides a way for developers to customize how an SSL connection is established. This may be used to provide a custom certificate source or other extensions by allowing the developer to create their own SSLContext instance. The connection URL parameters sslfactory allow the user to specify which custom class to use for creating the SSLSocketFactory . The class name specified by sslfactory must extend javax.net.ssl.SSLSocketFactory and be available to the driver’s classloader.

Issuing a Query and Processing the Result

Sun, 19 Jun 2022 22:46:55 +0530

Any time you want to issue SQL statements to the database, you require a Statement or PreparedStatement instance. Once you have a Statement or PreparedStatement , you can use issue a query. This will return a ResultSet instance, which contains the entire result (see the section called Getting results based on a cursor here for how to alter this behaviour). Example 5.1, “Processing a Simple Query in JDBC” illustrates this process.

Example 5.1. Processing a Simple Query in JDBC

This example will issue a simple query and print out the first column of each row using a Statement .

Calling Stored Functions and Procedures

Sun, 19 Jun 2022 22:46:55 +0530

PostgreSQL® supports two types of stored objects, functions that can return a result value and - starting from v11 - procedures that can perform transaction control. Both types of stored objects are invoked using CallableStatement and the standard JDBC escape call syntax {call storedobject(?)} . The escapeSyntaxCallMode connection property controls how the driver transforms the call syntax to invoke functions or procedures.

The default mode, select , supports backwards compatibility for existing applications and supports function invocation only. This is required to invoke a function returning void.

Storing Binary Data

Sun, 19 Jun 2022 22:46:55 +0530

PostgreSQL® provides two distinct ways to store binary data. Binary data can be stored in a table using the data type BYTEA or by using the Large Object feature which stores the binary data in a separate table in a special format and refers to that table by storing a value of type OID in your table.

In order to determine which method is appropriate you need to understand the limitations of each method. The BYTEA data type is not well suited for storing very large amounts of binary data. While a column of type BYTEA can hold up to 1 GB of binary data, it would require a huge amount of memory to process such a large value. The Large Object method for storing binary data is better suited to storing very large values, but it has its own limitations. Specifically deleting a row that contains a Large Object reference does not delete the Large Object. Deleting the Large Object is a separate operation that needs to be performed. Large Objects also have some security issues since anyone connected to the database can view and/or modify any Large Object, even if they don’t have permissions to view/update the row containing the Large Object reference.

JDBC escapes

Sun, 19 Jun 2022 22:46:55 +0530

The JDBC specification (like the ODBC specification) acknowledges the fact that some vendor specific SQL may be required for certain RDBMS features. To aid developers in writing portable JDBC applications across multiple database products, a special escape syntax is used to specify the generic commands the developer wants to be run. The JDBC driver translates these escape sequences into native syntax for its specific database. For more information consult the Java DB Technical Documentation.

PostgreSQL® Extensions to the JDBC API

Sun, 19 Jun 2022 22:46:55 +0530

PostgreSQL® is an extensible database system. You can add your own functions to the server, which can then be called from queries, or even add your own data types. As these are facilities unique to PostgreSQL®, we support them from Java, with a set of extension APIs. Some features within the core of the standard driver actually use these extensions to implement Large Objects, etc.

Accessing the Extensions

To access some of the extensions, you need to use some extra methods in the org.postgresql.PGConnection class. In this case, you would need to cast the return value of Driver.getConnection() . For example:

Using the Driver in a Multithreaded or a Servlet Environment

Sun, 19 Jun 2022 22:46:55 +0530

The PostgreSQL® JDBC driver is not thread safe. The PostgreSQL server is not threaded. Each connection creates a new process on the server as such any concurrent requests to the process would have to be serialized. The driver makes no guarantees that methods on connections are synchronized. It will be up to the caller to synchronize calls to the driver.

A notable exception is org/postgresql/jdbc/TimestampUtils.java which is threadsafe.

Connection Pools and Data Sources

Sun, 19 Jun 2022 22:46:55 +0530

JDBC 2 introduced standard connection pooling features in an add-on API known as the JDBC 2.0 Optional Package (also known as the JDBC 2.0 Standard Extension). These features have since been included in the core JDBC 3 API.

The JDBC API provides a client and a server interface for connection pooling. The client interface is javax.sql.DataSource, which is what application code will typically use to acquire a pooled database connection. The server interface is javax.sql.ConnectionPoolDataSource , which is how most application servers will interface with the PostgreSQL® JDBC driver.

Logging using java.util.logging

Sun, 19 Jun 2022 22:46:55 +0530

The PostgreSQL® JDBC Driver supports the use of logging (or tracing) to help resolve issues with the pgJDBC Driver when is used in your application.

The pgJDBC Driver uses the logging APIs of java.util.logging that is part of Java since JDK 1.4, which makes it a good choice for the driver since it doesn’t add any external dependency for a logging framework. java.util.logging is a very rich and powerful tool, it’s beyond the scope of these docs to explain how to use it to it’s full potential, for that please refer to Java Logging Overview.

Documentation on pgJDBC

Setting up the JDBC Driver

Getting the Driver

Initializing the Driver

Importing JDBC

Using SSL

Custom SSLSocketFactory

Issuing a Query and Processing the Result

Example 5.1. Processing a Simple Query in JDBC

Calling Stored Functions and Procedures

Storing Binary Data

JDBC escapes

PostgreSQL® Extensions to the JDBC API

Accessing the Extensions

Using the Driver in a Multithreaded or a Servlet Environment

Connection Pools and Data Sources

Logging using java.util.logging

Further Reading