Skip to content

Upgrade Brick Work

Since 0.9.0.

Do this when a new version is out and you want to move to it. Most upgrades need nothing from you: start the new version and it brings the collection along. The one exception is the move from 0.5.x to 0.6.0, which you run yourself.

Before you upgrade

  1. Back up. Export the database (Manage → Tools & Admin → Database → Export database) and copy secret.key and the media folders. Back up and restore has the steps.
  2. Read the entry for the new version in the changelog. It names any step you must take.

The backup is also the way back. An upgrade that changes the schema is one-way.

What each version does

From To Schema What runs Going back
0.5.x 0.6.0 3.3 to 4.0 You run brickwork migrate4 on a copy. It writes a new file and checks it before it publishes. The 3.3 file is never changed. Keep the 3.3 file and start 0.5.x on it.
0.6.0 0.7.0 4.0 to 4.1 In place, at the first read-write start. Restore the backup. 0.6.0 cannot open a 4.1 file.
0.7.0 0.8.0, 0.8.1 none (stays 4.1) Nothing. Start the older version on the same file.
0.8.x 0.9.0 4.1 to 4.2 In place, at the first read-write start. Restore the backup. 0.8.x cannot open a 4.2 file.
0.9.0 1.0.0 none (stays 4.2) Nothing. Start the older version on the same file.
1.0.0 1.0.1 none (stays 4.2) Nothing. Start the older version on the same file.

You can skip versions from 0.6.0 on. Starting 0.9.0 on a 4.0 file runs both in-place steps one after the other, each in its own transaction; a step that fails leaves the file at the version before it. From 0.5.x you always run brickwork migrate4 first, and it writes the schema of the version you are moving to.

A read-only instance (BW_READ_ONLY) never upgrades a file. Start the new version read-write once, then switch.

If an older version refuses a newer file, its message may say a 3.3 file must be migrated. Do not run migrate4 on a 4.x file: it reads only a 3.3 file. Restore the backup instead.

From 0.5.x

  1. Stop Brick Work 0.5.x, so that everything it wrote is in brickwork.db and not only in brickwork.db-wal. Then make a copy of the 3.3 brickwork.db. Never copy the file while the app runs.
  2. Run brickwork migrate4 on the copy, with the catalogue.db and the mapping files it needs. The arguments and the exit statuses are in Commands.
  3. Read the report folder. Rows that need a decision stop the run.
  4. Put the new file in place as brickwork.db, beside catalogue.db, and start the new version.

Move to the new version

With the Docker install, check out the release you want by its tag, then pull its image and restart. From 1.0.0 on, compose.yaml names the published image; up to 0.9.0 it builds from source, so use docker compose build there:

git fetch
git checkout v1.0.1
docker compose pull         # 0.9.0 and older: docker compose build
docker compose up -d

Your data/ folder stays where it is. Without Docker, update the source the same way and restart the app.

From 1.0.0 on, you can check the published image before you start it, with the GitHub CLI and that release's version for VERSION:

gh attestation verify oci://ghcr.io/ulef1005/brick-work:VERSION --owner Ulef1005
gh attestation verify oci://ghcr.io/ulef1005/brick-work:VERSION --owner Ulef1005 \
  --predicate-type https://spdx.dev/Document/v2.3

The first command checks the build provenance: the image was built by this repository's release workflow from that tag. The second checks the software bill of materials (SBOM, in SPDX) attached to the same image, which lists the packages inside it. Both print the verified attestation; a failure means the image did not come from this repository's release, so do not start it.

Check the result

  1. Open /api/v2/health (no token). It shows the app version and the schema, for example "app": "1.0.1" and "schema": "4.2". /api/v1/health answers the same.
  2. Run brickwork check (with Docker: docker compose exec brickwork brickwork check), or press Run integrity check under Manage → Tools & Admin → Database. Both must pass.
  3. Open Sets and compare what you see with your last export if you kept a note of the counts.

Go back

Stop Brick Work, put the backed-up brickwork.db and secret.key back, check out the older version's tag, and refresh the image before you start it. For 0.9.0 and older, run docker compose build: their compose.yaml builds from source. From 1.0.0 on, run docker compose pull. Then run docker compose up -d. Without that step, Docker starts the newer image again, and it upgrades the restored file once more. Changes made after the upgrade are not in the backup. Back up and restore has the details.

What next