Sam/docs add tests update (#1556)

* docs: schema.sql per maj version update

* docs: update command for flake checks

Author: samrose

migrations/README.md

@@ -120,7 +120,17 @@ Then, populate the migration at `./db/migrations/xxxxxxxxx_<some_message>` and m
 ```shell
 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.

nix/docs/adding-tests.md

@@ -11,12 +11,20 @@ and [prime.sql](../tests/prime.sql) (extensions may be enabled in either place.)
 ## pg\_regress tests
 
 pg\_regress tests are in [tests/sql](./../tests/sql/) with output in [tests/expected](./../tests/expected/).
-To create a new test, create a new SQL file in [tests/sql](./../tests/sql/) and then run:
+To create a new test, create a new SQL file in [tests/sql](./../tests/sql/)
+
+Next, for each current major version of postgres, we run a "flake check" build one at a time.
+
+Examples:
 
 ```
-nix flake check -L
+nix build .#checks.aarch64-darwin.psql_15 -L
+nix build .#checks.aarch64-darwin.psql_17 -L
+nix build .#checks.aarch64-darwin.psql_orioledb-17 -L
 ```
 
+(Note that the evaluation and nix build of the postgres packages "bundle" of each major version must succeed here, even though we run one version at a time. If you made changes to postgres or extensions, or wrappers those may rebuild here when you run this. Otherwise they will usually download the prebuilt version from the supabase nix binary cache)
+
 Next, review the logs to identify where the test output was written
 
 ```