> ## Documentation Index
> Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Restore a Cloud SQL Database

> Run and record point-in-time restore tests of a Cloud SQL for PostgreSQL instance with the gcp-postgres-restore blueprint.

The `gcp-postgres-restore` marketplace blueprint restores a Cloud SQL for PostgreSQL instance to a point in time and writes a JSON record of every run to a Cloud Storage bucket. Use it to run restore tests and keep evidence of them.

Each run restores the source into a new instance named `<source>-restore-<random>` and checks it. The source instance is only read.

A run starts only when you trigger the job. There is no schedule, and a failed run is never retried.

> [!NOTE]
>
> The blueprint works only in GCP environments. In AWS and Azure environments it creates nothing.

## Prerequisites

* A GCP environment.
* A Cloud SQL for PostgreSQL instance in the environment's project, with automated backups and point-in-time recovery turned on. The [Postgres marketplace blueprint](https://ryvn.ai/docs/configure/marketplace-blueprints.md) turns both on by default and keeps 7 days of transaction logs, so you can restore to any point in the last 7 days.

## Install the blueprint

```yaml theme={null}
# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: BlueprintInstallation
metadata:
  name: postgres-restore
spec:
  environment: production
  blueprint: ryvn.app/gcp-postgres-restore
  inputs:
  - name: sourceInstance
    valueFromOutput:
      blueprintInstallation: postgres
      name: instanceName
  - name: checkDatabases
    value: app
```

`sourceInstance` is the name of the instance to restore. Take it from the Postgres installation's `instanceName` output. `checkDatabases` is a comma-separated list of databases that must exist in the restored copy. Leave it empty to skip that check. Leave `accessUntil` unset: the job has no Cloud SQL admin access until you open it for a run.

The installation creates:

* A job installation with the same name, in the `compliance` namespace.
* An evidence bucket named `postgres-restore-evidence-<random>`, with object versioning and deletion protection. The installation's `evidenceBucketName` output holds the full name.
* Workload Identity access for the job. It gets Cloud SQL admin only while `accessUntil` is set and in the future, through an IAM condition that also limits it to the source instance and instances named `<source>-restore-*`. It always has read-only Cloud SQL access to the project so it can follow operations. On the evidence bucket it can create objects but not read, replace or delete them.

## Run a restore test

1. Open access for the run: set `accessUntil` on the installation to a UTC time about 2 hours after you deploy it, and deploy it. The job only needs access to start the restore; once Cloud SQL accepts the request, the restore finishes even if access lapses. Two hours leaves time for the deploy, for the grant to apply, which usually takes a few minutes, and for a retry or two. If the change waits for review before it deploys, count from when it will deploy, or update the time just before. To get the time 2 hours from now:

   ```bash theme={null}
   date -u -v+2H +%Y-%m-%dT%H:%M:%SZ          # macOS
   date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ  # Linux
   ```

2. Trigger the job. Open the `postgres-restore` installation and click **Run Now** in the **Actions** menu, or run:

   ```bash theme={null}
   ryvn command trigger-job --environment production --installation postgres-restore
   ```

   With `restoreTime` empty, the run restores to the latest recoverable time. To restore to an earlier point, set `restoreTime` on the installation first, in UTC and ending in `Z`, for example `2026-01-01T12:00:00Z`.

3. Wait for the job to finish. On a small instance the restore takes 20 to 40 minutes. The job stops after 55 minutes.

4. Read the run's record:

   ```bash theme={null}
   gcloud storage ls gs://<evidence-bucket>/runs/<source>/
   gcloud storage cat gs://<evidence-bucket>/runs/<source>/<runId>.json
   ```

5. Check the data, if you need more than the job's checks. The job confirms only that the copy is running and has the databases in `checkDatabases`; it doesn't read your data. The copy has the source's databases, users and passwords as of `restoreTime`, at its own IP addresses.

6. Delete the copy with the command in the record's `cleanup` field. The copy keeps running, and costs about as much as the source, until you delete it.

7. Clear `accessUntil` and deploy, which removes the grant. It grants nothing after `accessUntil` either way.

If the run fails at `restore` with a permission error right after you deployed `accessUntil`, the grant hasn't applied yet. Wait a few minutes and trigger the job again.

## The run record

The job writes one record per run to `runs/<source>/<runId>.json`, including runs that fail. If the record can't be written, the run fails.

| Field | Meaning |
| - | - |
| `runId` | When the run started, plus a random suffix. The copy's name ends in the same suffix. |
| `restoreTime` | The point restored to, in UTC with nanoseconds |
| `accessUntil` | When the job's access for the run ended |
| `latestRecoveryTime` | The latest point the source could be restored to when the run started |
| `restoredInstance` | The copy's name |
| `restoreSeconds` | How long the restore into the copy took |
| `restoredInstanceState`, `restoredDatabases` | The copy's state and databases after the restore |
| `cleanup` | The command that deletes the copy. Empty if no copy was started. |
| `startedAt`, `finishedAt` | When the run started and ended |
| `outcome`, `failedStep`, `exitCode` | `succeeded` or `failed`, and for a failed run the step it stopped at. Exit code 2 means the settings were rejected before anything changed, including a missing or past `accessUntil`. |

## Limits

* GCP only.
* A run stops after 55 minutes. A large instance can take longer than that to restore.
* `restoreTime` must fall inside the source's point-in-time recovery window.
* Copies keep running until you delete them.
* A run can start a restore only before `accessUntil`.
* The evidence bucket has no retention lock. Anyone with Cloud Storage admin rights in the project can delete records.
