Package org.postgresql

Interface PGConnection

All Known Subinterfaces:

BaseConnection

All Known Implementing Classes:

PgConnection

public interface PGConnection

This interface defines the public PostgreSQL extensions to java.sql.Connection. All Connections returned by the PostgreSQL driver implement PGConnection.

Method Summary

Modifier and Type	Method	Description
void	addDataType(String type, Class<? extends PGobject> klass)	This allows client code to add a handler for one of org.postgresql's more unique data types.
void	addDataType(String type, String className)	Deprecated. As of 8.0, replaced by addDataType(String, Class).
void	cancelQuery()	Sends a query cancellation for this connection.
Array	createArrayOf(String typeName, @Nullable Object elements)	Creates an Array wrapping elements.
String	escapeIdentifier(String identifier)	Return the given string suitably quoted to be used as an identifier in an SQL statement string.
String	escapeLiteral(String literal)	Return the given string suitably quoted to be used as a string literal in an SQL statement string.
boolean	getAdaptiveFetch()	Get state of adaptive fetch for connection.
AutoSave	getAutosave()	Connection configuration regarding automatic per-query savepoints.
int	getBackendPID()	Return the process ID (PID) of the backend server process handling this connection.
CopyManager	getCopyAPI()	This returns the COPY API for the current connection.
int	getDefaultFetchSize()	Get the default fetch size for statements created from this connection.
Fastpath	getFastpathAPI()	Deprecated. This API is somewhat obsolete, as one may achieve similar performance and greater functionality by setting up a prepared statement to define the function call.
LargeObjectManager	getLargeObjectAPI()	This returns the LargeObject API for the current connection.
PGNotification[]	getNotifications()	This method returns any notifications that have been received since the last call to this method.
PGNotification[]	getNotifications(int timeoutMillis)	This method returns any notifications that have been received since the last call to this method.
@Nullable String	getParameterStatus(String parameterName)	Shorthand for getParameterStatuses().get(...) .
Map<String,String>	getParameterStatuses()	Returns the current values of all parameters reported by the server.
PreferQueryMode	getPreferQueryMode()	Returns the query mode for this connection.
int	getPrepareThreshold()	Get the default server-side prepare reuse threshold for statements created from this connection.
PGReplicationConnection	getReplicationAPI()
void	setAdaptiveFetch(boolean adaptiveFetch)	Turn on/off adaptive fetch for connection.
void	setAutosave(AutoSave autoSave)	Configures if connection should use automatic savepoints.
void	setDefaultFetchSize(int fetchSize)	Set the default fetch size for statements created from this connection.
void	setPrepareThreshold(int threshold)	Set the default statement reuse threshold before enabling server-side prepare.

Method Details

createArrayOf

Array createArrayOf(String typeName,
 @Nullable Object elements)
             throws SQLException

Creates an Array wrapping elements. This is similar to Connection.createArrayOf(String, Object[]), but also provides support for primitive arrays.

Parameters:

typeName - The SQL name of the type to map the elements to. Must not be null.

elements - The array of objects to map. A null value will result in an Array representing null.

Returns:

An Array wrapping elements.

Throws:

SQLException - If for some reason the array cannot be created.

See Also:

• Connection.createArrayOf(String, Object[])

getNotifications

PGNotification[] getNotifications()
                           throws SQLException

This method returns any notifications that have been received since the last call to this method. Returns null if there have been no notifications.

Returns:

notifications that have been received

Throws:

SQLException - if something wrong happens

Since:

7.3

getNotifications

PGNotification[] getNotifications(int timeoutMillis)
                           throws SQLException

This method returns any notifications that have been received since the last call to this method. Returns null if there have been no notifications. A timeout can be specified so the driver waits for notifications.

Parameters:

timeoutMillis - when 0, blocks forever. when > 0, blocks up to the specified number of millis or until at least one notification has been received. If more than one notification is about to be received, these will be returned in one batch.

Returns:

notifications that have been received

Throws:

SQLException - if something wrong happens

Since:

43

getCopyAPI

CopyManager getCopyAPI()
                throws SQLException

This returns the COPY API for the current connection.

Returns:

COPY API for the current connection

Throws:

SQLException - if something wrong happens

Since:

8.4

getLargeObjectAPI

LargeObjectManager getLargeObjectAPI()
                              throws SQLException

This returns the LargeObject API for the current connection.

Returns:

LargeObject API for the current connection

Throws:

SQLException - if something wrong happens

Since:

7.3

getFastpathAPI

@Deprecated
Fastpath getFastpathAPI()
                 throws SQLException

Deprecated.

This API is somewhat obsolete, as one may achieve similar performance and greater functionality by setting up a prepared statement to define the function call. Then, executing the statement with binary transmission of parameters and results substitutes for a fast-path function call.

This returns the Fastpath API for the current connection.

Returns:

Fastpath API for the current connection

Throws:

SQLException - if something wrong happens

Since:

7.3

addDataType

@Deprecated
void addDataType(String type,
 String className)

Deprecated.

As of 8.0, replaced by addDataType(String, Class). This deprecated method does not work correctly for registering classes that cannot be directly loaded by the JDBC driver's classloader.

This allows client code to add a handler for one of org.postgresql's more unique data types. It is approximately equivalent to addDataType(type, Class.forName(name)).

Parameters:

type - JDBC type name

className - class name

Throws:

RuntimeException - if the type cannot be registered (class not found, etc).

addDataType

void addDataType(String type,
 Class<? extends PGobject> klass)
          throws SQLException

This allows client code to add a handler for one of org.postgresql's more unique data types.

NOTE: This is not part of JDBC, but an extension.

