Module is.codion.common.db
Package is.codion.common.db.database

Interface Database

All Superinterfaces:
ConnectionFactory
All Known Implementing Classes:
AbstractDatabase
public interface Database extends ConnectionFactory
Defines DBMS specific functionality as well as basic database configuration settings.
See Also:

  • Field Details

    • DATABASE_URL

      static final PropertyValue<String> DATABASE_URL
      Specifies the jdbc url of the database.

    • URL_SCOPED_INSTANCE

      static final PropertyValue<Boolean> URL_SCOPED_INSTANCE
      Specifies whether instance() should create a new instance each time the database URL has changed. This is convenient when running tests using in-memory databases.
      • Value type: Boolean
      • Default value: false
      See Also:

    • DATABASE_INIT_SCRIPTS

      static final PropertyValue<String> DATABASE_INIT_SCRIPTS
      A comma separated list of paths to scripts to run when initializing the database, implementation specific

    • CONNECTION_VALIDITY_CHECK_TIMEOUT

      static final PropertyValue<Integer> CONNECTION_VALIDITY_CHECK_TIMEOUT
      Specifies the timeout (in seconds) to use when checking if database connections are valid. This determines how long to wait for a connection validity check before considering it failed. Lower values detect failed connections faster but may timeout prematurely on slow networks.
      • Value type: Integer
      • Default value: 2 seconds
      • Property name: codion.db.validityCheckTimeout
      • Valid range: 1-30 seconds (typically 2-10 seconds for most networks)

    • COUNT_QUERIES

      static final PropertyValue<Boolean> COUNT_QUERIES
      Specifies whether database queries should be counted for collecting statistics.
      • Value type: Boolean
      • Default value: false

    • SELECT_FOR_UPDATE_NOWAIT

      static final PropertyValue<Boolean> SELECT_FOR_UPDATE_NOWAIT
      Specifies whether 'select for update' should be NOWAIT, if supported by the database.
      A database implementation may disregard this.
      • Value type: Boolean
      • Default value: true

    • LOGIN_TIMEOUT

      static final PropertyValue<Integer> LOGIN_TIMEOUT
      Specifies the default login timeout (in seconds).
      • Value type: Integer
      • Default value: 2

    • TRANSACTION_ISOLATION

      static final PropertyValue<Integer> TRANSACTION_ISOLATION
      Specifies the transaction isolation to set for created connections
      • Value type: Integer
      • Default value: null
      See Also:

    • USER_PROPERTY

      static final String USER_PROPERTY
      The constant used to denote the username value in the connection properties
      See Also:

    • PASSWORD_PROPERTY

      static final String PASSWORD_PROPERTY
      The constant used to denote the password value in the connection properties
      See Also:

  • Method Details

    • name

      String name()
      Returns:
      a name identifying this database

    • autoIncrementQuery

      String autoIncrementQuery(String idSource)
      Returns a query string for retrieving the last automatically generated id from the given id source
      Parameters:
      idSource - the source for the id, for example a sequence name or in the case of Derby, the name of the table auto generating the value
      Returns:
      a query string for retrieving the last auto-increment value from idSource
      Throws:
      NullPointerException - in case idSource is required and is null

    • sequenceQuery

      String sequenceQuery(String sequenceName)
      Returns a query string for selecting the next value from the given sequence.
      Parameters:
      sequenceName - the name of the sequence
      Returns:
      a query for selecting the next value from the given sequence
      Throws:
      UnsupportedOperationException - in case the underlying database does not support sequences
      NullPointerException - in case sequenceName is null

    • selectForUpdateClause

      String selectForUpdateClause()
      Returns a select for update clause, an empty string if not supported.
      Returns:
      a select for update clause

    • limitOffsetClause

      String limitOffsetClause(@Nullable Integer limit, @Nullable Integer offset)
      Returns a limit/offset clause variation for this database, based on the given limit and offset values. If both are null an empty string is returned.
      Parameters:
      limit - the limit
      offset - the offset
      Returns:
      a limit/offset clause

    • subqueryRequiresAlias

      boolean subqueryRequiresAlias()
      Returns true if this database requires that subqueries by aliased.
      Returns:
      true if subqueries require an alias

    • maximumParameters

      int maximumParameters()
      Returns the maximum number of prepared statement parameters, supported by this database. The default implementation simply returns Integer.MAX_VALUE, as in, no limit.
      Returns:
      the maximum number of prepared statement parameters, supported by this database.

    • errorMessage

      @Nullable String errorMessage(SQLException exception, Database.Operation operation)
      Returns a user-friendly error message for the given exception, otherwise simply return the message from exception
      Parameters:
      exception - the underlying SQLException
      operation - the operation resulting in the exception
      Returns:
      the message assigned to the given exception
      Throws:
      NullPointerException - in case exception or operation is null

    • exception

      DatabaseException exception(SQLException exception, Database.Operation operation)
      Maps the given SQLException to a DatabaseException.
      Parameters:
      exception - the SQL exception
      operation - the current operation
      Returns:
      a DatabaseException
      Throws:
      NullPointerException - in case exception or operation is null
      See Also:

    • isAuthenticationException

      boolean isAuthenticationException(SQLException exception)
      Returns true if this exception represents a login credentials failure
      Parameters:
      exception - the exception
      Returns:
      true if this exception represents a login credentials failure
      Throws:
      NullPointerException - in case exception is null

    • isReferentialIntegrityException

      boolean isReferentialIntegrityException(SQLException exception)
      Returns true if this exception is a referential integrity exception
      Parameters:
      exception - the exception
      Returns:
      true if this exception is a referential integrity exception
      Throws:
      NullPointerException - in case exception is null

    • isUniqueConstraintException

      boolean isUniqueConstraintException(SQLException exception)
      Returns true if this exception is a unique key exception
      Parameters:
      exception - the exception
      Returns:
      true if this exception is a unique key exception
      Throws:
      NullPointerException - in case exception is null

    • isTimeoutException

      boolean isTimeoutException(SQLException exception)
      Returns true if this exception is a timeout exception
      Parameters:
      exception - the exception
      Returns:
      true if this exception is a timeout exception
      Throws:
      NullPointerException - in case exception is null

    • queryCounter

      Database.QueryCounter queryCounter()
      Returns:
      the Database.QueryCounter for collecting query statistics

    • statistics

      Database.Statistics statistics()
      Returns statistics collected via queryCounter(). Note that calling this method resets the counter.
      Returns:
      collected statistics.

    • createConnectionPool

      ConnectionPoolWrapper createConnectionPool(ConnectionPoolFactory connectionPoolFactory, User poolUser)
      Creates a connection pool for the given user in this database.
      Parameters:
      connectionPoolFactory - the ConnectionPoolFactory implementation to use
      poolUser - the user for which to create a connection pool
      Returns:
      a new ConnectionPoolWrapper
      Throws:
      DatabaseException - in case of a database exception

    • containsConnectionPool

      boolean containsConnectionPool(String username)
      Parameters:
      username - the username
      Returns:
      true if a connection pool exists for the given username

    • connectionPool

      ConnectionPoolWrapper connectionPool(String username)
      Parameters:
      username - the username
      Returns:
      the connection pool for the given user
      Throws:
      IllegalArgumentException - in case no connection pool exists for the given user

    • connectionPoolUsernames

      Collection<String> connectionPoolUsernames()
      Returns:
      the usernames of all available connection pools

    • closeConnectionPool

      void closeConnectionPool(String username)
      Closes and removes the pool associated with the given user
      Parameters:
      username - the username of the pool that should be removed

    • closeConnectionPools

      void closeConnectionPools()
      Closes and removes all available connection pools

    • connectionProvider

      void connectionProvider(ConnectionProvider connectionProvider)
      Sets the ConnectionProvider instance to use when creating connections.
      Parameters:
      connectionProvider - the connection provider

    • instance

      static Database instance()
      Returns a Database instance based on the currently configured JDBC URL (DATABASE_URL). Subsequent changes to DATABASE_URL will cause an exception to be thrown unless URL_SCOPED_INSTANCE is enabled, then a new instance is created and returned.
      Returns:
      a Database instance based on the current jdbc url
      Throws:
      IllegalArgumentException - in case an unsupported database type is specified
      RuntimeException - in case of an exception occurring while instantiating the database implementation
      DatabaseException - in case DATABASE_URL has changed and URL_SCOPED_INSTANCE is not enabled
      See Also: