Please read carefully before starting the upgrade process.
Depending on whether there have been changes to the DBmarlin repository schema between the currently installed version and target version, the upgrade may be very fast or could take some time.
- Upgrading between versions where the DBmarlin schema has not changed is a quick process and just requires the new tar.gz file to be extracted over the top of the old installation while all DBmarlin processes are stopped and then running
- Upgrading between versions where the DBmarlin schema has has changed, will take longer and will require a period of downtime while the data is migrated to the new schema.
Please follow the pre-requistes first to find out which case you are dealing with. The upgrade steps will be the same in either case but the time taken to complete will be different.
Follow the pre-requisites below to check the repository schema version for the version you already have and the version you are looking to install.
Backup existing installation
It is a good idea to have a backup of the current installation to rollback to in the event that the upgrade is unsucessful. A directory copy or filesystem snapshot while the DBmarlin processess have been stopped would give you something to restore back if needed.
Download the latest version
dbmarlin-Linux-x64-[VERSION].tar.gz file from https://www.dbmarlin.com/download
Check the current schema version
You can see which version you have installed and the version of the repository schema it is using by looking at the
version.txt file in the root of the DBmarlin intallation directory. For example:
Check the new schema version to be installed
Extract the tar.gz of the newer version into a temporary location and do the same check of the
version.txt file to check the schema-version.
If the schema-version is the same as the one you already have, then no data migration is required and the upgrade will be quick. If the schema-version is newer than the one you already have, then data migration is required which could take some time. Additionally, you must check you have enough disk space before proceeding.
Checking disk space
If the schema-version has changed then you should make sure that you have enough disk space on the volume where DBmarlin is installed to accommodate double the amount of data, plus 10 percent headroom, for a short period of time while migration completes. You can use
du to get the disk usage for the DBmarlin directory and
df to get the disk space available on the file system which DBmarlin is installed on. For example:
In the example above DBmarlin is using 6.1GB so would required an extra 6.71GB (6.1GB +10%) free space to complete the upgrade. The filesystem has 87GB available so we are ok to proceed.
Once the data migration has completed and all data has been copied to the new schema, the old schema will be automatically dropped freeing up the extra disk space.
Stop all DBmarlin server components
Stop all DBmarlin processeses and make sure they are all stoppped.
Extract the tar.gz file
Extract the newer tar.gz over the top of the current install. For example if DBmarlin is installed in
/opt/dbmarlin then run:
Configure the installation
After extracting the tar.gz file you will find
configure.sh which needs to be run first before you can start up the server. This configures ports and other settings.
configure.sh will check if this is a first time installation or if there is an existing schema and whether that schema is already the correct version or if a new schema needs to be created.
Scenario 1 - No schema update necessary
If the schema version is the same you will see a message like this indicating that no schema change required and the upgrade is now complete. You can run
start.sh to restart all processes.
Scenario 2 - New schema and data migration required
If a new schema is needed, you will see a message like this. This means a new schema is needed. The data migration will start in the background once you run
Data migration could take several minutes or even several hours for large databases. During this time you will not be able to start any sensors until the migration has completed.
Restart all DBmarlin server components
Checking the upgrade progress
You can tail the latest Tomcat localhost log file to see where the upgrade has got up to. The biggest tables
statistic are the ones which will take longest time. Please be patient.
Once complete you will see a log message showing the total time for the migration E.g.
Data-migrator: data migration took 1447031ms. You can now go back to the DBmarlin UI in your browser and see that the sensors have are back to their previous state prior to the upgrade; if they were stopped, then they will need to be manually restarted, otherwise if they were started then they should now have restarted and new data should start being collected.
If you try to start/stop/edit a sensor which the upgrade is in progress you will be prevented from doing so and the sensor status will report 'Stopped - upgrading'.
Refresh the UI
It is recommended that following an upgrade that you do a hard refresh in your browser to make sure that you have the latest versions of all files loaded.
shift + cmd + R on MacOS or
Ctrl + F5 on Windows.
Check the log file
You can tail the latest Tomcat localhost log file to see where the upgrade has got up to. For example:
You can search the log for Data-migrator to find lines related to the data migration.
Check in PostgreSQL if the migration is still running
You can query
pg_stat_activity to see the active sessions and whether the migration process is still running or is blocked on something such as a lock.
Check the output to see if the migration is still prgressing or if it is blocked on something.
Rolling back to the previous version
If the data migration got part way through before failing then you may have both the old and new schema versions. You should clean up the new schema that was created so that you can retry the upgrade again. We provide a
drop_schema.sql script for this.
List the schema versions in the database
drop_schema.sql script BEFORE you restore the tar.gz from the previous version. This is so the newer schema is dropped and not the older one you want to roll back to.
To go back to the old version you can now run
./stop.sh to stop all processes and then extract the tar.gz file from the old version back over the top of the current installation and then run
Retrying a failed upgrade
Reach out to support via one of the contact options listed on https://www.dbmarlin.com/support