Package org.dspace.storage.rdbms

Class DatabaseUtils

java.lang.Object
org.dspace.storage.rdbms.DatabaseUtils
public class DatabaseUtils extends Object
Utility class used to manage the Database. This class is used by the DatabaseManager to initialize/upgrade/migrate the Database. It can also be called via the commandline as necessary to get information about the database.

Currently, we use Flyway DB (http://flywaydb.org/) for database management.

Author:
Tim Donohue

  • Field Details

  • Method Details

    • main

      public static void main(String[] argv)
      Commandline tools for managing database changes, etc.
      Parameters:
      argv - the command line arguments given

    • updateDatabase

      public static void updateDatabase() throws SQLException
      Ensures the current database is up-to-date with regards to the latest DSpace DB schema. If the scheme is not up-to-date, then any necessary database migrations are performed.

      FlywayDB (http://flywaydb.org/) is used to perform database migrations. If a Flyway DB migration fails it will be rolled back to the last successful migration, and any errors will be logged.

      Throws:
      SQLException - if database error If database cannot be upgraded.

    • updateDatabase

      protected static void updateDatabase(DataSource datasource, Connection connection) throws SQLException
      Ensures the current database is up-to-date with regards to the latest DSpace DB schema. If the scheme is not up-to-date, then any necessary database migrations are performed.

      FlywayDB (http://flywaydb.org/) is used to perform database migrations. If a Flyway DB migration fails it will be rolled back to the last successful migration, and any errors will be logged.

      Parameters:
      datasource - DataSource object (retrieved from DatabaseManager())
      connection - Database connection
      Throws:
      SQLException - if database error If database cannot be upgraded.

    • updateDatabase

      protected static void updateDatabase(DataSource datasource, Connection connection, String targetVersion, boolean outOfOrder) throws SQLException
      Ensures the current database is up-to-date with regards to the latest DSpace DB schema. If the scheme is not up-to-date, then any necessary database migrations are performed.

      FlywayDB (http://flywaydb.org/) is used to perform database migrations. If a Flyway DB migration fails it will be rolled back to the last successful migration, and any errors will be logged.

      Parameters:
      datasource - DataSource object (retrieved from DatabaseManager())
      connection - Database connection
      targetVersion - If specified, only migrate the database to a particular *version* of DSpace. This is just useful for testing migrations, and should NOT be used in Production. If null, the database is migrated to the latest version.
      outOfOrder - If true, Flyway will run any lower version migrations that were previously "ignored". If false, Flyway will only run new migrations with a higher version number.
      Throws:
      SQLException - if database error If database cannot be upgraded.

    • updateDatabase

      protected static void updateDatabase(DataSource datasource, Connection connection, String targetVersion, boolean outOfOrder, boolean forceMigrate) throws SQLException
      Ensures the current database is up-to-date with regards to the latest DSpace DB schema. If the scheme is not up-to-date, then any necessary database migrations are performed.

      FlywayDB (http://flywaydb.org/) is used to perform database migrations. If a Flyway DB migration fails it will be rolled back to the last successful migration, and any errors will be logged.

      Parameters:
      datasource - DataSource object (retrieved from DatabaseManager())
      connection - Database connection
      targetVersion - If specified, only migrate the database to a particular *version* of DSpace. This is just useful for testing migrations, and should NOT be used in Production. If null, the database is migrated to the latest version.
      outOfOrder - If true, Flyway will run any lower version migrations that were previously "ignored". If false, Flyway will only run new migrations with a higher version number.
      forceMigrate - If true, always run a Flyway migration, even if no "Pending" migrations exist. This can be used to trigger Flyway Callbacks manually. If false, only run migration if pending migrations exist, otherwise do nothing.
      Throws:
      SQLException - if database error If database cannot be upgraded.

    • tableExists

      public static boolean tableExists(Connection connection, String tableName)
      Determine if a particular database table exists in our database
      Parameters:
      connection - Current Database Connection
      tableName - The name of the table
      Returns:
      true if table of that name exists, false otherwise

    • tableExists

      public static boolean tableExists(Connection connection, String tableName, boolean caseSensitive)
      Determine if a particular database table exists in our database
      Parameters:
      connection - Current Database Connection
      tableName - The name of the table
      caseSensitive - When "true", the case of the tableName will not be changed. When "false, the name may be uppercased or lowercased based on DB type.
      Returns:
      true if table of that name exists, false otherwise

    • tableColumnExists

      public static boolean tableColumnExists(Connection connection, String tableName, String columnName)
      Determine if a particular database column exists in our database
      Parameters:
      connection - Current Database Connection
      tableName - The name of the table
      columnName - The name of the column in the table
      Returns:
      true if column of that name exists, false otherwise

    • sequenceExists

      public static boolean sequenceExists(Connection connection, String sequenceName)

    • executeSql

      public static void executeSql(Connection connection, String sqlToExecute) throws SQLException
      Execute a block of SQL against the current database connection.

      The SQL is executed using the Flyway SQL parser.

      Parameters:
      connection - Current Database Connection
      sqlToExecute - The actual SQL to execute as a String
      Throws:
      SQLException - if database error If a database error occurs

    • getSchemaName

      public static String getSchemaName(Connection connection) throws SQLException
      Get the Database Schema Name in use by this Connection, so that it can be used to limit queries in other methods (e.g. tableExists()).
      Parameters:
      connection - Current Database Connection
      Returns:
      Schema name as a string, or "null" if cannot be determined or unspecified
      Throws:
      SQLException - An exception that provides information on a database access error or other errors.

    • getDBUserName

      public static String getDBUserName(Connection connection) throws SQLException
      Get the Database User Name in use by this Connection.
      Parameters:
      connection - Current Database Connection
      Returns:
      User name as a string, or "null" if cannot be determined or unspecified
      Throws:
      SQLException - An exception that provides information on a database access error or other errors.

    • canonicalize

      public static String canonicalize(Connection connection, String dbIdentifier) throws SQLException
      Return the canonical name for a database identifier based on whether this database defaults to storing identifiers in uppercase or lowercase.
      Parameters:
      connection - Current Database Connection
      dbIdentifier - Identifier to canonicalize (may be a table name, column name, etc)
      Returns:
      The canonical name of the identifier.
      Throws:
      SQLException - An exception that provides information on a database access error or other errors.

    • setReindexDiscovery

      public static void setReindexDiscovery(boolean reindex)
      Whether or not to tell Discovery to reindex itself based on the updated database.

      Whenever a DB migration occurs this is set to "true" to ensure the Discovery index is updated. When Discovery initializes it calls checkReindexDiscovery() to reindex if this flag is true.

      Because the DB migration may be initialized by commandline or any one of the many DSpace webapps, setting this to "true" actually writes a temporary file which lets Solr know when reindex is needed.

      Parameters:
      reindex - true or false

    • getReindexDiscovery

      public static boolean getReindexDiscovery()
      Whether or not reindexing is required in Discovery.

      Because the DB migration may be initialized by commandline or any one of the many DSpace webapps, this checks for the existence of a temporary file, and the discovery.autoReindex setting to know when Discovery/Solr needs reindexing.

      Returns:
      whether reindexing should happen.

    • checkReindexDiscovery

      public static void checkReindexDiscovery(IndexingService indexer)
      Method to check whether we need to reindex in Discovery (i.e. Solr). If reindexing is necessary, it is performed. If not, nothing happens.

      This method is called by Discovery whenever it initializes a connection to Solr.

      Parameters:
      indexer - The actual indexer to use to reindex Discovery, if needed
      See Also:

    • getDbType

      public static String getDbType(Connection connection) throws SQLException
      Determine the type of Database, based on the DB connection.
      Parameters:
      connection - current DB Connection
      Returns:
      a DB keyword/type (see DatabaseUtils.DBMS_* constants)
      Throws:
      SQLException - if database error

    • getDataSource

      protected static DataSource getDataSource()
      Get a reference to the configured DataSource (which can be used to initialize the database using Flyway). The DataSource is configured via our ServiceManager (i.e. via Spring).

      This is NOT public, as we discourage direct connections to the database which bypass Hibernate. Only Flyway should be allowed a direct connection.

      Returns:
      DataSource

    • getCurrentFlywayState

      public static String getCurrentFlywayState(Connection connection) throws SQLException
      Returns the current Flyway schema_version being used by the given database. (i.e. the version of the highest numbered migration that this database has run)
      Parameters:
      connection - current DB Connection
      Returns:
      version as string
      Throws:
      SQLException - if database error occurs

    • getCurrentFlywayDSpaceState

      public static Double getCurrentFlywayDSpaceState(Connection connection) throws SQLException
      Return the DSpace version that this Flyway-enabled database reports to be compatible with. The version is retrieved from Flyway, and parsed into a Double to represent an actual DSpace version number (e.g. 5.0, 6.0, etc)
      Parameters:
      connection - current DB Connection
      Returns:
      reported DSpace version as a Double
      Throws:
      SQLException - if database error occurs