Database

Database management

The server uses a series of database changesets to automatically initialise and update its tables, indexes and occasionally also the contained data, to accommodate new software versions. Each time the server starts up, the system checks for new changesets to apply before completing the bootstrap sequence. 

The database update begins by acquiring a lock on the database, to prevent multiple clients from simultaneously running updates on the server. The update then begins a transaction. If the update fails, all database operations will be rolled back and leave the database in the exact same state that it had before the update begun.

Once a changeset has been successfully applied to the server, it will not be applied again. Please keep this in mind, since it might have consequences in rollback scenarios.  When a new version contains a changeset that might need special treatment in case of rollback, this should be clearly stated in the release notes.


WARNING: If the server is shut down during the startup sequence, before the database lock is released, the lock will remain indefinitely and needs to be removed manually.

The beginning and end of the update task is indicated in the application log with the lines

[DbManagementVerticle]  INFO: Running database management...
[DbManagementVerticle]  INFO: Database management finished

If the second line fails to show up within reasonable time, it might indicate that a previous unreleased lock is stopping the update task from running. 

Make sure that all servers that are accessing the database is shut down, then log into the database and check if this is the case by running the following query

SELECT * FROM DATABASECHANGELOGLOCK

If the result shows is similar to 

ID LOCKED LOCKGRANTED LOCKEDBY
1 1 2021-04-22 08:27:26.588
10.0.1.28 (10.0.1.28)

the database lock has not been properly released. Remove it by deleting the row:

DELETE FROM DATABASECHANGELOGLOCK

Important: before deleting the lock, make absolutely sure that no server is waiting to executing the update job.