Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/persistence/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ nature.

## Postgres

Postgres is a managed PostgreSQL database for your workloads. It is in preview and supports self-service creation and point-in-time recovery into a separate branch.
Postgres is a managed PostgreSQL database for your workloads. It is in preview and supports self-service creation and cloning from backups, including point-in-time restore to a separate database.

[:bulb: Learn more about Postgres](postgres/README.md)

Expand Down
1 change: 0 additions & 1 deletion docs/persistence/postgres/.pages
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,4 @@ title: Postgres
nav:
- README.md
- 🎯 How-To: how-to
- 💡 Explanations: explanations
- 📚 Reference: reference
8 changes: 4 additions & 4 deletions docs/persistence/postgres/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Postgres gives your Applications and Jobs a managed PostgreSQL database. You can

Postgres automatically creates and manages credentials for your workloads. You can also get short-lived personal access from the Nais CLI when you need to inspect the database.

Postgres keeps backups continuously. When you need an older copy of the data, restore it to a new branch and inspect it without affecting the workloads that use your current database.
Postgres keeps backups continuously. You can clone a database from its backups, either from the latest available point or from a specific time. The clone is a separate database that you can inspect without affecting existing workloads.

## Next steps

Expand All @@ -23,14 +23,14 @@ Postgres keeps backups continuously. When you need an older copy of the data, re

[:dart: Connect as a personal user](how-to/personal-access.md)

[:dart: Restore a database to a point in time](how-to/restore-point-in-time.md)
[:dart: Clone or restore a database](how-to/restore-point-in-time.md)

[:dart: Delete Postgres](how-to/delete.md)

[:bulb: Postgres branches](explanations/branches.md)

[:books: Available extensions](reference/extensions.md)

[:books: Postgres cloning](reference/cloning.md)

[:books: Postgres workload credentials](reference/workload-credentials.md)

[:books: Postgres personal access](reference/personal-access.md)
Expand Down
29 changes: 0 additions & 29 deletions docs/persistence/postgres/explanations/branches.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/persistence/postgres/how-to/create.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Create a Postgres database.

