# Back up PostgreSQL

Back up the Syntho PostgreSQL databases. They store users, workspaces, and platform state.

{% hint style="info" %}
Syntho stores platform state in PostgreSQL databases. You can back them up using either an external PostgreSQL instance or the bundled PostgreSQL. Official PostgreSQL guidance: [Backup and Restore](https://www.postgresql.org/docs/current/backup.html).
{% endhint %}

Use your managed PostgreSQL backups.

{% stepper %}
{% step %}

#### Back up

1. Enable automated backups.
2. Enable the ability to restore to an earlier point in time (if your provider supports it).
3. Pick a retention period that matches your business needs.
4. Keep `syntho-core` and `syntho-backend` on the **same** PostgreSQL instance.
   {% endstep %}

{% step %}

#### Restore

1. Restore the PostgreSQL instance to the same point in time for both databases.
2. Start Syntho and validate login/workspaces.
   {% endstep %}
   {% endstepper %}

Use this when you prefer file-based backups. This works for external PostgreSQL and bundled PostgreSQL. You only need network access to the database. Official documentation [`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html).

{% stepper %}
{% step %}

#### Back up

Run `pg_dump` for **both** databases:

```bash
pg_dump -h <db-host> -p 5432 -U <db-user> -Fc -f syntho-backend.dump -d syntho-backend
pg_dump -h <db-host> -p 5432 -U <db-user> -Fc -f syntho-core.dump    -d syntho-core
```

<details>

<summary>What the <code>pg_dump</code> options mean</summary>

* `-h <db-host>`: PostgreSQL host name or Internet Protocol address.
* `-p 5432`: PostgreSQL port.
* `-U <db-user>`: database user name.
* `-F c` (shown as `-Fc`): output format “custom”. It is designed for `pg_restore`.
* `-f <file>`: output file path.
* `-d <database>`: database name to back up.

</details>

Store both dump files together (same run).
{% endstep %}

{% step %}

#### Restore

1. Stop Syntho.
2. Restore both databases:

```bash
pg_restore -h <db-host> -p 5432 -U <db-user> -d syntho-backend --clean syntho-backend.dump
pg_restore -h <db-host> -p 5432 -U <db-user> -d syntho-core    --clean syntho-core.dump
```

3. Start Syntho and validate.
   {% endstep %}
   {% endstepper %}

{% hint style="info" %}
`pg_dump` is consistent per database, but it does not automatically keep both databases in sync. If you need `syntho-backend` and `syntho-core` to represent the same moment, stop Syntho while dumping. Alternatively, use a backup method that restores the whole PostgreSQL instance to a single point in time.
{% endhint %}

#### Method 3: Persistent Volume Claim snapshots / Velero (in-cluster PostgreSQL)

Use this only if PostgreSQL runs **in-cluster**.

{% stepper %}
{% step %}
**Back up**

1. Identify the PostgreSQL Persistent Volume Claims:

   ```bash
   kubectl get pvc -n <namespace>
   ```

   Common names:

   * `database-data-1`
   * `database-data-2`
2. Back up both Persistent Volume Claims using one of:
   * Kubernetes `VolumeSnapshot`
   * **Velero** namespace backup
3. Keep the two backups **time-consistent**.
   {% endstep %}

{% step %}
**Restore**

1. Restore both Persistent Volume Claims (or their snapshots) to the same point in time.
2. Start Syntho and validate login/workspaces.
   {% endstep %}
   {% endstepper %}

{% hint style="warning" %}
In-cluster PostgreSQL is convenient for dev/test. For production, you can use either in-cluster PostgreSQL or external PostgreSQL. External PostgreSQL can simplify backups, restores, and upgrades, but it is optional.
{% endhint %}

### Switch Kubernetes (Helm) to external PostgreSQL

Optional. Use this when you want Syntho to connect to a PostgreSQL instance outside the cluster.

Use the same metadata database names listed above (`syntho-core` and `syntho-backend`).

{% stepper %}
{% step %}
**Provision PostgreSQL and create the databases**

Run this SQL as a PostgreSQL admin:

```sql
CREATE ROLE syntho WITH LOGIN PASSWORD '<strong-password>';

CREATE DATABASE "syntho-core" OWNER syntho;
CREATE DATABASE "syntho-backend" OWNER syntho;
```

Make sure Syntho can reach your PostgreSQL host:

1. PostgreSQL is reachable from the cluster / node network.
2. Firewall / security groups allow inbound traffic (usually `5432`).
3. TLS is enabled if required by your security policy.
   {% endstep %}

{% step %}
**Update `values.yaml` database configuration**

Update **both** database configuration blocks. Note that both core and backend have a dedicated database. Set the external host and align database names:

```yaml
core:
  db:
    host: <external-postgres-hostname-or-ip>
    port: 5432
    name: syntho-core
    username: syntho
    password: <strong-password>

backend:
  db:
    host: <external-postgres-hostname-or-ip>
    port: 5432
    name: syntho-backend
    user: syntho
    password: <strong-password>
```

{% endstep %}

{% step %}
**Disable the in-cluster PostgreSQL**

If you run PostgreSQL externally, do not deploy the chart’s PostgreSQL resources. In the values.yaml set

```yaml
core:
  database_enabled: false
backend:
  database_enabled: false
```

{% endstep %}

{% step %}
**Deploy and verify**

Apply your updated values:

```bash
helm upgrade --install <release-name> <chart> -f values.yaml
```

Verify pods/containers are healthy, UI is accessible, you can log in and workspaces are visible (or can be created).
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-kubernetes/back-up-postgresql.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.