feat(database): manage the schema with typeorm migrations

- replace synchronize with migrations, starting with a generated initial
  migration that adopts databases created by synchronize
- apply pending migrations in the docker container before the server,
  and refuse to start the server while migrations are pending
- share one entity list and data source between app, migration runner,
  typeorm cli and tests; tests run the real migrations
- add migration:run, migration:show and migration:generate scripts and
  a test that fails when entities and migrations differ
- exit with code 1 when startup fails
- bump version to 1.20.0
This commit is contained in:
Andrii Arsenin committed 2026-09-30 21:45:42 +03:00
1 parent 0ae807d68d
commit 95c3bd7bcb
17 files changed
+526 -80

No files matched your search

+2 -1
View File
@@ -50,6 +50,7 @@ Everything runs in one container built from the root `Dockerfile`: the server se
Cross-cutting pieces:
- `config/app.config.ts` - all settings, validated at startup (see `.env.example`).
- `database/` - the entity list, TypeORM data source options (shared by the app, the migration runner and the TypeORM CLI), the migration runner and the migrations.
- `common/app-package.ts` - app name and version, read from the workspace root `package.json`.
- `common/client-static.ts` - serving the built client, with the `index.html` fallback for client-side routes.
- `common/body-parsers.ts` - YAML request bodies (`application/yaml`) for the import endpoint.
@@ -57,7 +58,7 @@ Cross-cutting pieces:
## Data
SQLite via TypeORM with `synchronize: true`: entity changes alter the schema on startup, and there are no migrations. The main tables:
SQLite via TypeORM. The schema is managed by migrations (`server/src/database/migrations/`, registered in `migrations/index.ts`); `synchronize` is off. The Docker container applies pending migrations (`node dist/database/migrate`) before starting the server, and the server refuses to start while migrations are pending. See "Database migrations" in [development.md](development.md). The main tables:
- `scenarios` / `scenario_steps` hold the **latest** version of each scenario; `scenario_versions` holds a snapshot of every version (content + steps).
- `snippets` holds the latest version of each snippet; `snippet_versions` holds every version. Step code pins a version with `runSnippet("alias@N")`.
+30
View File
@@ -86,6 +86,36 @@ The built files are emitted to `client/dist/`.
---
## Database migrations
The SQLite schema is managed by TypeORM migrations in `server/src/database/migrations/`; `synchronize` is off.
- **Docker:** the container applies pending migrations before starting the server.
- **Locally:** build, then apply them before starting the server (it refuses to start while migrations are pending):
```bash
npm -w server run build
npm -w server run migration:run # apply pending migrations to DB_PATH
npm -w server run migration:show # list migrations and whether they're applied
```
The scripts run from `server/`, so `DB_PATH` (default `data/liqa.db`) is relative to it, and they read `server/.env` if present, like the server does.
**Changing the schema** (adding or changing an entity):
1. Change the entity and build (`npm -w server run build`).
2. Make sure your local database is on the latest migration (`migration:run`).
3. Generate a migration from the difference between the entities and that database:
```bash
npm -w server run migration:generate -- src/database/migrations/AddSomething
```
4. Review the generated file, then add its class to `MIGRATIONS` in `src/database/migrations/index.ts` (they're listed explicitly, oldest first).
5. Run the tests: `test/migrations.spec.ts` checks that the migrations produce exactly the schema the entities describe, and fails if an entity change has no migration.
The initial migration (`Initial…`) adopts databases created before migrations existed (by `synchronize`): if the tables already exist, it's only recorded as applied.
## Running tests
### Server (Jest)