The best way to use this is as follows:

 ...
 ((org.postgresql.PGConnection)myconn).addDataType("mytype", my.class.name.class);
 ...
 

where myconn is an open Connection to org.postgresql.

The handling class must extend org.postgresql.util.PGobject

Parameters:

type - the PostgreSQL type to register

klass - the class implementing the Java representation of the type; this class must implement PGobject).

Throws:

SQLException - if klass does not implement PGobject).

Since:

8.0

See Also:

• PGobject

setPrepareThreshold

void setPrepareThreshold(int threshold)

Set the default statement reuse threshold before enabling server-side prepare. See PGStatement.setPrepareThreshold(int) for details.

Parameters:

threshold - the new threshold

Since:

build 302

getPrepareThreshold

int getPrepareThreshold()

Get the default server-side prepare reuse threshold for statements created from this connection.

Returns:

the current threshold

Since:

build 302

setDefaultFetchSize

void setDefaultFetchSize(int fetchSize)
                  throws SQLException

Set the default fetch size for statements created from this connection.

Parameters:

fetchSize - new default fetch size

Throws:

SQLException - if specified negative fetchSize parameter

See Also:

• Statement.setFetchSize(int)

getDefaultFetchSize

int getDefaultFetchSize()

Get the default fetch size for statements created from this connection.

Returns:

current state for default fetch size

See Also:

• PGProperty.DEFAULT_ROW_FETCH_SIZE
• Statement.getFetchSize()

getBackendPID

int getBackendPID()

Return the process ID (PID) of the backend server process handling this connection.

Returns:

PID of backend server process.

cancelQuery

void cancelQuery()
          throws SQLException

Sends a query cancellation for this connection.

Throws:

SQLException - if there are problems cancelling the query

escapeIdentifier

String escapeIdentifier(String identifier)
                 throws SQLException

Return the given string suitably quoted to be used as an identifier in an SQL statement string. Quotes are added only if necessary (i.e., if the string contains non-identifier characters or would be case-folded). Embedded quotes are properly doubled.

Parameters:

identifier - input identifier

Returns:

the escaped identifier

Throws:

SQLException - if something goes wrong

escapeLiteral

String escapeLiteral(String literal)
              throws SQLException

Return the given string suitably quoted to be used as a string literal in an SQL statement string. Embedded single-quotes and backslashes are properly doubled. Note that quote_literal returns null on null input.

Parameters:

literal - input literal

Returns:

the quoted literal

Throws:

SQLException - if something goes wrong

getPreferQueryMode

PreferQueryMode getPreferQueryMode()

Returns the query mode for this connection.

When running in simple query mode, certain features are not available: callable statements, partial result set fetch, bytea type, etc.

The list of supported features is subject to change.

Returns:

the preferred query mode

See Also:

• PreferQueryMode

getAutosave

AutoSave getAutosave()

Connection configuration regarding automatic per-query savepoints.

Returns:

connection configuration regarding automatic per-query savepoints

See Also:

• PGProperty.AUTOSAVE

setAutosave

void setAutosave(AutoSave autoSave)

Configures if connection should use automatic savepoints.

Parameters:

autoSave - connection configuration regarding automatic per-query savepoints

See Also:

• PGProperty.AUTOSAVE

getReplicationAPI

PGReplicationConnection getReplicationAPI()

Returns:

replication API for the current connection

getParameterStatuses

Map<String,String> getParameterStatuses()

Returns the current values of all parameters reported by the server.

PostgreSQL reports values for a subset of parameters (GUCs) to the client at connect-time, then sends update messages whenever the values change during a session. PgJDBC records the latest values and exposes it to client applications via getParameterStatuses().

PgJDBC exposes individual accessors for some of these parameters as listed below. They are more backwards-compatible and should be preferred where possible.

Not all parameters are reported, only those marked GUC_REPORT in the source code. The pg_settings view does not expose information about which parameters are reportable. PgJDBC's map will only contain the parameters the server reports values for, so you cannot use this method as a substitute for running a SHOW paramname; or SELECT current_setting('paramname'); query for arbitrary parameters.

Parameter names are case-insensitive and case-preserving in this map, like in PostgreSQL itself. So DateStyle and datestyle are the same key.

As of PostgreSQL 11 the reportable parameter list, and related PgJDBC interfaces or assessors, are:

• application_name - Connection.getClientInfo(), Connection.setClientInfo(java.util.Properties) and ApplicationName connection property.
• client_encoding - PgJDBC always sets this to UTF8. See allowEncodingChanges connection property.
• DateStyle - PgJDBC requires this to always be set to ISO
• standard_conforming_strings - indirectly via escapeLiteral(String)
• TimeZone - set from JDK timezone see TimeZone.getDefault() and TimeZone.setDefault(TimeZone)
• integer_datetimes
• IntervalStyle
• server_encoding
• server_version
• is_superuser
• session_authorization

Note that some PgJDBC operations will change server parameters automatically.

Returns:

unmodifiable map of case-insensitive parameter names to parameter values

Since:

42.2.6

getParameterStatus

@Nullable String getParameterStatus(String parameterName)

Shorthand for getParameterStatuses().get(...) .

Parameters:

parameterName - case-insensitive parameter name

Returns:

parameter value if defined, or null if no parameter known

Since:

42.2.6

See Also:

• getParameterStatuses()

setAdaptiveFetch

void setAdaptiveFetch(boolean adaptiveFetch)

Turn on/off adaptive fetch for connection. Existing statements and resultSets won't be affected by change here.

Parameters:

adaptiveFetch - desired state of adaptive fetch.

getAdaptiveFetch

boolean getAdaptiveFetch()

Get state of adaptive fetch for connection.

Returns:

state of adaptive fetch (turned on or off)