Upgrading

An upgrade is: pull the new code, rebuild the containers, apply any new migrations with migrate:deploy. The one step people skip is the rebuild — several containers run source directly rather than a baked artifact, so a stale image can silently keep running old code.

Only one of these two commands is supported in this repo.

How to upgrade

1. Pull the new version of the repository (git pull, or check out the release tag you want).
2. Rebuild the images — docker compose build so api, web, and worker pick up the new source, then pnpm install if dependencies changed. Use build, not up -d --build — the latter starts the new code immediately, ahead of the migrations below.
3. Apply Postgres migrations — pnpm --filter @deckgauge/db migrate:deploy. This only applies migrations that haven't run yet; it's safe to run on every upgrade, whether or not the schema changed.
4. Apply ClickHouse schema changes — pnpm migrate:clickhouse. New widgets add tables under clickhouse/schemas/; skip this and the first render of such a widget throws an unknown-table error instead of a clean empty state. Every schema file uses IF NOT EXISTS, so it's safe to run on every upgrade too.
5. Bring the stack back up — docker compose up -d.

Why migrate:dev doesn't work here

pnpm --filter @deckgauge/db migrate:dev fails with a shadow-database error (Prisma error P3006) in this repository — it isn't a supported path for either local development or an upgrade. migrate:deploy is: it applies whatever migrations are already committed under packages/db/prisma/migrations/ without needing a shadow database at all. If you're the one adding a new migration rather than applying existing ones, hand-write the migration SQL yourself and apply it the same way with migrate:deploy.

The rebuild story

worker isn't the odd one out here — api runs the same way. Both containers' CMD is npx tsx src/index.ts: they run their TypeScript source directly, not a compiled dist/ build. The one container that's a genuinely compiled artifact is web — its Dockerfile runs a Next.js build and ships the standalone output, so its CMD is node apps/web/server.js, no tsx involved. That distinction doesn't change what an upgrade needs, though: all three images bake their code in at build time, so a plain docker compose restart worker (or api, or web) after a code change does nothing regardless of which one you touched — the container is still running whatever was copied in during its last docker compose build. An upgrade that touches any of their code needs an actual rebuild — docker compose build worker api web (or --no-cache if you suspect a stale layer) — before restarting the affected service(s).

If it looks wrong

Related

• Backup & restore — take a backup before any upgrade that touches the schema.
• Install & first run — the same migrate:deploy step, on a fresh install.
• Services & architecture — how api, web, and worker are built.

Last updated 17 August 2026