Document how to restore a project backup locally (#29674)

* document how to restore a project backup locally

* fix spelling error

* Update apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* Update apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* Update apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* Update apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* Update apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* Update apps/docs/content/guides/platform/migrating-and-upgrading-projects.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* show where to get image version

* prettier

* resolve feedback on back restore doc

* document purpose of local restore. note storage objects download

---------

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

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.
 
 <Image
   zoomable
@@ -93,6 +93,54 @@ If you upgrade to a paid plan while your project is paused, any expired one-clic
   src="/docs/img/guides/platform/paused-paid-tier.png"
 />
 
+#### 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:
+
+<Image
+  zoomable
+  alt="Project Paused: 90 Days Remaining"
+  src="/docs/img/guides/platform/paused-dl-image-version.png"
+/>
+
+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 <BACKUP 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