PostgreSQL JDBC Driver 42.7.2 · org.postgresql.PGConnection

Method Summary

Modifier and Type	Method and Description
public void	addDataType(String JDBC type name type, String class name className) Deprecated As of 8.0, replaced by `addDataType(String, Class)`. This allows client code to add a handler for one of org.postgresql's more unique data types.
public void	addDataType(String the PostgreSQL type to register type, Class<? extends PGobject> the class implementing the Java representation of the type; this class must implement `org.postgresql.util.PGobject`). klass) This allows client code to add a handler for one of org.postgresql's more unique data types.
public default void	alterUserPassword(String The username of the database user user, char[] The new password for the database user. The implementation will zero out the array after use newPassword, @Nullable String The type of password encryption to use or null if the database server default should be used. encryptionType) Change a user's password to the specified new password.
public void	cancelQuery() Sends a query cancellation for this connection.
public Array	Returns: An `Array` wrapping elements. createArrayOf(String The SQL name of the type to map the elements to. Must not be `null`. typeName, @Nullable Object The array of objects to map. A `null` value will result in an `Array` representing `null`. elements) Creates an `Array` wrapping elements.
public String	Returns: the escaped identifier escapeIdentifier(String input identifier identifier) Return the given string suitably quoted to be used as an identifier in an SQL statement string.
public String	Returns: the quoted literal escapeLiteral(String input literal literal) Return the given string suitably quoted to be used as a string literal in an SQL statement string.
public boolean	Returns: state of adaptive fetch (turned on or off) getAdaptiveFetch() Get state of adaptive fetch for connection.
public AutoSave	Returns: connection configuration regarding automatic per-query savepoints getAutosave() Connection configuration regarding automatic per-query savepoints.
public int	Returns: PID of backend server process. getBackendPID() Return the process ID (PID) of the backend server process handling this connection.
public CopyManager	Returns: COPY API for the current connection getCopyAPI() This returns the COPY API for the current connection.
public int	Returns: current state for default fetch size getDefaultFetchSize() Get the default fetch size for statements created from this connection.
public Fastpath	Returns: Fastpath API for the current connection 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. This returns the Fastpath API for the current connection.
public LargeObjectManager	Returns: LargeObject API for the current connection getLargeObjectAPI() This returns the LargeObject API for the current connection.
public PGNotification[]	Returns: notifications that have been received getNotifications() This method returns any notifications that have been received since the last call to this method.
public PGNotification[]	Returns: notifications that have been received getNotifications(int 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. timeoutMillis) This method returns any notifications that have been received since the last call to this method.
public @Nullable String	Returns: parameter value if defined, or null if no parameter known getParameterStatus(String case-insensitive parameter name parameterName) Shorthand for getParameterStatuses().get(...) .
public Map<String, String>	Returns: unmodifiable map of case-insensitive parameter names to parameter values getParameterStatuses() Returns the current values of all parameters reported by the server.
public PreferQueryMode	Returns: the preferred query mode getPreferQueryMode() Returns the query mode for this connection.
public int	Returns: the current threshold getPrepareThreshold() Get the default server-side prepare reuse threshold for statements created from this connection.
public PGReplicationConnection	Returns: replication API for the current connection getReplicationAPI()
public void	setAdaptiveFetch(boolean desired state of adaptive fetch. adaptiveFetch) Turn on/off adaptive fetch for connection.
public void	setAutosave(AutoSave connection configuration regarding automatic per-query savepoints autoSave) Configures if connection should use automatic savepoints.
public void	setDefaultFetchSize(int new default fetch size fetchSize) Set the default fetch size for statements created from this connection.
public void	setPrepareThreshold(int the new threshold threshold) Set the default statement reuse threshold before enabling server-side prepare.

Method Detail

addDataType back to summary

addDataType	back to summary
public 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:String JDBC type name className:String class name Annotations @Deprecated Exceptions RuntimeException: if the type cannot be registered (class not found, etc).

public 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:String: JDBC type name
className:String: class name

Annotations

@Deprecated

Exceptions

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

addDataType back to summary

addDataType	back to summary
public 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:String the PostgreSQL type to register klass:Class<? extends PGobject> the class implementing the Java representation of the type; this class must implement `org.postgresql.util.PGobject`). Exceptions SQLException: if `klass` does not implement `org.postgresql.util.PGobject`). Since 8.0 See Also `org.postgresql.util.PGobject`

public 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:String: the PostgreSQL type to register
klass:Class<? extends PGobject>: the class implementing the Java representation of the type; this class must implement org.postgresql.util.PGobject).

Exceptions

SQLException:: if klass does not implement org.postgresql.util.PGobject).

Since

8.0

See Also

org.postgresql.util.PGobject

