mirror of
https://gitlab.com/wgp/dougal/software.git
synced 2025-12-06 13:07:08 +00:00
35 lines
1.4 KiB
Markdown
35 lines
1.4 KiB
Markdown
|
# Database schema upgrades
|
||
|
|
|
||
|
|
When the database schema needs to be upgraded in order to provide new functionality, fix errors, etc., an upgrade script should be added to this directory.
|
||
|
|
|
||
|
|
The script can be SQL (preferred) or anything else (Bash, Python, …) in the event of complex upgrades.
|
||
|
|
|
||
|
|
The script itself should:
|
||
|
|
|
||
|
|
* document what the intended changes are;
|
||
|
|
* contain instructions on how to run it;
|
||
|
|
* make the user aware of any non-obvious side effects; and
|
||
|
|
* say if it is safe to run the script multiple times on the
|
||
|
|
* same schema / database.
|
||
|
|
|
||
|
|
## Naming
|
||
|
|
|
||
|
|
Script files should be named `upgrade-<index>-<commit-id-old>-<commit-id-new>-v<schema-version>.sql`, where:
|
||
|
|
|
||
|
|
* `<index>` is a correlative two-digit index. When reaching 99, existing files will be renamed to a three digit index (001-099) and new files will use three digits.
|
||
|
|
* `<commit-id-old>` is the ID of the Git commit that last introduced a schema change.
|
||
|
|
* `<commit-id-new>` is the ID of the first Git commit expecting the updated schema.
|
||
|
|
* `<schema-version>` is the version of the schema.
|
||
|
|
|
||
|
|
Note: the `<schema-version>` value should be updated with every change and it should be the same as reported by:
|
||
|
|
|
||
|
|
```sql
|
||
|
|
select value->>'db_schema' as db_schema from public.info where key = 'version';
|
||
|
|
```
|
||
|
|
|
||
|
|
If necessary, the wanted schema version must also be updated in `package.json`.
|
||
|
|
|
||
|
|
## Running
|
||
|
|
|
||
|
|
Schema upgrades are always run manually.
|