Fix documentation relating to migrations (#268)

Author: benjie

@app/db/README.md

@@ -19,12 +19,14 @@ may prefer to switch this out for your preferred migration framework such as
 Should you decide to stick with Graphile Migrate, we strongly encourage you to
 [read the Graphile Migrate README](https://github.com/graphile/migrate/blob/main/README.md)
 before attempting to write your own migrations. Graphile Migrate works in quite
-a different way to many other migration frameworks, and relys on your discipline
-and SQL knowledge to work well.
+a different way to many other migration frameworks, and relies on your
+discipline and SQL knowledge to work well.
 
 If you're not very comfortable with SQL then we recommend you use an alternative
 migration framework (for now at least, Graphile Migrate is still young...)
 
+[Read more about the migrations in `migrations/README.md`.](./migrations/README.md)
+
 ## Database Roles
 
 Graphile Starter uses three roles:
@@ -45,7 +47,7 @@ Graphile Starter uses three roles:
   queries runs as, it's what the vast majority of your `GRANT`s will reference
   and the row level security policies will apply to. It represents both logged
   in AND logged out users to your GraphQL API - it's assumed that your Row Level
-  Security policies will deferentiate between these states (and any other
+  Security policies will differentiate between these states (and any other
   "application roles" the user may have) to determine what they are permitted to
   do.
 
@@ -59,3 +61,10 @@ dev, production), not with your own user role nor the default superuser role
 (often named `postgres`). This ensures that the system behaves as expected when
 graduating from your local dev environment to hosted database systems in
 production.
+
+## \_\_tests\_\_/
+
+Our database tests are written in Jest, enabling you to call database functions
+or run SQL and perform your regular assertions against them. We've added a
+number of helpers to make this easier; read more in the
+[\_\_tests\_\_ README](./__tests__/README.md).

@app/db/migrations/README.md

@@ -1,12 +1,11 @@
 # Migrations
 
 This folder contains the database migrations. We're using the `graphile-migrate`
-project to produce these; we highly recommend you read the README before
-implementing your own migrations:
+project to produce these; we highly recommend you
+[read the Graphile Migrate README](https://github.com/graphile/migrate/blob/main/README.md)
+before implementing your own migrations.
 
-https://github.com/graphile/migrate/blob/main/README.md
-
-The main file you'll be working with is `current.sql`.
+The main files you'll be working with are those in the `current/` folder.
 
 ## afterReset.sql
 
@@ -15,12 +14,16 @@ currently grants permissions to the relevant roles and creates the required
 extensions. It's expected that this is ran with database superuser privileges as
 normal users often don't have sufficient permissions to install extensions.
 
-## current.sql
+## current/\*.sql
 
 This is where your new database changes go. They need to be idempotent (for
-details read the README above). The `yarn start` command will automatically
-watch this file and re-run it whenever it changes, updating your database in
-realtime.
+explanation
+[read the Graphile Migrate README](https://github.com/graphile/migrate/blob/main/README.md)).
+The `yarn start` command will automatically watch these files and re-run them
+whenever they change, updating your database in realtime. Each file needs a
+unique positive integer prefix, we've started you off with
+`current/1-current.sql` but you can add more if it helps you structure your
+migration more cleanly.
 
 **IMPORTANT**: because we use `ignoreRBAC: false` in PostGraphile's
 configuration, new tables _will not show up_ until you `GRANT` permissions on
@@ -42,7 +45,7 @@ grant
 on app_public.my_new_table to :DATABASE_VISITOR;
 ```
 
-## committed
+## committed/\*.sql
 
 When you're happy with the changes you have made, you can commit your migration
 with
@@ -51,9 +54,10 @@ with
 yarn db commit
 ```
 
-This will call `graphile-migrate commit` which involves moving `current.sql`
-into the `committed` folder, and hashing it to prevent later modifications
-(which should instead be done with additional migrations).
+This will call `graphile-migrate commit` which involves merging the
+`current/*.sql` files together and then putting the result into the `committed`
+folder with a hash to prevent later modifications (which should instead be done
+with additional migrations).
 
 If you've not yet merged your changes (and no-one else has ran them) then you
 can run
@@ -64,9 +68,3 @@ yarn db uncommit
 
 and it will perform the reverse of this process so that you may modify the
 migrations again.
-
-## **tests**
-
-Our database tests are written in Jest, enabling you to call database functions
-or run SQL and perform your regular assertions against them. We've added a
-number of helpers to make this easier.