alterUserPassword	back to summary
public default void alterUserPassword(String user, char[] newPassword, @Nullable String encryptionType) throws SQLException Change a user's password to the specified new password. If the specific encryption type is not specified, this method defaults to querying the database server for the server's default password_encryption. This method does not send the new password in plain text to the server. Instead, it encrypts the password locally and sends the encoded hash so that the plain text password is never sent on the wire. Acceptable values for encryptionType are null, "md5", or "scram-sha-256". Users should avoid "md5" unless they are explicitly targeting an older server that does not support the more secure SCRAM. Parameters user:String The username of the database user newPassword:char[] The new password for the database user. The implementation will zero out the array after use encryptionType:@Nullable String The type of password encryption to use or null if the database server default should be used. Exceptions SQLException: If the password could not be altered

alterUserPassword

back to summary

public default void alterUserPassword(String user, char[] newPassword, @Nullable String encryptionType) throws SQLException

Change a user's password to the specified new password.

If the specific encryption type is not specified, this method defaults to querying the database server for the server's default password_encryption. This method does not send the new password in plain text to the server. Instead, it encrypts the password locally and sends the encoded hash so that the plain text password is never sent on the wire.

Acceptable values for encryptionType are null, "md5", or "scram-sha-256". Users should avoid "md5" unless they are explicitly targeting an older server that does not support the more secure SCRAM.

Parameters

user:String: The username of the database user
newPassword:char[]: The new password for the database user. The implementation will zero out the array after use
encryptionType:@Nullable String: The type of password encryption to use or null if the database server default should be used.

Exceptions

SQLException:: If the password could not be altered

cancelQuery	back to summary
public void cancelQuery() throws SQLException Sends a query cancellation for this connection. Exceptions SQLException: if there are problems cancelling the query

cancelQuery

back to summary

public void cancelQuery() throws SQLException

Sends a query cancellation for this connection.

Exceptions

SQLException:: if there are problems cancelling the query

createArrayOf back to summary

createArrayOf	back to summary
public Array createArrayOf(String typeName, @Nullable Object elements) throws SQLException Creates an `Array` wrapping elements. This is similar to `java.sql.Connection#createArrayOf(String, Object[])`, but also provides support for primitive arrays. Parameters typeName:String The SQL name of the type to map the elements to. Must not be `null`. elements:@Nullable Object The array of objects to map. A `null` value will result in an `Array` representing `null`. Returns:Array An `Array` wrapping elements. Exceptions SQLException: If for some reason the array cannot be created. See Also `java.sql.Connection#createArrayOf(String, Object[])`

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

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

Parameters

typeName:String: The SQL name of the type to map the elements to. Must not be null.
elements:@Nullable Object: The array of objects to map. A null value will result in an Array representing null.

Returns:Array

An Array wrapping elements.

Exceptions

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

escapeIdentifier	back to summary
public 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:String input identifier Returns:String the escaped identifier Exceptions SQLException: if something goes wrong

escapeIdentifier

back to summary

public 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:String: input identifier

Returns:String

the escaped identifier

Exceptions

SQLException:: if something goes wrong

escapeLiteral	back to summary
public 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:String input literal Returns:String the quoted literal Exceptions SQLException: if something goes wrong

escapeLiteral

back to summary

public 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:String: input literal

Returns:String

the quoted literal

Exceptions

SQLException:: if something goes wrong

getAdaptiveFetch	back to summary
public boolean getAdaptiveFetch() Get state of adaptive fetch for connection. Returns:boolean state of adaptive fetch (turned on or off)

getAdaptiveFetch

back to summary

public boolean getAdaptiveFetch()

Get state of adaptive fetch for connection.

Returns:boolean: state of adaptive fetch (turned on or off)

getAutosave back to summary

getAutosave	back to summary
public AutoSave getAutosave() Connection configuration regarding automatic per-query savepoints. Returns:AutoSave connection configuration regarding automatic per-query savepoints See Also `PGProperty#AUTOSAVE`

public AutoSave getAutosave()

Connection configuration regarding automatic per-query savepoints.

Returns:AutoSave: connection configuration regarding automatic per-query savepoints
See Also: PGProperty#AUTOSAVE

getBackendPID	back to summary
public int getBackendPID() Return the process ID (PID) of the backend server process handling this connection. Returns:int PID of backend server process.

getBackendPID

back to summary

public int getBackendPID()

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

Returns:int: PID of backend server process.

getCopyAPI	back to summary
public CopyManager getCopyAPI() throws SQLException This returns the COPY API for the current connection. Returns:CopyManager COPY API for the current connection Exceptions SQLException: if something wrong happens Since 8.4

getCopyAPI

back to summary

public CopyManager getCopyAPI() throws SQLException

This returns the COPY API for the current connection.

Returns:CopyManager

COPY API for the current connection

Exceptions

SQLException:: if something wrong happens

Since

8.4

getDefaultFetchSize back to summary

getDefaultFetchSize	back to summary
public int getDefaultFetchSize() Get the default fetch size for statements created from this connection. Returns:int current state for default fetch size See Also `PGProperty#DEFAULT_ROW_FETCH_SIZE`, `Statement#getFetchSize()`

public int getDefaultFetchSize()

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

Returns:int: current state for default fetch size
See Also: PGProperty#DEFAULT_ROW_FETCH_SIZE, Statement#getFetchSize()

getFastpathAPI	back to summary
public 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 Fastpath API for the current connection Annotations @Deprecated Exceptions SQLException: if something wrong happens Since 7.3

