47 lines
1.6 KiB
Markdown
47 lines
1.6 KiB
Markdown
|
# Quartermaster (repo instructions)
|
||
|
|
|
||
|
|
## Database safety rule
|
||
|
|
|
||
|
|
The SQLite database at `./quartermaster.db` (or whatever path
|
||
|
|
`QUARTERMASTER_DB_URL` points at) holds real user data. It is
|
||
|
|
`.gitignored`, so losing it means the data is gone.
|
||
|
|
|
||
|
|
**Before any operation that interacts with the database at the schema
|
||
|
|
or destructive level**, run:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
./scripts/backup-db.sh <reason>
|
||
|
|
```
|
||
|
|
|
||
|
|
That includes:
|
||
|
|
|
||
|
|
* `rm`, `mv`, truncate, or otherwise replace `quartermaster.db`
|
||
|
|
* Ad-hoc `sqlite3` sessions that might `DROP`, `DELETE`, or `UPDATE`
|
||
|
|
* Any script that does data migration or cleanup outside the running
|
||
|
|
application
|
||
|
|
|
||
|
|
Alembic runs `scripts/backup-db.sh alembic` automatically on every
|
||
|
|
`alembic upgrade`, `alembic downgrade`, or `alembic revision --autogenerate`
|
||
|
|
via the hook in `alembic/env.py`, so you do not need to call it
|
||
|
|
manually for ordinary schema work. The hook is defense in depth, not
|
||
|
|
a substitute for thinking.
|
||
|
|
|
||
|
|
Routine writes through the running web application are NOT covered by
|
||
|
|
this rule. Those are normal application behaviour, not "interactions"
|
||
|
|
in the sense meant here.
|
||
|
|
|
||
|
|
## Where backups go
|
||
|
|
|
||
|
|
Default: `<dir-of-db-file>/backups/quartermaster-YYYYMMDD-HHMMSS-{slug}.db`.
|
||
|
|
For the standard `./quartermaster.db` that resolves to `./backups/`.
|
||
|
|
Override with `QUARTERMASTER_BACKUP_DIR=/some/path`.
|
||
|
|
|
||
|
|
The `backups/` directory is `.gitignored`. Retention is forever:
|
||
|
|
backups are small. Prune manually if you need to.
|
||
|
|
|
||
|
|
## Restoring
|
||
|
|
|
||
|
|
A backup is a complete SQLite file. To restore, stop the app, replace
|
||
|
|
`quartermaster.db` with the chosen backup (`cp backups/... quartermaster.db`),
|
||
|
|
then restart.
|