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 Summary

Fields

Modifier and Type	Field	Description
static String	DBMS_H2
static String	DBMS_ORACLE
static String	DBMS_POSTGRES

Method Summary

Modifier and Type	Method	Description
static String	canonicalize(Connection connection, String dbIdentifier)	Return the canonical name for a database identifier based on whether this database defaults to storing identifiers in uppercase or lowercase.
static void	checkReindexDiscovery(IndexingService indexer)	Method to check whether we need to reindex in Discovery (i.e.
static void	clearFlywayDBCache()	In case of a unit test the flyway db is cached to long leading to exceptions, we need to clear the object
static void	executeSql(Connection connection, String sqlToExecute)	Execute a block of SQL against the current database connection.
static Double	getCurrentFlywayDSpaceState(Connection connection)	Return the DSpace version that this Flyway-enabled database reports to be compatible with.
static String	getCurrentFlywayState(Connection connection)	Returns the current Flyway schema_version being used by the given database.
protected static DataSource	getDataSource()	Get a reference to the configured DataSource (which can be used to initialize the database using Flyway).
static String	getDbType(Connection connection)	Determine the type of Database, based on the DB connection.
static boolean	getReindexDiscovery()	Whether or not reindexing is required in Discovery.
static String	getSchemaName(Connection connection)	Get the Database Schema Name in use by this Connection, so that it can be used to limit queries in other methods (e.g.
static void	main(String[] argv)	Commandline tools for managing database changes, etc.
static boolean	sequenceExists(Connection connection, String sequenceName)
static void	setReindexDiscovery(boolean reindex)	Whether or not to tell Discovery to reindex itself based on the updated database.
static boolean	tableColumnExists(Connection connection, String tableName, String columnName)	Determine if a particular database column exists in our database
static boolean	tableExists(Connection connection, String tableName)	Determine if a particular database table exists in our database
static boolean	tableExists(Connection connection, String tableName, boolean caseSensitive)	Determine if a particular database table exists in our database
static void	updateDatabase()	Ensures the current database is up-to-date with regards to the latest DSpace DB schema.
protected static void	updateDatabase(DataSource datasource, Connection connection)	Ensures the current database is up-to-date with regards to the latest DSpace DB schema.
protected static void	updateDatabase(DataSource datasource, Connection connection, String targetVersion, boolean outOfOrder)	Ensures the current database is up-to-date with regards to the latest DSpace DB schema.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DBMS_POSTGRES

public static final String DBMS_POSTGRES

See Also:

Constant Field Values

DBMS_ORACLE

public static final String DBMS_ORACLE

See Also:

Constant Field Values

DBMS_H2

public static final String DBMS_H2

See Also:

Constant Field Values

Method Detail

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 mostly just useful for testing. 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.

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.

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:

SolrServiceImpl

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

clearFlywayDBCache

public static void clearFlywayDBCache()

In case of a unit test the flyway db is cached to long leading to exceptions, we need to clear the object

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