Package org.postgresql.core

# Interface BaseConnection

All Superinterfaces:
  `AutoCloseable`, `Connection`, `PGConnection`, `Wrapper`

All Known Implementing Classes:
  `PgConnection`

public interface BaseConnection extends PGConnection, Connection
Driver-internal connection interface. Application code should not use this interface.

- ## Field Summary

  ### Fields inherited from interface java.sql.Connection

  `TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addTimerTask(TimerTask timerTask, long milliSeconds)`
  Schedule a TimerTask for later execution.
  `boolean`
  `binaryTransferSend(int oid)`
  Returns true if value for the given oid should be sent using binary transfer.
  `void`
  `cancelQuery()`
  Cancel the current query executing on this connection.
  `CachedQuery`
  `createQuery(String sql, boolean escapeProcessing, boolean isParameterized, String... columnNames)`
  `byte @PolyNull []`
  `encodeString(@PolyNull String str)`
  Encode a string using the database's client_encoding (usually UTF8, but can vary on older server versions).
  `String`
  `escapeString(String str)`
  Escapes a string for use as string-literal within an SQL command.
  `ResultSet`
  `execSQLQuery(String s)`
  Execute a SQL query that returns a single resultset.
  `ResultSet`
  `execSQLQuery(String s, int resultSetType, int resultSetConcurrency)`
  `void`
  `execSQLUpdate(String s)`
  Execute a SQL query that does not return results.
  `boolean`
  `getConvertBooleanToNumeric()`
  Returns true if boolean values should be converted to numeric types (1/0).
  `Encoding`
  `getEncoding()`
  `LruCache<FieldMetadata.Key,FieldMetadata>`
  `getFieldMetadataCache()`
  Return metadata cache for given connection.
  `Logger`
  `getLogger()`
  `boolean`
  `getLogServerErrorDetail()`
  Indicates if error details from server used in included in logging and exceptions.
  `Object`
  `getObject(String type, @Nullable String value, byte @Nullable [] byteValue)`
  Construct and return an appropriate object for the given type and value.
  `QueryExecutor`
  `getQueryExecutor()`
  Get the QueryExecutor implementation for this connection.
  `ReplicationProtocol`
  `getReplicationProtocol()`
  Internal protocol for work with physical and logical replication.
  `boolean`
  `getStandardConformingStrings()`
  Returns whether the server treats string-literals according to the SQL standard or if it uses traditional PostgreSQL escaping rules.
  `boolean`
  `getStringVarcharFlag()`
  `TimestampUtils`
  `getTimestampUtils()`
  Deprecated.
  `TransactionState`
  `getTransactionState()`
  Get the current transaction state of this connection.
  `TypeInfo`
  `getTypeInfo()`
  `PGXmlFactoryFactory`
  `getXmlFactoryFactory()`
  Retrieve the factory to instantiate XML processing factories.
  `boolean`
  `haveMinimumServerVersion(int ver)`
  Check if we have at least a particular server version.
  `boolean`
  `haveMinimumServerVersion(Version ver)`
  Check if we have at least a particular server version.
  `boolean`
  `hintReadOnly()`
  Indicates if statements to backend should be hinted as read only.
  `boolean`
  `isColumnSanitiserDisabled()`
  Return whether to disable column name sanitation.
  `void`
  `purgeTimerTasks()`
  Invoke purge() on the underlying shared Timer so that internal resources will be released.
  `void`
  `setFlushCacheOnDeallocate(boolean flushCacheOnDeallocate)`
  By default, the connection resets statement cache in case deallocate all/discard all message is observed.

  ### Methods inherited from interface java.sql.Connection

  `abort, beginRequest, clearWarnings, close, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, endRequest, getAutoCommit, getCatalog, getClientInfo, getClientInfo, getHoldability, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, isValid, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setClientInfo, setClientInfo, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid, setTransactionIsolation, setTypeMap`

  ### Methods inherited from interface org.postgresql.PGConnection

  `addDataType, addDataType, alterUserPassword, createArrayOf, escapeIdentifier, escapeLiteral, getAdaptiveFetch, getAutosave, getBackendPID, getCopyAPI, getDefaultFetchSize, getFastpathAPI, getLargeObjectAPI, getNotifications, getNotifications, getParameterStatus, getParameterStatuses, getPreferQueryMode, getPrepareThreshold, getQueryTimeout, getReplicationAPI, setAdaptiveFetch, setAutosave, setDefaultFetchSize, setPrepareThreshold, setQueryTimeout`

  ### Methods inherited from interface java.sql.Wrapper

  `isWrapperFor, unwrap`

