Skip to main content

Overview

Spawn currently supports two formats of PostgreSQL backups:

You can read more about these in the PostgreSQL documentation.

Depending on the type of pg_dump backup you create, your data image definition file will require different configuration.

Plain#

Plain backups are the default type. If you omit the format value in the data image definition file, Spawn will assume the postgres backup is of the "plain" format.

For plain backups, you'll need to specify the following items in the data image definition file:

  • folder
  • file

Video#

Watch this video for how to create data images from PostgreSQL backups. Or follow the step-by-step instructions below.

Steps to create an image#

Create a backup#

Create a subdirectory for the backup file and data image YAML definition file:

mkdir -p ~/spawn/postgres-backup-image/ && cd ~/spawn/postgres-backup-image/

Assuming there is a database called pagila running at prod-db.example.com on port 5432 and is accessible to the user admin, you can run the following pg_dump command:

pg_dump -h prod-db.example.com -U admin --create pagila > dump.sql

Create a data image yaml file#

Now that we've got a dump.sql file produced by pg_dump we can create our Spawn data image definition YAML file called image.yaml in the current directory with the following contents:

# ~/spawn/postgres-backup-image/image.yaml
sourceType: backup
name: pagila
engine: postgresql
version: 12.0
backup:
folder: /<YOUR_HOME_DIRECTORY>/spawn/postgres-backup-image/
file: dump.sql
tags:
- production

This instructs Spawn to create a data image called pagila on Postgres 12. It will upload the file /<YOUR_HOME_DIRECTORY>/spawn/postgres-backup-image/dump.sql to Spawn and restore that backup using psql, snapshot the state of the restored database and then produce the data image ready for consumption.

The data image will also have a production tag associated with it, so you later know that this data image represents a backup of production.

Create the image#

Run

spawnctl create data-image --file=./image.yaml

This will create the data image from the backup defined in the image.yaml file we created.

Custom#

Custom backups are restored with the --no-owner flag enabled. This means all objects restored will be owned by the auto generated spawn admin user. If you need to, you may change the ownership of objects in subsequent data containers created from this image.

For custom backups, there's some additional configuration required. You'll need to specify the following items in the data image definition file:

  • folder
  • file
  • format
  • initialDatabaseName

Steps to create an image#

Create a backup#

Create a subdirectory for the backup file and data image YAML definition file:

mkdir -p ~/spawn/postgres-backup-image/ && cd ~/spawn/postgres-backup-image/

Assuming there is a database called pagila running at prod-db.example.com on port 5432 and is accessible to the user admin, you can run the following pg_dump command:

pg_dump -h prod-db.example.com -U admin --create pagila --format=custom > pagila.dump

Create a data image yaml file#

Now that we've got a pagila.dump file produced by pg_dump we can create our Spawn data image definition YAML file with the following contents:

# ~/spawn/postgres-backup-image/image.yaml
sourceType: backup
name: pagila
engine: postgresql
version: 12.0
backup:
folder: /<YOUR_HOME_DIRECTORY>/spawn/postgres-backup-image/
file: pagila.dump
format: custom
initialDatabaseName: pagila
tags:
- production

This instructs Spawn to create a data image called pagila on Postgres 12. It will upload the file /<YOUR_HOME_DIRECTORY>/spawn/postgres-backup-image/pagila.dump to Spawn and restore that custom backup file using pg_restore, snapshot the state of the restored database and then produce the data image ready for consumption.

The data image will also have a production tag associated with it, so you later know that this data image represents a backup of production.

Create the image#

Run

spawnctl create data-image --file=./image.yaml

This will create the data image from the backup defined in the image.yaml file we created.