Contribute to the DSpace Development Fund

The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.

"database" command

This command can be used at any time to manage or upgrade the Database. It will also assist in troubleshooting PostgreSQL and Oracle connection issues with the database.

Command used:

[dspace]/bin/dspace database

Java class:

org.dspace.storage.rdbms.DatabaseUtils

Valid Arguments:

Description

testTest the database connection settings (in [dspace]/config/dspace.cfg or local.cfg) are OK and working properly.  This command also validates the database version is compatible with DSpace.
info / status

Provide detailed information about the DSpace database itself. This includes the database type, version, driver, schema, and any successful/failed/pending database migrations.

This command, along with "test", is very useful in debugging issues with your database.

migrate

Migrate the database to the latest version (if not already on the latest version). This uses FlywayDB along with embedded migrations scripts to automatically update your database to the latest version.

Additional 'migrate' options:

  • "migrate ignored" will run a migration which also includes any database migrations which are flagged as "Ignored" (or "Skipped") by the "info" command. If these "Ignored" migrations succeed, they will now be noted (in the "info" command) as having run "Out Of Order" (i.e. they were successful, but they were executed out of the normal, numerical order). 
  • "migrate force" (available in 7.1 and later) will run a migration even when no new migrations exist (i.e. no migrations are currently flagged as "Pending" when using the "info" command). This can be used to force the post-migration ("callback") scripts to run.  Normally, these post-migration scripts only run after a new migrations are applied. They will (re-)initialize your database with required objects, like the "Site" object, default groups (Administrator/Anonymous) and default metadata registry and bitstream format registry entries.
repair

Attempt to "repair" any migrations which are flagged as "Failed" by the "info" command and/or resolve failed checksum validation. This runs the FlywayDB repair command.

Please note however, this will NOT automatically repair corrupt or broken data in your database. It merely tries to re-run previously "Failed" migrations and/or realign the checksums of the applied migrations to the ones of the available migrations.

skip

(Available in 7.5 and later) Allows you to "skip" individual database migrations. Skipping a migration will flag it as having run successfully (either "Success" or "Out of Order" status), but the migration will not be executed.

WARNING: You should ONLY skip migrations which are no longer required or have become obsolete. Skipping a REQUIRED migration may result in DSpace failing to startup or function properly.  The only fix to that scenario would be to run the migration manually (by executing the SQL directly on the database).  Therefore, this "skip" command should ONLY be used when the migration is known to be obsolete or no longer valid.  All other usages are unsupported.

update-sequences

Update database sequences after running a bulk ingest (e.g. AIP Backup and Restore) or data migration.

validateValidate the checksums of all previously run database migrations. This runs the FlywayDB 'validate' command.
clean

Completely and permanently delete all tables and data in this database. WARNING: There is no turning back! If you run this command, you will lose your entire database and all its contents.

This command is only useful for testing or for reverting your database to a "fresh install" state (e.g. running "dspace database clean" followed by "dspace database migrate" will return your database to a fresh install state)

By default the 'clean' command is disabled (to avoid accidental data loss). In order to enable it, you must first set db.cleanDisabled=false in either your local.cfg or dspace.cfg.

Guide to Flyway Migration States

Whenever you run the "info" or "status" option (e.g. ./dspace database info), you'll see a table listing all Flyway migrations which were run on your database.

In the "State" column of that table you'll see the various states that Flyway returns for each migration:

  • "Baseline" - This state simply notes when your database was originally created.  In other words, it's the first migration in the table
  • "Success" -  The state means that the migration was successful. It completed without any errors.
  • "Out of Order" - This state means the migration was successful but was run in a different order than the default. By default, Flyway will run all migrations in numerical order (based on the "Version" column in that table).  These "Out of Order" entries are normal and will occur in almost every production DSpace. These entries are a sign of backported bug fixes which required a database migration.  Those backported fixes may be required to run in non-numerical order. 
    • For example: If we found a database issue that impacts both 7.x and 8.x, we may create a migration numbered "7.9.[date]" which is safe to run on both 7.x and 8.x.  If your site is already on 8.x, this migration would be flagged as "Out of Order" because it starts with "7.9.*" and was run after other "8.0.*" migrations were already run.
  • "Ignored" - This state means the migration was skipped (because it's not in numerical order) and has not yet been run.  To run it, you'd run "./dspace database migrate ignored".   Ignored migrations will move into the "Out of Order" state if they are successfully run.
  • "Pending" - This state means the migration has not yet been run.  It's waiting for the next time you call "./dspace database migrate".


  • No labels

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.