> For the complete documentation index, see [llms.txt](https://help.sentinelsoftware.com/sentinel-help-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sentinelsoftware.com/sentinel-help-center/installation-and-updates/postgresql-backups/migrating-postgresql-db.md).

# Migrating PostgreSql DB

### Use this when migrating Sentinel to a new machine.

> <mark style="color:$danger;background-color:red;">⚠️ The PostgreSQL</mark> <mark style="color:$danger;background-color:red;"></mark><mark style="color:$danger;background-color:red;">**major version**</mark> <mark style="color:$danger;background-color:red;"></mark><mark style="color:$danger;background-color:red;">on the new server must match the original.</mark>\ <mark style="color:$danger;background-color:red;">(e.g. if the backup came from PG16, restore to PG16 — not PG17)</mark>

**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:

{% code overflow="wrap" %}

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

{% endcode %}

**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:

{% code overflow="wrap" %}

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

{% endcode %}

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

{% code overflow="wrap" %}

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

{% endcode %}

**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):

{% code overflow="wrap" %}

```
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]
```

{% endcode %}

> 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):

{% code overflow="wrap" %}

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

{% endcode %}

**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]
```

<br>