com.amazon.redshift

## Interface RedshiftConnection

All Known Subinterfaces:
  BaseConnection

All Known Implementing Classes:
  RedshiftConnectionImpl

    public interface RedshiftConnection

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

### Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
`void` `addDataType(String type, Class<? extends RedshiftObject> klass)` This allows client code to add a handler for one of com.amazon.redshift's more unique data types.
`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.
`void` `cancelQuery()` Sends a query cancellation for this connection.
`Array` `createArrayOf(String typeName, 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.
`AutoSave` `getAutosave()` Connection configuration regarding automatic per-query savepoints.
`int` `getBackendPID()` Return the process ID (PID) of the backend server process handling this connection.
`Long` `getBytesReadFromStream()`
`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. Then, executing the statement with binary transmission of parameters and results substitutes for a fast-path function call.
`LargeObjectManager` `getLargeObjectAPI()` This returns the LargeObject API for the current connection.
`RedshiftNotification[]` `getNotifications()` This method returns any notifications that have been received since the last call to this method.
`RedshiftNotification[]` `getNotifications(int timeoutMillis)` This method returns any notifications that have been received since the last call to this method.
`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.
`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 Detail

#### createArrayOf

    Array createArrayOf(String typeName,
                        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

    RedshiftNotification[] 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

#### getBytesReadFromStream

    Long getBytesReadFromStream()

#### getNotifications

    RedshiftNotification[] 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 millies 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

#### 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 com.amazon.redshift'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 RedshiftObject> klass)
              throws SQLException

This allows client code to add a handler for one of com.amazon.redshift's more unique data types.

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

The best way to use this is as follows:

     ...
     ((com.amazon.redshift.RedshiftConnection)myconn).addDataType("mytype", my.class.name.class);
     ...

where myconn is an open Connection to com.amazon.redshift.

The handling class must extend com.amazon.redshift.util.RedshiftObject

Parameters:
  `type` - the Redshift type to register
  `klass` - the class implementing the Java representation of the type; this class must implement `RedshiftObject`).
Throws:
  `SQLException` - if `klass` does not implement `RedshiftObject`).
Since:
  8.0
See Also:
  `RedshiftObject`

#### setPrepareThreshold

    void setPrepareThreshold(int threshold)

Set the default statement reuse threshold before enabling server-side prepare. See `RedshiftStatement.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:
  `RedshiftProperty.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:
  `RedshiftProperty.AUTOSAVE`

#### setAutosave

    void setAutosave(AutoSave autoSave)

Configures if connection should use automatic savepoints.

Parameters:
  `autoSave` - connection configuration regarding automatic per-query savepoints
See Also:
  `RedshiftProperty.AUTOSAVE`

#### getParameterStatuses

    Map<String,String> getParameterStatuses()

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

Redshift 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 backwarrds-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 Redshift itself. So `DateStyle` and `datestyle` are the same key.

As of PostgreSQL 11 the reportable parameter list, and related PgJDBC interfaces or accesors, 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

    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()`