The PostgreSQL™ server allows clients
to compile sql statements that are expected to be reused to avoid the
overhead of parsing and planning the statement for every execution.
This functionality is available at the SQL level
via PREPARE and EXECUTE beginning with server version 7.3, and at the
protocol level beginning with server version 7.4, but as Java
developers we really just want to use the standard
PreparedStatement interface.
Previous versions of the driver used PREPARE and EXECUTE to implement server-prepared statements. This is supported on all server versions beginning with 7.3, but produced application-visible changes in query results, such as missing ResultSet metadata and row update counts. The current driver uses the V3 protocol-level equivalents which avoid these changes in query results, but the V3 protocol is only available beginning with server version 7.4. Enabling server-prepared statements will have no affect when connected to a 7.3 server or when explicitly using the V2 protocol to connect to a 7.4 server.
There are a number of ways to enable server side prepared statements
depending on your application's needs. The general method is to
set a threshold for a PreparedStatement.
An internal counter keeps track of how many times the statement has
been executed and when it reaches the threshold it will start to
use server side prepared statements.
Server side prepared statements are planned only once by the server. This avoids the cost of replanning the query every time, but also means that the planner cannot take advantage of the particular parameter values used in a particular execution of the query. You should be cautious about enabling the use of server side prepared statements globally.
Example 9.3. Using server side prepared statements
import java.sql.*;
public class ServerSidePreparedStatement
{
public static void main(String args[]) throws Exception
{
Class.forName("org.postgresql.Driver");
String url = "jdbc:postgresql://localhost:5432/test";
Connection conn = DriverManager.getConnection(url,"test","");
PreparedStatement pstmt = conn.prepareStatement("SELECT ?");
// cast to the pg extension interface
org.postgresql.PGStatement pgstmt = (org.postgresql.PGStatement)pstmt;
// on the third execution start using server side statements
pgstmt.setPrepareThreshold(3);
for (int i=1; i<=5; i++)
{
pstmt.setInt(1,i);
boolean usingServerPrepare = pgstmt.isUseServerPrepare();
ResultSet rs = pstmt.executeQuery();
rs.next();
System.out.println("Execution: "+i+", Used server side: " + usingServerPrepare + ", Result: "+rs.getInt(1));
rs.close();
}
pstmt.close();
conn.close();
}
}
Which produces the expected result of using server side prepared statements upon the third execution.
Execution: 1, Used server side: false, Result: 1 Execution: 2, Used server side: false, Result: 2 Execution: 3, Used server side: true, Result: 3 Execution: 4, Used server side: true, Result: 4 Execution: 5, Used server side: true, Result: 5
The example shown above requires the programmer to use
PostgreSQL™ specific code in a
supposedly portable API which is not ideal. Also it sets the
threshold only for that particular statement which is some extra
typing if we wanted to use that threshold for every statement.
Let's take a look at the other ways to set the threshold to enable
server side prepared statements. There is already a hierarchy in
place above a PreparedStatement, the
Connection it was created from, and above that
the source of the connection be it a Datasource
or a URL. The server side prepared statement
threshold can be set at any of these levels such that the value
will be the default for all of it's children.
// pg extension interfaces
org.postgresql.PGConnection pgconn;
org.postgresql.PGStatement pgstmt;
// set a prepared statement threshold for connections created from this url
String url = "jdbc:postgresql://localhost:5432/test?prepareThreshold=3";
// see that the connection has picked up the correct threshold from the url
Connection conn = DriverManager.getConnection(url,"test","");
pgconn = (org.postgresql.PGConnection)conn;
System.out.println(pgconn.getPrepareThreshold()); // Should be 3
// see that the statement has picked up the correct threshold from the connection
PreparedStatement pstmt = conn.prepareStatement("SELECT ?");
pgstmt = (org.postgresql.PGStatement)pstmt;
System.out.println(pgstmt.getPrepareThreshold()); // Should be 3
// change the connection's threshold and ensure that new statements pick it up
pgconn.setPrepareThreshold(5);
PreparedStatement pstmt = conn.prepareStatement("SELECT ?");
pgstmt = (org.postgresql.PGStatement)pstmt;
System.out.println(pgstmt.getPrepareThreshold()); // Should be 5