- ## Method Details

  - ### cancelQuery

    void cancelQuery() throws SQLException
    Cancel the current query executing on this connection.
    Specified by:
      `cancelQuery` in interface `PGConnection`
    Throws:
      `SQLException` - if something goes wrong.

  - ### execSQLQuery

    ResultSet execSQLQuery(String s) throws SQLException
    Execute a SQL query that returns a single resultset. Never causes a new transaction to be started regardless of the autocommit setting.
    Parameters:
      `s` - the query to execute
    Returns:
      the (non-null) returned resultset
    Throws:
      `SQLException` - if something goes wrong.

  - ### execSQLQuery

    ResultSet execSQLQuery(String s, int resultSetType, int resultSetConcurrency) throws SQLException
    Throws:
      `SQLException`

  - ### execSQLUpdate

    void execSQLUpdate(String s) throws SQLException
    Execute a SQL query that does not return results. Never causes a new transaction to be started regardless of the autocommit setting.
    Parameters:
      `s` - the query to execute
    Throws:
      `SQLException` - if something goes wrong.

  - ### getQueryExecutor

    QueryExecutor getQueryExecutor()
    Get the QueryExecutor implementation for this connection.
    Returns:
      the (non-null) executor

  - ### getReplicationProtocol

    ReplicationProtocol getReplicationProtocol()
    Internal protocol for work with physical and logical replication. Physical replication available only since PostgreSQL version 9.1. Logical replication available only since PostgreSQL version 9.4.
    Returns:
      not null replication protocol

  - ### getObject

    Object getObject(String type, @Nullable String value, byte @Nullable [] byteValue) throws SQLException
    Construct and return an appropriate object for the given type and value. This only considers the types registered via `PGConnection.addDataType(String, Class)` and `PGConnection.addDataType(String, String)`.

    If no class is registered as handling the given type, then a generic `PGobject` instance is returned.

    value or byteValue must be non-null

    Parameters:
      `type` - the backend typename
      `value` - the type-specific string representation of the value
      `byteValue` - the type-specific binary representation of the value
    Returns:
      an appropriate object; never null.
    Throws:
      `SQLException` - if something goes wrong

  - ### getEncoding

    @Pure Encoding getEncoding() throws SQLException
    Throws:
      `SQLException`

  - ### getTypeInfo

    TypeInfo getTypeInfo()

  - ### haveMinimumServerVersion

    boolean haveMinimumServerVersion(int ver)
    Check if we have at least a particular server version.

    The input version is of the form xxyyzz, matching a PostgreSQL version like xx.yy.zz. So 9.0.12 is 90012.

    Parameters:
      `ver` - the server version to check, of the form xxyyzz eg 90401
    Returns:
      true if the server version is at least "ver".

  - ### haveMinimumServerVersion

    boolean haveMinimumServerVersion(Version ver)
    Check if we have at least a particular server version.

    The input version is of the form xxyyzz, matching a PostgreSQL version like xx.yy.zz. So 9.0.12 is 90012.

    Parameters:
      `ver` - the server version to check
    Returns:
      true if the server version is at least "ver".

  - ### encodeString

    byte @PolyNull [] encodeString(@PolyNull String str) throws SQLException
    Encode a string using the database's client_encoding (usually UTF8, but can vary on older server versions). This is used when constructing synthetic resultsets (for example, in metadata methods).
    Parameters:
      `str` - the string to encode
    Returns:
      an encoded representation of the string
    Throws:
      `SQLException` - if something goes wrong.

  - ### escapeString

    String escapeString(String str) throws SQLException
    Escapes a string for use as string-literal within an SQL command. The method chooses the applicable escaping rules based on the value of `getStandardConformingStrings()`.
    Parameters:
      `str` - a string value
    Returns:
      the escaped representation of the string
    Throws:
      `SQLException` - if the string contains a `\0` character

  - ### getStandardConformingStrings

    boolean getStandardConformingStrings()
    Returns whether the server treats string-literals according to the SQL standard or if it uses traditional PostgreSQL escaping rules. Versions up to 8.1 always treated backslashes as escape characters in string-literals. Since 8.2, this depends on the value of the `standard_conforming_strings` server variable.
    Returns:
      true if the server treats string literals according to the SQL standard
    See Also:
      - `QueryExecutor.getStandardConformingStrings()`

  - ### getTimestampUtils

    @Deprecated TimestampUtils getTimestampUtils()
    Deprecated.

  - ### getLogger

    Logger getLogger()

  - ### getStringVarcharFlag

    boolean getStringVarcharFlag()

  - ### getTransactionState

    TransactionState getTransactionState()
    Get the current transaction state of this connection.
    Returns:
      current transaction state of this connection

  - ### binaryTransferSend

    boolean binaryTransferSend(int oid)
    Returns true if value for the given oid should be sent using binary transfer. False if value should be sent using text transfer.
    Parameters:
      `oid` - The oid to check.
    Returns:
      True for binary transfer, false for text transfer.

  - ### isColumnSanitiserDisabled

    boolean isColumnSanitiserDisabled()
    Return whether to disable column name sanitation.
    Returns:
      true column sanitizer is disabled

  - ### addTimerTask

    void addTimerTask(TimerTask timerTask, long milliSeconds)
    Schedule a TimerTask for later execution. The task will be scheduled with the shared Timer for this connection.
    Parameters:
      `timerTask` - timer task to schedule
      `milliSeconds` - delay in milliseconds

  - ### purgeTimerTasks

    void purgeTimerTasks()
    Invoke purge() on the underlying shared Timer so that internal resources will be released.

  - ### getFieldMetadataCache

    LruCache<FieldMetadata.Key,FieldMetadata> getFieldMetadataCache()
    Return metadata cache for given connection.
    Returns:
      metadata cache

  - ### createQuery

    CachedQuery createQuery(String sql, boolean escapeProcessing, boolean isParameterized, String... columnNames) throws SQLException
    Throws:
      `SQLException`

  - ### setFlushCacheOnDeallocate

    void setFlushCacheOnDeallocate(boolean flushCacheOnDeallocate)
    By default, the connection resets statement cache in case deallocate all/discard all message is observed. This API allows to disable that feature for testing purposes.
    Parameters:
      `flushCacheOnDeallocate` - true if statement cache should be reset when "deallocate/discard" message observed

  - ### hintReadOnly

    boolean hintReadOnly()
    Indicates if statements to backend should be hinted as read only.
    Returns:
      Indication if hints to backend (such as when transaction begins) should be read only.
    See Also:
      - `PGProperty.READ_ONLY_MODE`

  - ### getXmlFactoryFactory

    PGXmlFactoryFactory getXmlFactoryFactory() throws SQLException
    Retrieve the factory to instantiate XML processing factories.
    Returns:
      The factory to use to instantiate XML processing factories
    Throws:
      `SQLException` - if the class cannot be found or instantiated.

  - ### getLogServerErrorDetail

    boolean getLogServerErrorDetail()
    Indicates if error details from server used in included in logging and exceptions.
    Returns:
      true if should be included and passed on to other exceptions

  - ### getConvertBooleanToNumeric

    boolean getConvertBooleanToNumeric()
    Returns true if boolean values should be converted to numeric types (1/0).
    Returns:
      true if boolean to numeric conversion is enabled