Upgrading Traccar: Restore Database Backup (H2) | Issue with H2 Version + Fix | Linux

Summary

• There is no documentation for database restore following upgrade. I ran into issues with my attempt at database restore, while using the default H2 database and moving from Traccar 5.0 -> 6.5
• I found a fix for these issues and am sharing for anyone unlucky enough to run into the same issue.
• Hopefully, the linux commands will also be of use to less experienced server admins, even if this issue is not encountered.

Background

Upgrading from Traccar 5.0 -> 6.5 on a linux machine. Default H2 database is in use. I encountered issue when restoring the database. As there is no relevant documentation for DB restoration, and as H2 is a Traccar default, I am documenting the steps I've taken to resolve it here for others to find.

Reproducing the issue - documented steps

Following the somewhat high-level steps provided at https://www.traccar.org/upgrading-traccar/ and referencing https://www.traccar.org/linux/.

sudo systemctl stop traccar

1- Make a database backup
2- Backup the traccar.xml config file (if changed)
3- Backup the media folder (if present)
sudo cp -r /opt/traccar /backup/traccar
(You might as well combine these steps with a full backup, if space on your machine allows. Then you avoid accidental loss of anything.)

4- Remove the old version of Traccar
sudo systemctl disable traccar
sudo rm /etc/systemd/system/traccar.service
sudo systemctl daemon-reload
sudo rm -rf /opt/traccar

5- Install the new version of Traccar
cd /tmp
wget https://github.com/traccar/traccar/releases/download/v6.5/traccar-linux-64-6.5.zip
unzip traccar-linux-64-6.5.zip
chmod +x traccar.run
sudo ./traccar.run

6- Restore the media folder (if present)
7- Restore the traccar.xml config file (if changed); Do not copy default.xml from old versions
sudo nano /opt/traccar/conf/traccar.xml (add any custom configs from /backup/traccar/conf/traccar.xml)

8- Start the service
sudo systemctl start traccar

Reproducing the issue - undocumented steps

By following the documentation exactly, we now have v6.5 running successfully, and a backup of the database in a different location. Of course, we still need to restore the original database content.

The obvious solution is to copy the content back in:
sudo systemctl stop traccar
sudo cp /backup/traccar/data/database.trace.db /opt/traccar/data/
sudo cp /backup/traccar/data/database.mv.db /opt/traccar/data/
sudo systemctl start traccar

Starting the server now results in errors in the server logs.

2024-09-19 11:10:32 ERROR: Main method error - The write format 2 is smaller than the supported format 3 [2.3.232/5] - MVStoreException (... < DatabaseModule:80 < <gener:-1 < *:-1 < ... < MainModule:138 < <gener:-1 < ...)

Explanation

Why it happens: the H2 database format changed between versions used in Traccar 5.0 and 6.5. Directly copying the old database files results in a format conflict.

Solution

Export the old database to an SQL script using the old H2 version and import it into the new database using the new H2 version.

Export the old database file

Export the old database .mv.db file to an SQL script using the old h2 .jar file (ls /opt/traccar/lib/h2*.jar):
java -cp /backup/traccar/lib/h2-2.0.206.jar org.h2.tools.Script -url jdbc:h2:/backup/traccar/data/database -script /tmp/backup.sql

Stop the server and remove empty db files

Stop server and remove the new database files:
sudo systemctl stop traccar
sudo rm /opt/traccar/data/database.mv.db
sudo rm /opt/traccar/data/database.trace.db

Run the created SQL script

Run the script using the new h2 .jar file (ls /opt/traccar/lib/h2*.jar). Replace the default user/password with those used by your traccar server, if necessary:
sudo java -cp /opt/traccar/lib/h2-2.3.232.jar org.h2.tools.RunScript -url jdbc:h2:/opt/traccar/data/database -script /tmp/backup.sql -user sa -password ""

Restart the server and validate the data.

sudo systemctl start traccar

Final Remarks

Welcome any suggestions or improvements on the steps I have used above. Perhaps some of this thread could be recycled into a more detailed 'How to upgrade Traccar on Linux' docs page.

Congratulations, or maybe a bash script to accomplish the task.

Ideally you should migrate away from H2. It is not intended for production use. It is a default so that people can easily try out Traccar. But for production we always recommend a proper SQL database, like MySQL for example.

Thank you. We are still in dev for the moment, but I will implement this.

its best to use mysql server instead of H2 DB. It not difficult to setup, And very easy to backup and restore.