getFastpathAPI

back to summary

public 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

Fastpath API for the current connection

Annotations

@Deprecated

Exceptions

SQLException:: if something wrong happens

Since

7.3

getLargeObjectAPI	back to summary
public LargeObjectManager getLargeObjectAPI() throws SQLException This returns the LargeObject API for the current connection. Returns:LargeObjectManager LargeObject API for the current connection Exceptions SQLException: if something wrong happens Since 7.3

getLargeObjectAPI

back to summary

public LargeObjectManager getLargeObjectAPI() throws SQLException

This returns the LargeObject API for the current connection.

Returns:LargeObjectManager

LargeObject API for the current connection

Exceptions

SQLException:: if something wrong happens

Since

7.3

getNotifications	back to summary
public 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:PGNotification[] notifications that have been received Exceptions SQLException: if something wrong happens Since 7.3

getNotifications

back to summary

public 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:PGNotification[]

notifications that have been received

Exceptions

SQLException:: if something wrong happens

Since

7.3

getNotifications	back to summary
public 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:int 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:PGNotification[] notifications that have been received Exceptions SQLException: if something wrong happens Since 43

getNotifications

back to summary

public 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:int: 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:PGNotification[]

notifications that have been received

Exceptions

SQLException:: if something wrong happens

Since

getParameterStatus back to summary

getParameterStatus	back to summary
public @Nullable String getParameterStatus(String parameterName) Shorthand for getParameterStatuses().get(...) . Parameters parameterName:String case-insensitive parameter name Returns:@Nullable String parameter value if defined, or null if no parameter known Since 42.2.6 See Also `getParameterStatuses`

public @Nullable String getParameterStatus(String parameterName)

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

Parameters

parameterName:String: case-insensitive parameter name

Returns:@Nullable String

parameter value if defined, or null if no parameter known

Since

42.2.6

See Also

getParameterStatuses

getParameterStatuses back to summary

getParameterStatuses	back to summary
public 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` - `java.sql.Connection#getClientInfo()`, `java.sql.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 `java.util.TimeZone#getDefault()` and `java.util.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:Map<String, String> unmodifiable map of case-insensitive parameter names to parameter values Since 42.2.6

public 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 - java.sql.Connection#getClientInfo(), java.sql.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 java.util.TimeZone#getDefault() and java.util.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:Map<String, String>: unmodifiable map of case-insensitive parameter names to parameter values
Since: 42.2.6

getPreferQueryMode back to summary

getPreferQueryMode	back to summary
public 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:PreferQueryMode the preferred query mode See Also `PreferQueryMode`

public 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:PreferQueryMode: the preferred query mode
See Also: PreferQueryMode

getPrepareThreshold	back to summary
public int getPrepareThreshold() Get the default server-side prepare reuse threshold for statements created from this connection. Returns:int the current threshold Since build 302

getPrepareThreshold

back to summary

public int getPrepareThreshold()

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

Returns:int: the current threshold
Since: build 302

getReplicationAPI	back to summary
public PGReplicationConnection getReplicationAPI() Returns:PGReplicationConnection replication API for the current connection

setAdaptiveFetch	back to summary
public void setAdaptiveFetch(boolean adaptiveFetch) Turn on/off adaptive fetch for connection. Existing statements and resultSets won't be affected by change here. Parameters adaptiveFetch:boolean desired state of adaptive fetch.

setAdaptiveFetch

back to summary

public void setAdaptiveFetch(boolean adaptiveFetch)

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

Parameters

adaptiveFetch:boolean: desired state of adaptive fetch.

setAutosave back to summary

setAutosave	back to summary
public void setAutosave(AutoSave autoSave) Configures if connection should use automatic savepoints. Parameters autoSave:AutoSave connection configuration regarding automatic per-query savepoints See Also `PGProperty#AUTOSAVE`

public void setAutosave(AutoSave autoSave)

Configures if connection should use automatic savepoints.

Parameters

autoSave:AutoSave: connection configuration regarding automatic per-query savepoints

See Also

PGProperty#AUTOSAVE

setDefaultFetchSize back to summary

setDefaultFetchSize	back to summary
public void setDefaultFetchSize(int fetchSize) throws SQLException Set the default fetch size for statements created from this connection. Parameters fetchSize:int new default fetch size Exceptions SQLException: if specified negative `fetchSize` parameter See Also `Statement#setFetchSize(int)`

public void setDefaultFetchSize(int fetchSize) throws SQLException

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

Parameters

fetchSize:int: new default fetch size

Exceptions

SQLException:: if specified negative fetchSize parameter

See Also

Statement#setFetchSize(int)

setPrepareThreshold back to summary

setPrepareThreshold	back to summary
public void setPrepareThreshold(int threshold) Set the default statement reuse threshold before enabling server-side prepare. See `org.postgresql.PGStatement#setPrepareThreshold(int)` for details. Parameters threshold:int the new threshold Since build 302

public void setPrepareThreshold(int threshold)

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

Parameters

threshold:int: the new threshold

Since

build 302

public Interface PGConnection

Method Summary

Method Detail