Upgrading¶

How to move a running DataQ to a newer release without losing data.

How releases work¶

Releases are tagged vX.Y.Z and follow Semantic Versioning. The backend and frontend images carry the same tag.
The changelog lists what changed in each release. An entry marked ⚠️ breaking needs action from you; read every such entry between the version you run and the one you are moving to.
Database migrations only add to the schema in the release that needs them. A column or table is removed in a later release than the code that stopped using it, so the previous release keeps working while a new one rolls out.

Before you upgrade¶

Read the changelog from your version to the target version. Note any one-time step an entry asks for.
Back up the database — see Backup, restore & rollback for what to include beside it (the vault data on the prebuilt-image stack) and the exact pg_dump command. For the prebuilt-image stack, stopping the stack and copying the data directory (./dataq-data, or the path in DATAQ_DATA_DIR) also works.
Pin the target version. Do not upgrade onto the moving latest tag.

The prebuilt-image stack¶

The compose file and the images change together, so take the compose file from the release you are moving to and pin both images to it:

curl -O https://raw.githubusercontent.com/TheurgicDuke771/DataQ/vX.Y.Z/docker-compose.ghcr.yml
export DATAQ_BACKEND_TAG=vX.Y.Z DATAQ_FRONTEND_TAG=vX.Y.Z
docker compose -f docker-compose.ghcr.yml pull
docker compose -f docker-compose.ghcr.yml up -d

The migrate service brings the database to the new schema before the API and the worker start; they do not start if it fails. Your connections, suites, results and stored credentials are in the data directory and are kept.

A cloud deployment¶

Run the Deploy workflow on the release tag (see Deployment). It builds the images, runs the migration job and waits for it to succeed, and only then rolls the API, the worker, the scheduler (beat) and the frontend. If the migration fails, nothing is rolled.

Infrastructure changes are separate: if the changelog says the OpenTofu stack changed, run tofu plan and tofu apply on it first.

After you upgrade¶

/healthz returns 200 and you can sign in.
A suite run completes. This exercises the worker, the secret store and a datasource together.
Run any one-time step the changelog asked for.
Hard-refresh the browser if the app looks unchanged. The entry page is revalidated on every load, but an open tab keeps the bundle it already loaded.

Rolling back¶

Read the release's Rollback line first; the full procedure for both cases is in Backup, restore & rollback. In short:

Normal case (previous images on this schema — yes · DB restore needed — no): with the new release's tree, alembic downgrade <previous head> (the revision the line names), then re-pin the previous tag with its compose file and start. Nothing written since the upgrade is lost.
Restore case (DB restore needed — yes): stop the stack, restore the backup from before the upgrade, re-pin the previous tag and start. Everything written since the upgrade is lost, so decide quickly.

Re-pinning the previous tag without either step does not work once a migration has applied: the older release's migration step does not know the newer schema revision and stops, so the API and the worker never start. If the release added no migration, re-pinning alone is enough.

Skipping versions¶

You can upgrade straight to the latest release: the migration step applies every migration between your schema and the new one, in order. Read the changelog for every release you skip.