Skip to main content
Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

​
Goal

Get back to the exact state your database was in before a migration or a bulk change, much faster than a full restore.

​
Prerequisites

  • A Dedicated database that is running
  • A database on a server that offers fast restore points. See Where they are offered.
  • Write access to the database

​
Workflow

1
Check that your database offers them: stackshift database restore-points DATABASE (GET /api/v1/databases/{id}/restore-points). eligibility.available must be true.
2
Before the risky change, take one with stackshift database restore-point-create DATABASE (POST /api/v1/databases/{id}/restore-points). Add a name of up to 100 characters if you like.
3
Wait until its status is available.
4
Run your change. If it goes wrong, roll back with stackshift database restore-point-rollback DATABASE POINT --data '{"confirm":"DATABASE_NAME"}' (POST /api/v1/databases/{id}/restore-points/{pointID}/rollback), using the database’s exact name.
5
Wait until the database status returns to running, then check your data.

​
Where they are offered

Fast restore points need your database to run in our high-performance location. When it doesn’t, eligibility.available is false and eligibility.reason says why:
  • “Fast restore points are available for databases in our high-performance location.” Your database runs somewhere else.
  • “Fast restore points are not available yet.” The feature isn’t switched on yet, or the database is a Starter database.
  • “Fast restore points become available once your database is running.” Wait until the database has started.
  • There is no separate charge for them on the servers that offer them. Restore points take space on the server, so they are limited as described below.

​
Automatic restore points

  • Three schedules are on by default: daily (keeps 7), weekly (keeps 4) and monthly (keeps 3).
  • They are taken at your maintenance window time: daily every day, weekly on your window’s day and monthly on the 1st, one at a time, after a checkpoint.
  • Points beyond keep are removed. Turning a schedule off takes nothing new, and its existing points stay until you delete them.
  • Change a schedule with stackshift database restore-point-schedules DATABASE --data '{"daily":{"enabled":true,"keep":10}}' (PUT /api/v1/databases/{id}/restore-points/schedules). keep is 1 to 30.

​
Your own restore points

  • You can keep up to 10 of your own. Delete one to take another.
  • The database must be running to take one.
  • Delete one with stackshift database restore-point-delete DATABASE POINT (DELETE /api/v1/databases/{id}/restore-points/{pointID}). A point that is still being taken, already being deleted or used by a rollback can’t be deleted.
  • A restore point is not a backup. It lives on the same server as the database. Keep your regular backups and snapshots too.

​
What a rollback does

  • Takes a fresh full backup first, as a safety net. If that backup doesn’t finish, nothing is changed and the database keeps running.
  • Removes the standby and read replicas.
  • Stops the database and swaps its storage for a copy of the restore point. The restore point itself is kept.
  • Starts the database, starts a new backup history with a full backup, then rebuilds the standby and read replicas from it.
  • The database is offline while it switches, and its status is rolling_back the whole time. Your old storage is kept for 24 hours.
  • Everything written after the restore point is gone. If you might want any of it, take a snapshot or copy the data out before you roll back.
  • stackshift database restore-points DATABASE shows the latest rollback and its step: backing_up, removing_members, stopping, swapping, starting, configuring_backups, full_backup, completed or failed.
  • If a rollback fails before anything was changed, the database goes back to running with an error message. If it can’t start after the swap, its status is failed and we are alerted.

​
When the server runs low on space

Restore points take space on the server. When it gets short, we remove the oldest restore points first, and every database always keeps its newest one. You get a warning event when points are removed.

​
Availability

Dedicated databases are rolling out. If Create doesn’t offer Dedicated, it isn’t switched on for your account yet, and the API answers 403.

​
Expected result

The database holds the data it had when the restore point was taken, and any standby and read replicas are rebuilt from it.

​
Common failures

  • 400 when rolling back: confirm must be exactly the database name.
  • 409 when taking a restore point: the database isn’t running, isn’t eligible, or already has 10 of your own.
  • 409 when rolling back: the database isn’t running, the point isn’t available yet, the point was taken on a server the database no longer runs on, a storage or size change is in progress, another point is being taken, or a rollback is already open.
  • “The safety backup did not finish, so nothing was changed…”: the rollback stopped before touching your data. Try again in a few minutes.
  • keep outside 1 to 30 is refused with 400.

Snapshots

Take a snapshot of a Dedicated database before a risky change and keep it until you delete it.

Restore to any second

Dedicated databases archive every change, so you can restore to an exact second. A restore always creates a new database.

Standby and high availability

Add a standby on another server. If the primary fails, the standby takes over and your connection address stays the same.

Dedicated databases

Create a Dedicated PostgreSQL database, connect to it, resize it and manage its lifecycle.