Module is.codion.dbms.h2
Package is.codion.dbms.h2

Class H2DatabaseFactory

java.lang.Object
is.codion.dbms.h2.H2DatabaseFactory
All Implemented Interfaces:
DatabaseFactory
public final class H2DatabaseFactory extends Object implements DatabaseFactory
Provides h2 database implementations.

An embedded database, in memory or in a file, runs its init scripts, Database.INIT_SCRIPTS, as sa, when an instance is created for it, once per JVM until the database is closed. Each script runs once in the database's life:

  • a new database runs them all, in the order listed;
  • an existing file database runs those it has not yet run, in the order listed, so a script added to the list brings it up to date;
  • each script run is recorded in the table CODION.INIT_SCRIPT, by its path as listed, with a SHA-256 checksum of its content, line endings aside;
  • a script moved, listed by another path, with the content of one recorded but no longer listed, does not run again, its record taking the new path.
The database is refused with a DatabaseException, and left as it was, where a script has changed since it ran, where a script has run but is no longer listed, or where a script not yet run is listed before one that has. validateInitScripts(Connection, String...) tells without opening it, for a copy of a database, say.

A script that fails is not recorded, and runs again the next time. H2's DDL commits, so a failed script may leave part of its work behind.

An existing file database without the table, created before the scripts were recorded, or with none listed, ran none since its creation, so the first time it records every script listed as run, running none, and only scripts added to the list later run. It is taken to hold what the list says, so:

  • a script added in the same release as the upgrade to recorded scripts, or as the first scripts listed, is recorded without having run: add it in a later release;
  • a database restored from a copy taken before the upgrade, into a release whose list has grown since, records the scripts added since without having run them: restore such a copy only into a release listing the same scripts.

A database on a server, or in a zip file, is not initialized, nor an existing one refusing sa without a password, its admin having one or being another: administered, its scripts run by its administrator, and a script listed for it never run.

A thread interrupted during I/O closes the file of a database opened with jdbc:h2:file:, every connection to it failing until it is reopened. Where its threads may be interrupted, open it with jdbc:h2:async: instead, the file being the same. Every URL to a database in a JVM must then use the same prefix.

  • Constructor Details

    • H2DatabaseFactory

      public H2DatabaseFactory()

  • Method Details

    • supports

      public boolean supports(String driverClassName)
      Specified by:
      supports in interface DatabaseFactory
      Parameters:
      driverClassName - the driver class name
      Returns:
      true if this database factory supports the given driver

    • create

      public Database create(String url)
      Specified by:
      create in interface DatabaseFactory
      Parameters:
      url - the jdbc url
      Returns:
      a new Database implementation based on the given jdbc url.

    • database

      public static Database database(String url, String... initScripts)
      Creates an H2 Database instance
      Parameters:
      url - the jdbc url
      initScripts - the init scripts, each run once in the database's life, see H2DatabaseFactory
      Returns:
      an H2 Database instance

    • validateInitScripts

      public static void validateInitScripts(Connection connection, String... initScripts) throws SQLException
      Validates a database against the init scripts it would be opened with, refusing it as opening it would, see H2DatabaseFactory, changing nothing, so the connection may be read only. A database without the record of its scripts is never refused, nor one opened with none listed.
      Parameters:
      connection - a connection to the database
      initScripts - the init scripts it would be opened with
      Throws:
      DatabaseException - in case the database would be refused, or a script listed can not be read
      SQLException - in case the record of the scripts run can not be read

    • scriptRunner

      public static H2DatabaseFactory.ScriptRunner scriptRunner(String jdbcUrl)
      Creates a new ScriptRunner instance, using by default the sysadmin username (sa) and the default system charset.
      Parameters:
      jdbcUrl - the jdbc URL
      Returns:
      a new H2DatabaseFactory.ScriptRunner instance