1. Open your team in [Nais Console](https://console.nais.io) and select **Postgres**.
2. Select **Create Postgres**.
3. Fill in the form and select **Create Postgres**.
3. Select **Empty database**, fill in the form and select **Create Postgres**. To start from an existing database's backups instead, see [Clone or restore Postgres](restore-point-in-time.md).

To change settings later, see [Manage Postgres](manage.md?tab=console).

Expand Down
4 changes: 3 additions & 1 deletion docs/persistence/postgres/how-to/delete.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,12 @@ tags: [postgres, how-to]

# Delete Postgres

Deleting a Postgres irreversibly removes the whole instance with all its branches and data.
Deleting a Postgres irreversibly removes the database, its data and its backups.

Remove `uses.postgres` from all workloads that reference the database and deploy them. If the Postgres manifest is managed in Git, delete the manifest file so the next apply does not recreate the database.

Wait for any [clones](restore-point-in-time.md) that depend on the database to complete. Deletion is blocked while workloads, bindings or unfinished clones still reference it.

=== "CLI"

Delete the Postgres:
Expand Down
2 changes: 1 addition & 1 deletion docs/persistence/postgres/how-to/manage.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Change CPU, memory, disk size or high availability. PostgreSQL 18 is the only su
For a Postgres managed in Git, update the manifest. A later `nais apply` can overwrite changes made through the CLI or Console.

!!! warning "Disk size"
It is not possible to decrease the disk size, only increase it.
It is not possible to decrease the disk size, only increase it.

=== "GitOps"

Expand Down
4 changes: 2 additions & 2 deletions docs/persistence/postgres/how-to/personal-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ Use this how-to to connect to a Postgres database with your personal user, for a
- You have the [Nais CLI :octicons-link-external-16:](https://cli.nais.io/) installed and are logged in with `nais login --nais`
- `psql` on `PATH`

The CLI grants temporary personal access: read-only access to the active branch for 30 minutes by default. For access levels, lifetime and branch selection, see [Postgres personal access](../reference/personal-access.md).
The CLI grants temporary personal access: read-only access to the database for 30 minutes by default. For access levels and lifetime, see [Postgres personal access](../reference/personal-access.md).

## Open `psql`

Connect to the active branch:
Connect to the database:

```bash
nais postgres psql <POSTGRES-NAME> --team <TEAM> --environment <ENVIRONMENT> --reason "Investigating a database issue"
Expand Down
73 changes: 37 additions & 36 deletions docs/persistence/postgres/how-to/restore-point-in-time.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,70 +2,71 @@
tags: [postgres, how-to]
---

# Restore a Postgres branch from backup
# Clone or restore Postgres

The restore creates a new, writable branch from a point in time covered by the source branch's backups. It does not change your workloads.
Clone a Postgres database from its backups, either from the latest available point or from a specific time. The clone is a new, writable database in the same team and environment. It does not change the source database or move your workloads.

## Create the restored branch
## Clone the database

=== "CLI"

Create a branch from a relative recovery point:
Clone from the latest available point, about 10 minutes ago:

```bash
nais postgres branch create <POSTGRES-NAME> <NEW-BRANCH> --ago 2h --team <TEAM> --environment <ENVIRONMENT>
nais postgres clone <SOURCE-POSTGRES-NAME> <NEW-POSTGRES-NAME> --team <TEAM> --environment <ENVIRONMENT>
```

`--ago` accepts durations such as `30m`, `2h` or `1h30m`. For an exact recovery point, use `--at` instead:
To restore to a specific time instead, add `--at`:

```bash
nais postgres branch create <POSTGRES-NAME> <NEW-BRANCH> --at 2026-10-06T10:00:00Z --team <TEAM> --environment <ENVIRONMENT>
nais postgres clone <SOURCE-POSTGRES-NAME> <NEW-POSTGRES-NAME> \
--team <TEAM> \
--environment <ENVIRONMENT> \
--at "2026-11-16 12:00"
```

`--at` takes a UTC timestamp in RFC3339 format with whole seconds; `Z` means UTC.
Times without an offset use your computer's local time zone. Use RFC3339 with `Z` or an explicit offset to specify an absolute time, for example `2026-11-16T12:00:00Z`.

The restore uses the active branch as source. Add `--from <BRANCH>` to restore from a different branch.
Review the configuration and confirm. To override the source's resource or high-availability settings, see the [clone flags](../reference/cloning.md#cli-flags).

Wait until the new branch shows `Ready`:
Check progress with:

```bash
nais postgres branch list <POSTGRES-NAME> --team <TEAM> --environment <ENVIRONMENT>
nais postgres get <NEW-POSTGRES-NAME> --team <TEAM> --environment <ENVIRONMENT>
```

=== "Console"
Wait until **Clone status** is **Completed** and **Status** is **Ready**.

1. Open your team in [Nais Console](https://console.nais.io) and select **Postgres**.
2. Select the database in the correct environment and open **Branches**.
3. Select **Create branch**.
4. Enter a new branch name and select the source branch.
5. Set **Restore to (UTC)** to a time within the source branch's available recovery window.
6. Select **Create branch** and wait until it is available. The branch list updates automatically.
=== "Console"

The new branch does not become active automatically.
1. Open your team in [Nais Console :octicons-link-external-16:](https://console.nais.io) and select **Postgres**.
2. Select **Create Postgres**, then the **Clone existing database** tab.
3. Select the environment and source database, and enter a name for the new database.
4. Leave **Specify time** closed to use the latest available point, about 10 minutes ago. To restore to a specific time, open it and enter a time in your browser's local time zone, within the available recovery window.
5. Optionally, open **Customize resources** to change CPU, memory, disk size or high availability. Keep the disk at least as large as the source's.
6. Select **Clone database**. Follow the clone status on the new database's page and wait until cloning completes and the database is ready.

Optionally, inspect the restored data by [connecting as a personal user](personal-access.md) with `psql` or the proxy. This does not affect workload traffic.
If the source has no available recovery window, wait for its backups before trying again. If the default clone point is too early for a newly created source, wait or specify a time within its recovery window.

## Switch workloads to the restored branch
Do not connect workloads to a failed clone. See [Postgres cloning](../reference/cloning.md) for inherited settings, time limits and completion status.

To move only one workload, [pin it to the restored branch](use-in-workload.md#select-a-branch) instead of activating the branch for all workloads that follow the active branch.
Inspect the cloned data by [connecting as a personal user](personal-access.md) with the new database's name. This does not affect workload traffic.

When the restored data is correct, pause writes from workloads that will move and request activation:
## Move workloads to the clone

=== "CLI"
1. Pause writes from the workloads you want to move.
2. Change `uses.postgres[].name` in each workload's manifest to the new database's name:

```bash
nais postgres branch activate <POSTGRES-NAME> <NEW-BRANCH> --team <TEAM> --environment <ENVIRONMENT>
```yaml title="app.yaml"
spec:
uses:
postgres:
- name: <NEW-POSTGRES-NAME>
```

Run `branch list` again until the new branch shows `Ready` and is marked active.

=== "Console"

1. Open **Branches** on the database's page.
2. Open the restored branch's action menu and select **Use as active**.
3. Confirm with **Use as active**.
4. Wait until the branch is marked active.
Keep any existing `role` and `envPrefix` settings. See [Use Postgres in a workload](use-in-workload.md).

Activation is asynchronous and does not move workloads pinned to another branch.
3. Deploy the changed workloads and verify that they connect to the clone and use the expected data.
4. Resume writes when verification is complete.

Verify the workload's connection and data before allowing writes again. Existing database connections may still point to the old branch; restart or reconnect workloads as needed. Do not delete the old branch until workloads are using the new branch and you have verified the data.
Do not delete the source database until cloning has completed, you have verified the data and no workloads still use it.
22 changes: 0 additions & 22 deletions docs/persistence/postgres/how-to/use-in-workload.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,28 +15,6 @@ spec:

Replace `<POSTGRES-NAME>` with the database name you used in [Create Postgres](create.md), then deploy the workload as usual. If you do not already have deployment set up, see [Build and deploy with GitHub Actions](../../../build/how-to/build-and-deploy.md).

## Select a branch

Without a `branch` field, the workload follows the database's active branch. A new Postgres starts with `main` active.

To pin the workload to an existing branch, add its name:

```yaml title="app.yaml"
spec:
uses:
postgres:
- name: <POSTGRES-NAME>
branch: <BRANCH-NAME>
```

1. [Create a branch from backup](restore-point-in-time.md) if the branch does not exist yet.
2. Check that it is ready in **Branches** on the database's Console page, or with `nais postgres branch list <POSTGRES-NAME> --team <TEAM> --environment <ENVIRONMENT>`.
3. Replace `<BRANCH-NAME>` with the branch name and deploy the workload.

A pinned workload stays on that branch when the database's active branch changes. If the selected branch is unavailable or deleted, the workload does not fall back to another branch. Omit `branch` to follow the active branch again, then redeploy.

See [Postgres branches](../explanations/branches.md) for how branches and activation work.

## Credentials

The default `admin` role is intended for workloads that run schema migrations. It provides two sets of credentials:
Expand Down
1 change: 1 addition & 0 deletions docs/persistence/postgres/reference/.pages
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
nav:
- Cloning: cloning.md
- Example YAML: example.md
- Extensions: extensions.md
- Personal access: personal-access.md
Expand Down
57 changes: 57 additions & 0 deletions docs/persistence/postgres/reference/cloning.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
tags: [postgres, reference]
---

# Postgres cloning

Cloning creates a separate, writable Postgres database from a source database's backups. Point-in-time restore uses the same operation with an explicit target time. The source remains unchanged, and no workloads move automatically.

For steps, see [Clone or restore Postgres](../how-to/restore-point-in-time.md).

## Source and configuration

The clone has a different name from its source and belongs to the same team and environment.

| Setting | Default | Changes allowed at creation |
| --- | --- | --- |
| PostgreSQL major version | Source's version | None |
| Extensions | Source's extensions | Console allows adding available extensions, but not removing source extensions. CLI inherits the source's extensions |
| High availability | Source's setting | Enable or disable |
| CPU and memory | Source's configured requests | Override independently |
| Disk size | Source's configured size | Increase, but not decrease |

The source's configuration is read when the clone is created, not from the selected point in time. Later changes to the source do not update the clone.

## Target time

Without an explicit time, CLI and Console request a point 10 minutes before submission. This buffer accounts for recent write-ahead logs that may not yet be archived. The clone does not include the source's most recent writes.

An explicit time must fall within the source's available recovery window and must not be in the future. A source without a recovery window cannot be cloned yet. An accepted target time does not guarantee success: cloning can still fail if required backup data or write-ahead logs are unavailable.

| Client | Time format |
| --- | --- |
| CLI `--at` | Local time, such as `2026-11-16 12:00` or `2026-11-16T12:00:00`. RFC3339 with `Z` or an explicit offset is also accepted. Whole-second precision only |
| Console **Specify time** | Date and time in the browser's local time zone, with minute precision. Empty or collapsed means the default clone point |

Local times skipped by a daylight-saving clock change are rejected. A repeated local time selects the earlier occurrence. CLI timestamps with an explicit offset are unambiguous.

## CLI flags

Command: `nais postgres clone <SOURCE> <NEW-NAME> --team <TEAM> --environment <ENVIRONMENT>`

| Flag | Description |
| --- | --- |
| `--at` | Target time. Omitted means about 10 minutes ago |
| `--high-availability true\|false` | Override the source's high-availability setting |
| `--cpu` | Override the source's CPU request, for example `500m` |
| `--memory` | Override the source's memory request, for example `2Gi` |
| `--disk-size` | Override the source's disk size, for example `50Gi`. Must not be smaller than the source's |
| `--yes`, `-y` | Skip the confirmation prompt |

## Completion status

Cloning runs asynchronously. `nais postgres get` reports **Clone status** separately from the database's **Status**. A database marked **Ready** does not by itself mean cloning is complete.

**Completed** means the clone is independent of the source and has its own backup. Source deletion is blocked while dependent clones still need its backups. The clone builds its own backup history; the source's earlier recovery window does not become part of it.

**Failed** includes the failure message. A failed clone is not a usable restored database.
1 change: 0 additions & 1 deletion docs/persistence/postgres/reference/example.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ version: v1
type: Postgres
name: mypostgres
spec:
activeBranch: main
extensions:
- name: postgis
highAvailability: true
Expand Down
Loading
Loading