diff --git a/docs/persistence/README.md b/docs/persistence/README.md index 6b66d758..3235205a 100644 --- a/docs/persistence/README.md +++ b/docs/persistence/README.md @@ -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) diff --git a/docs/persistence/postgres/.pages b/docs/persistence/postgres/.pages index 6a060df0..84d7628d 100644 --- a/docs/persistence/postgres/.pages +++ b/docs/persistence/postgres/.pages @@ -2,5 +2,4 @@ title: Postgres nav: - README.md - 🎯 How-To: how-to -- 💡 Explanations: explanations - 📚 Reference: reference diff --git a/docs/persistence/postgres/README.md b/docs/persistence/postgres/README.md index 9629bb5f..d721fef8 100644 --- a/docs/persistence/postgres/README.md +++ b/docs/persistence/postgres/README.md @@ -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 @@ -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) diff --git a/docs/persistence/postgres/explanations/branches.md b/docs/persistence/postgres/explanations/branches.md deleted file mode 100644 index ffa19c3c..00000000 --- a/docs/persistence/postgres/explanations/branches.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -tags: [postgres, explanation] ---- - -# Postgres branches - -A Postgres can have several branches. Each branch is a separate, writable database with its own data and history. Branch names belong to one Postgres, so different databases can each have a branch named `main`. - -Every new Postgres starts with `main`. Restoring from backup creates another branch with the source branch's data and schema at the chosen point in time. The source stays unchanged. This lets you inspect restored data without replacing the database your workloads use. - -Branches are not Git branches. Writes on one branch do not appear on another, and switching branches does not merge data. - -## Active and pinned branches - -One branch is active for each Postgres. Workloads that omit `uses.postgres[].branch` follow this branch. Workloads with an explicit branch name are pinned to it and do not follow changes to the active branch. - -Creating a branch does not activate it. You can connect to an inactive branch with personal access or pin a workload to it without changing the active branch for other workloads. - -Activation is asynchronous. The requested branch (`spec.activeBranch`) and the observed active branch (`status.activeBranch`) can differ while the platform prepares the switch. Workload credentials and connections also take time to change. Existing connections can still point to the old branch until the workload reconnects. - -A pinned workload does not fall back to the active branch if its selected branch is unavailable or deleted. - -## Restore history - -Each branch builds its own backup history. A restored branch does not inherit the source branch's entire restore window. To recover to a time before the new branch's own backups began, use the original source branch while its backups are still available. - -Activating a branch does not combine its backup history with another branch's history. - -See [Restore a Postgres branch from backup](../how-to/restore-point-in-time.md) for restore and activation steps, or [Use Postgres in a workload](../how-to/use-in-workload.md#select-a-branch) to select a branch for one workload. diff --git a/docs/persistence/postgres/how-to/create.md b/docs/persistence/postgres/how-to/create.md index 2cdcf445..fba1d308 100644 --- a/docs/persistence/postgres/how-to/create.md +++ b/docs/persistence/postgres/how-to/create.md @@ -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). diff --git a/docs/persistence/postgres/how-to/delete.md b/docs/persistence/postgres/how-to/delete.md index f5aefe9f..9f7ee537 100644 --- a/docs/persistence/postgres/how-to/delete.md +++ b/docs/persistence/postgres/how-to/delete.md @@ -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: diff --git a/docs/persistence/postgres/how-to/manage.md b/docs/persistence/postgres/how-to/manage.md index f053cccb..c522edc1 100644 --- a/docs/persistence/postgres/how-to/manage.md +++ b/docs/persistence/postgres/how-to/manage.md @@ -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" diff --git a/docs/persistence/postgres/how-to/personal-access.md b/docs/persistence/postgres/how-to/personal-access.md index 990d1d58..ac60a014 100644 --- a/docs/persistence/postgres/how-to/personal-access.md +++ b/docs/persistence/postgres/how-to/personal-access.md @@ -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 --team --environment --reason "Investigating a database issue" diff --git a/docs/persistence/postgres/how-to/restore-point-in-time.md b/docs/persistence/postgres/how-to/restore-point-in-time.md index ee5a2421..050bd665 100644 --- a/docs/persistence/postgres/how-to/restore-point-in-time.md +++ b/docs/persistence/postgres/how-to/restore-point-in-time.md @@ -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 --ago 2h --team --environment + nais postgres clone --team --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 --at 2026-10-06T10:00:00Z --team --environment + nais postgres clone \ + --team \ + --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 ` 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 --team --environment + nais postgres get --team --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 --team --environment + ```yaml title="app.yaml" + spec: + uses: + 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. diff --git a/docs/persistence/postgres/how-to/use-in-workload.md b/docs/persistence/postgres/how-to/use-in-workload.md index 02e16ea1..85f6b637 100644 --- a/docs/persistence/postgres/how-to/use-in-workload.md +++ b/docs/persistence/postgres/how-to/use-in-workload.md @@ -15,28 +15,6 @@ spec: Replace `` 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: - branch: -``` - -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 --team --environment `. -3. Replace `` 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: diff --git a/docs/persistence/postgres/reference/.pages b/docs/persistence/postgres/reference/.pages index ab4dfe98..89d19788 100644 --- a/docs/persistence/postgres/reference/.pages +++ b/docs/persistence/postgres/reference/.pages @@ -1,4 +1,5 @@ nav: +- Cloning: cloning.md - Example YAML: example.md - Extensions: extensions.md - Personal access: personal-access.md diff --git a/docs/persistence/postgres/reference/cloning.md b/docs/persistence/postgres/reference/cloning.md new file mode 100644 index 00000000..f2ee2f90 --- /dev/null +++ b/docs/persistence/postgres/reference/cloning.md @@ -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 --team --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. diff --git a/docs/persistence/postgres/reference/example.md b/docs/persistence/postgres/reference/example.md index c137034c..41cba51c 100644 --- a/docs/persistence/postgres/reference/example.md +++ b/docs/persistence/postgres/reference/example.md @@ -23,7 +23,6 @@ version: v1 type: Postgres name: mypostgres spec: - activeBranch: main extensions: - name: postgis highAvailability: true diff --git a/docs/persistence/postgres/reference/extensions.md b/docs/persistence/postgres/reference/extensions.md index a8874399..44deb21b 100644 --- a/docs/persistence/postgres/reference/extensions.md +++ b/docs/persistence/postgres/reference/extensions.md @@ -4,26 +4,28 @@ tags: [postgres, reference] # Postgres extensions -The PostgreSQL 18 image used by Postgres includes the extensions below. Available extensions are not necessarily enabled in your database. `plpgsql` is installed by default; the platform also configures `pgaudit` and `pg_stat_statements`. +Postgres supports extensions bundled with PostgreSQL and extensions mounted from platform image catalogs. Available extensions are not necessarily enabled in your database. `plpgsql` is installed by default; the platform manages `pgaudit` and `pg_stat_statements`. ## Additional extensions | Extension name | Purpose | | --- | --- | | `pgaudit` | SQL audit logging, configured by the platform | +| `pg_stat_statements` | Query statistics, configured by the platform | +| `postgis` | Spatial data and queries, mounted from the image catalog | +| `timescaledb` | Time-series data, mounted from the image catalog and preloaded by the platform | | `vector` | Vector storage and similarity search (pgvector) | -PostGIS is not included in the current image. The extension name for pgvector is `vector`, not `pgvector`. +The extension names are `vector` for pgvector and `timescaledb` for TimescaleDB, not `pgvector` or `timescaledb-oss`. The platform-managed extensions `pgaudit` and `pg_stat_statements` cannot be requested in `spec.extensions`. -## PostgreSQL bundled extensions +## Supported bundled extensions | Area | Extension names | | --- | --- | | Indexes and search | `bloom`, `btree_gin`, `btree_gist`, `pg_trgm` | -| Data types and text | `citext`, `cube`, `dict_int`, `dict_xsyn`, `earthdistance`, `fuzzystrmatch`, `hstore`, `intarray`, `isn`, `ltree`, `seg`, `unaccent` | -| Functions and utilities | `autoinc`, `insert_username`, `intagg`, `lo`, `moddatetime`, `pgcrypto`, `refint`, `tablefunc`, `tcn`, `uuid-ossp`, `xml2` | -| External data | `dblink`, `file_fdw`, `postgres_fdw` | -| Inspection and maintenance | `amcheck`, `pageinspect`, `pg_buffercache`, `pg_freespacemap`, `pg_logicalinspect`, `pg_prewarm`, `pg_stat_statements`, `pg_surgery`, `pg_visibility`, `pg_walinspect`, `pgrowlocks`, `pgstattuple`, `sslinfo` | +| Data types and text | `citext`, `cube`, `earthdistance`, `fuzzystrmatch`, `hstore`, `intarray`, `isn`, `ltree`, `seg`, `unaccent` | +| Functions and utilities | `lo`, `pgcrypto`, `tablefunc`, `tcn` | +| Inspection and maintenance | `amcheck`, `pageinspect`, `pg_buffercache`, `pg_freespacemap`, `pg_logicalinspect`, `pg_prewarm`, `pg_visibility`, `pg_walinspect`, `pgrowlocks`, `pgstattuple`, `sslinfo` | | Sampling | `tsm_system_rows`, `tsm_system_time` | | Procedural language | `plpgsql` | @@ -39,7 +41,9 @@ spec: - name: vector ``` -The CLI create/update commands and the Console configuration form do not expose extension settings. Use the Postgres manifest for declarative configuration. +Console exposes extension selection when creating or editing a database. When cloning, source extensions are kept and additional available extensions can be selected. The CLI create, update and clone commands do not expose extension selection; clone inherits the source's extensions. Declarative configuration uses the Postgres manifest. + +The [manifest reference](spec.md#extensionsname) lists the accepted extension names. Console lists the extensions available in the selected environment. PostgreSQL exposes the extensions available in the running image through `pg_available_extensions`: diff --git a/docs/persistence/postgres/reference/personal-access.md b/docs/persistence/postgres/reference/personal-access.md index 0f636d37..aa270edc 100644 --- a/docs/persistence/postgres/reference/personal-access.md +++ b/docs/persistence/postgres/reference/personal-access.md @@ -30,7 +30,8 @@ These settings log: | --- | --- | | `read` | Read data (default) | | `write` | Change data | -| `admin` | Change database objects | +| `admin` | Application database owner privileges | +| `maintain` | Instance monitoring and maintenance through `pg_monitor` and `pg_maintain` | `--access-level ` selects the access level. @@ -38,6 +39,5 @@ These settings log: | Flag | Description | | --- | --- | -| `--reason` | Required. Reason for the access, minimum 10 characters | +| `--reason` | Reason for the access, minimum 10 characters. Prompted interactively if omitted | | `--ttl` | How long the access lasts. Default 30 minutes, maximum 1 hour | -| `--branch` | Branch to connect to. Defaults to the active branch | diff --git a/docs/persistence/postgres/reference/spec.md b/docs/persistence/postgres/reference/spec.md index 364fd26c..b5c1ebad 100644 --- a/docs/persistence/postgres/reference/spec.md +++ b/docs/persistence/postgres/reference/spec.md @@ -21,20 +21,7 @@ tags: [postgres, reference] This feature is an alpha feature, and is subject to API change, instability or removal. See the [main Postgres page](../README.md) for more information. -This document describes all possible configuration values in the `Postgres` spec, commonly known as the `postgres.yaml` file. A `Postgres` is a logical database: pgrator creates its default `main` branch as a separate CNPG cluster. `spec.activeBranch` requests a local branch name; `status.activeBranch` is the observed selection. A requested branch must have an initialized, Ready, non-terminating CNPG cluster before pgrator updates observed status. This check is not an atomic cutover guarantee; verify workload connections when switching branches. - -## activeBranch -ActiveBranch selects the local branch name within this Postgres for normal workloads. -When omitted, pgrator retains the current active branch. - -Type: `string`
-Required: `false`
- -??? example - ``` yaml - spec: - activeBranch: main - ``` +This document describes configuration values in the `Postgres` spec, commonly known as the `postgres.yaml` file. Each `Postgres` is a separate database. ## extensions Extensions to activate in the application database. Removing an entry drops the extension @@ -187,4 +174,3 @@ Pattern: `^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE] resources: memory: 512Mi ``` -