Skip to content

Upgrading between minor versions

A production upgrade is four ordered steps: dump the database, bump the packages, run the scaffold upgrade, then migrate the live database before the push.

Four steps, in this order, on a branch. The order is the whole content of this page: the migration runs against the production database before the commit that deploys the new code, so the schema is never behind the app that expects it.

1. Dump first

Nothing in Kywi rolls back an applied migration, so the dump is the rollback plan. Take it through a public TCP proxy — an operator machine cannot reach a platform's internal database host — and match the client version to the server, which is the step that costs an hour when it is skipped (Backups).

2. Bump the packages

pnpm

pnpm add @kywi-software/core@latest @kywi-software/js@latest @kywi-software/cli@latest @kywi-software/mcp@latest

3. Run the scaffold upgrade, dry first

npx create-kywi-app@<version> upgrade --dry-run, then --force if it refuses anything you understand. The gate before merging is that a second dry run reports every stamped file current — those files are core's, and editing one converts every future upgrade into a manual merge. What each report word means is Upgrading core inside your project.

4. Migrate production, then push

Run kywi migrate against the production database from your machine, through the proxy, while the branch is still unmerged. Then merge, and let the push deploy the code that expects the new schema.

from the release branch, before mergingbash
PROXY="postgresql://$PGUSER:$PGPASSWORD@$PROXY_HOST:$PROXY_PORT/$PGDATABASE?sslmode=require"

DATABASE_URL="$PROXY" pnpm exec kywi migrate:status  # what is pending, before you commit to it
DATABASE_URL="$PROXY" pnpm exec kywi migrate         # applies, then runs the post-steps

psql "$PROXY" -Atc "select hash from drizzle.__drizzle_migrations order by created_at"

Compare that journal against your local database: after an upgrade the two must hold the same hashes in the same order. Commit the generated migration and its snapshot in the same pull request as the version bump, or the next person generates a duplicate. migrate:status needs a drizzle.config.ts in the working directory and exits 1 telling you to generate one if there is none — an empty report and a wrong directory look different, which is the point of running it first.

Verifying

Use one smoke script and run it twice — against a local server on the branch before merging, and against the deployed URL after. Its value is that it is the same check every time, so "the count went from twelve to eleven" is a signal rather than an argument. A multi-site deployment needs it run per host, since each host resolves to a different site (Multi-site).