Added developer docs for postgres

README.md

@@ -109,6 +109,46 @@ The realm server uses the request accept header to determine the type of request
 | `text/html`                   | Card instance URL's should not include the `.json` file extension. This is considered a 404                                                                                                                                                                                                                          | Used to request rendered card instance html (this serves the host application)                                                                                                 |
 | `*/*`                         | We support node-like resolution, which means that the extension is optional                                                                                                                                                                                                                                          | Used to request transpiled executable code modules                                                                                                                             |
 
+### Database
+
+The boxel system leverages a Postgres database. The Postgres database lives within a docker container, `boxel-pg`, that is started as part of `pnpm start:all`. You can manually start and stop the `boxel-pg` docker container using `pnpm start:pg` and `pnpm stop:pg`. The postgres database runs on port 5435 so that it doesn't conflict with a natively installed postgres that may be running on your system.
+
+When running tests we isolate the database between each test run by actually creating a new database for each test with a random database name (e.g. `test_db_1234567`). The test databases are dropped before the beginning of each test run.
+
+If you wish to drop the development database you can execute:
+```
+docker exec boxel-pg dropdb -U postgres -w boxel
+```
+
+You can then run `pnpm migrate up` to create the database again.
+
+#### DB Migrations
+When the realm server starts up it will automatically run DB migrations that live in the `packages/realm-server/migrations` folder. As part of development you may wish to run migrations manually as well as to create a new migration.
+
+To create a new migration, from `packages/realm-server`, execute:
+```
+pnpm migrate create name-of-migration
+```
+This creates a new migration file in `packages/realm-server/migrations`. You can then edit the newly created migration file with the details of your migration. We use `node-pg-migrate` to handle our migrations. You can find the API at https://salsita.github.io/node-pg-migrate. 
+
+To run the migration, execute:
+```
+pnpm migrate up
+```
+
+
+To revert the migration, execute:
+```
+pnpm migrate down
+```
+
+The boxel system also uses SQLite in order to run the DB in the browser as part of running browser tests (and eventually we may run the realm server in the browser to provide a local index). After you have completed your migration you then need to generate a new schema SQL file for SQLite. To generate a new SQLite schema, from `packages/realm-server`, execute:
+```
+pnpm make-schema
+```
+This will create a new SQLite schema based on the current postgres DB (the schema file will be placed in the `packages/host/config/schema` directory). This schema file will share the same timestamp as the latest migration file's timestamp. If you forget to generate a new schema file, the next time you start the host app, you will receive an error that the SQLite schema is out of date.
+
+
 ### Matrix Server
 
 The boxel platform leverages a Matrix server called Synapse in order to support identity, workflow, and chat behaviors. This project uses a dockerized Matrix server. We have multiple matrix server configurations (currently one for development that uses a persistent DB, and one for testing that uses an in-memory DB). You can find and configure these matrix servers at `packages/matrix/docker/synapse/*`.

packages/realm-server/package.json

@@ -97,7 +97,7 @@
     "lint:js:fix": "eslint . --fix",
     "lint:glint": "glint",
     "migrate": "PGDATABASE=boxel ./scripts/ensure-db-exists.sh && PGPORT=5435 PGDATABASE=boxel PGUSER=postgres node-pg-migrate",
-    "schema": "./scripts/schema-dump.sh"
+    "make-schema": "./scripts/schema-dump.sh"
   },
   "volta": {
     "extends": "../../package.json"