diff --git a/apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx b/apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx index 3ad20c7278f..51addd244da 100644 --- a/apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx +++ b/apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx @@ -77,7 +77,7 @@ During the 90-day restore window a paused project can be restored to the platfor src="/docs/img/guides/platform/paused-90-day.png" /> -After the 90-day restore window, you can download your project's backup file from the project dashboard. This backup is compatible with [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html). You can extract your data from it, or attempt to manually restore the project. +After the 90-day restore window, you can download your project's backup file, and Storage objects from the project dashboard. See [restoring a backup locally](#restoring-a-downloaded-backup-locally) for instructions on how to load that backup locally to recover your data. +#### Restoring a Downloaded Backup Locally + +If the 90 day project restore window has expired but you need to access data contained within your project using SQL, you can attempt to restore the project into a local Postgres instance. Supabase publishes tooling that can be used for that purpose. Be aware that this workflow does not produce a complete Supabase environment with REST/Auth/Storage. Instead, it creates a standalone Postgres instance that is maximally compatible with your project's backup file to assist with recovering your data. + +Downloaded backups are plain text SQL files that can be executed in Postgres to restore your project's schema and data. If you need you access data within a backup we recommend restoring into a Postgres instance built using the Supabase open source build tooling to ensure that the local instance is as similar to the original project as possible. Here are the steps to start Supabase Postgres locally and restore the backup: + +Install [nix](https://nixos.org/): + +```sh +curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install +``` + +To identify your project's backup image version, reference the backup's download button following the `PG:` prefix: + +Project Paused: 90 Days Remaining + +Given Postgres version `15.6.1.115`, start Postgres locally with the nix command: + +```sh +nix run 'github:supabase/postgres?ref=15.6.1.115#start-server' 15 +``` + +where `15` refers to the backup's Postgres major version. + +Note that the earliest Supabase Postgres version that supports a direct reference is `15.6.1.115`. If you don't know your roject's Postgres version or it is lower than `15.6.1.115` then omit the `ref` option to build our most recent image: + +```sh +nix run 'github:supabase/postgres#start-server' -- 15 +``` + +Then restore the backup file from a separate shell session: + +```sh +nix run github:supabase/postgres#start-client -- --file +``` + +Which loads the backup into Postgres and drops you into a [psql](https://www.postgresql.org/docs/current/app-psql.html) prompt. For `start-client` you do not need to provide a reference to the backup's Postgres version. + +Once your project has been restored, connect to it with your preferred Postgres tooling using `host=localhost`, `user=postgres`, `port=5432`, and an empty password. This will allow you to inspect your saved data and export whatever is necessary. + +Errors encountered during the restore process are logged to the console by the `start-server` process. Review those errors and edit the backup file as needed until the project restores successfully. The backup file is a plain text sequence of SQL statements that recreate your database. To resolve common error classes like `relation "xxx" does not exist`, identify the line raising the exception and shuffle the `create ... "xxx"` statement before it. A failed restore leaves artifacts on the Postgres server so be sure to restart the `start-server` process between restore attempts. + +A Postgres database started with `start-server` command is not production ready and should never be used outside a local development workflow. + #### Disk sizing When upgrading, the Supabase platform will "right-size" your disk based on the current size of the database. For example, if your database is 100GB in size, and you have a 200GB disk, the upgrade will reduce the disk size to 120GB (1.2x the size of your database). @@ -148,7 +196,7 @@ Supabase performs extensive pre- and post-upgrade validations to ensure that the ## Migrate your project -Migrating projects can be achieved using the Supabase CLI. This is particularly useful for older projects (e.g. to use a newer Postgres version). +Migrating projects can be achieved using the Supabase CLI. This is particularly useful for older projects (for example to use a newer Postgres version). ### Before you begin diff --git a/apps/docs/public/img/guides/platform/paused-dl-backup.png b/apps/docs/public/img/guides/platform/paused-dl-backup.png index 9251b3dbbae..e888a465a76 100644 Binary files a/apps/docs/public/img/guides/platform/paused-dl-backup.png and b/apps/docs/public/img/guides/platform/paused-dl-backup.png differ diff --git a/apps/docs/public/img/guides/platform/paused-dl-image-version.png b/apps/docs/public/img/guides/platform/paused-dl-image-version.png new file mode 100644 index 00000000000..bb288dd1c85 Binary files /dev/null and b/apps/docs/public/img/guides/platform/paused-dl-image-version.png differ