dougal-software/etc/db/upgrades

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:

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.