Migrating PostgreSql DB

Migrate an existing PostgreSQL db to another environme

Use this when migrating Sentinel to a new machine.

⚠️ The PostgreSQL major version on the new server must match the original. (e.g. if the backup came from PG16, restore to PG16 — not PG17)

Step 1. Install PostgreSQL on the new server (same major version as the source):

sudo apt install postgresql-16    # adjust version number to match source

Step 2. Find your service name and PGDATA path on the new server:

sudo systemctl list-units --type=service | grep -i postgressudo -u postgres psql -c "SHOW data_directory;"

Step 3. Stop PostgreSQL on the new server:

sudo systemctl stop [YOUR_POSTGRES_SERVICE]

Step 4. Transfer the backup files from the source server:

scp -r /data/pg_backup/2025-07-17/ newserver:/data/pg_backup/

Or copy from your off-site storage to the new server.

Step 5. Clear the data directory on the new server:

sudo -u postgres rm -rf /your/pgdata/folder/*

Step 6. Extract the base backup:

sudo -u postgres tar -xzf /data/pg_backup/2025-07-17/base.tar.gz \  -C /your/pgdata/folder/

Step 7. Extract the WAL files into the pg_wal subfolder:

sudo -u postgres tar -xzf /data/pg_backup/2025-07-17/pg_wal.tar.gz \  -C /your/pgdata/folder/pg_wal/

Step 8. Remove the standby marker file:

sudo -u postgres rm -f /your/pgdata/folder/standby.signal

Step 9. Fix permissions:

sudo chown -R postgres:postgres /your/pgdata/folder/sudo chmod 700 /your/pgdata/folder/

Step 10. Start PostgreSQL on the new server:

sudo systemctl start [YOUR_POSTGRES_SERVICE]

Step 11. Copy the Sentinel JAR to the new server:

scp /apps/sentinel/sentinel.jar newserver:/apps/sentinel/

Step 12. Configure Sentinel's environment variables on the new server. Edit Sentinel's environment config (commonly /etc/sentinel/env or a systemd override):

DB_HOST=localhostDB_PORT=5432DB_NAME=heliumdbDB_USER=postgresDB_PASSWORD=[your database password]JWT_SECRET=[copy from the original server, or set a new one]

If you set a new JWT_SECRET, all users will be logged out on first login after the migration. Everything else continues to work normally.

Step 13. Copy SAML certificates to the new server (only if you use SSO):

scp /apps/sentinel/saml-cert.pem newserver:/apps/sentinel/scp /apps/sentinel/saml-key.pem  newserver:/apps/sentinel/

Step 14. Start Sentinel:

sudo systemctl start sentinel

Step 15. Log into Sentinel and confirm users, reports, and history are present.

Step 16 — Only if the domain name changed: The license key is tied to your domain. If the new server uses a different URL, re-register before or after starting Sentinel:

java -jar /apps/sentinel/sentinel.jar register --license-key [YOUR_KEY]