From 743d36728d36cd202e76ac5991361eaab4be2916 Mon Sep 17 00:00:00 2001
From: Sam Rose <samuel@supabase.io>
Date: Thu, 17 Apr 2025 15:09:02 -0400
Subject: [PATCH 1/2] docs: update thie new migration create to cover missing
 steps

---
 migrations/README.md | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/migrations/README.md b/migrations/README.md
index ef3c7215b..868e9d97e 100644
--- a/migrations/README.md
+++ b/migrations/README.md
@@ -78,23 +78,31 @@ Additionally, [supabase/postgres](https://github.com/supabase/postgres/blob/deve
 
 ### Add a Migration
 
-First, start a local postgres server and apply the migrations
+First, start a local postgres server in another terminal window:
 
 ```shell
-# Start the database server
-nix run .#dbmate-tool -- --version 15 --flake-url "."
+# Start the database server in another window
+nix run .#start-server 15
+```
 
-# create a new migration
-nix develop
-dbmate new '<some message>'
+Then, in your main terminal window:
+
+```shell
+# Set up the database URL for migrations
+export DATABASE_URL="postgres://postgres@localhost:5435/postgres?sslmode=disable"
+
+# Create a new migration (make sure to specify the migrations directory)
+dbmate --migrations-dir="migrations/db" new '<some message>'
 ```
 
-Then, execute the migration at `./db/migrations/xxxxxxxxx_<some_message>` and make sure it runs sucessfully with
+Then, execute the migration at `./migrations/db/xxxxxxxxx_<some_message>` and make sure it runs successfully with:
 
 ```shell
 dbmate up
 ```
 
+Note: Migrations are applied using the `supabase_admin` superuser role, as specified in the "How it was Created" section above.
+
 ### Adding a migration with docker-compose
 
 dbmate can optionally be run locally using docker:

From 2d0266a1581b683ea31fdbb587c2f4a468f92a0b Mon Sep 17 00:00:00 2001
From: Sam Rose <samuel@supabase.io>
Date: Thu, 17 Apr 2025 17:36:10 -0400
Subject: [PATCH 2/2] docs: section on schema.sql for each maj  ver update

---
 migrations/README.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/migrations/README.md b/migrations/README.md
index 868e9d97e..7de888c2d 100644
--- a/migrations/README.md
+++ b/migrations/README.md
@@ -121,6 +121,18 @@ Then, populate the migration at `./db/migrations/xxxxxxxxx_<some_message>` and m
 docker-compose run --rm dbmate up
 ```
 
+### Updating schema.sql for each major version
+
+After making changes to migrations, you should update the schema.sql files for each major version of PostgreSQL:
+
+```shell
+# First, stop any running PostgreSQL servers
+# Then from the root of supabase/postgres run:
+nix run .#dbmate-tool -- --version all
+```
+
+This will create a schema.sql file for each major version of PostgreSQL. Commit these changes to your repository and push to your branch. The test.yml workflow will verify these changes against the test matrix.
+
 ## Testing
 
 Migrations are tested in CI to ensure they do not raise an exception against previously released `supabase/postgres` docker images. The full version matrix is at [test.yml](./.github/workflows/test.yml) in the `supabase-version` variable.