You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+40
Original file line number
Diff line number
Diff line change
@@ -109,6 +109,46 @@ The realm server uses the request accept header to determine the type of request
109
109
|`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) |
110
110
|`*/*`| We support node-like resolution, which means that the extension is optional | Used to request transpiled executable code modules |
111
111
112
+
### Database
113
+
114
+
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.
115
+
116
+
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.
117
+
118
+
If you wish to drop the development database you can execute:
119
+
```
120
+
docker exec boxel-pg dropdb -U postgres -w boxel
121
+
```
122
+
123
+
You can then run `pnpm migrate up` to create the database again.
124
+
125
+
#### DB Migrations
126
+
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.
127
+
128
+
To create a new migration, from `packages/realm-server`, execute:
129
+
```
130
+
pnpm migrate create name-of-migration
131
+
```
132
+
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.
133
+
134
+
To run the migration, execute:
135
+
```
136
+
pnpm migrate up
137
+
```
138
+
139
+
140
+
To revert the migration, execute:
141
+
```
142
+
pnpm migrate down
143
+
```
144
+
145
+
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:
146
+
```
147
+
pnpm make-schema
148
+
```
149
+
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.
150
+
151
+
112
152
### Matrix Server
113
153
114
154
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/*`.
0 commit comments