# Upgrading between minor versions

URL: https://kywi-docs-production.up.railway.app/operating/upgrading-between-minor-versions
Type: docPage

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](/operating/backups-what-kywi-does-not-do-for-you/)).

## 2. Bump the packages

{pm} 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](/developing/upgrading-core-inside-your-project/).

## Grep before you force

The upgrade deletes six pre-layered glue files without detecting a non-landmark file that imports one, so grep the whole repo for `lib/site` and `lib/config` imports before any `--force` and repoint them — file by file, that's [Upgrading core inside your project](/developing/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.

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"

## from the release branch, before merging

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.

## A minor bump often carries no schema change at all

Between two of this deployment's upgrades `kywi migrate` reported *no schema changes* and did nothing but reindex component instances; the next applied one additive `CREATE TABLE IF NOT EXISTS` and printed `sites: 2 created, 0 updated` — the post-step that creates a config-defined site's row the first time `migrate` sees it, each with a published home. Check `migrate:status` before booking a maintenance window — and read [Post-migration data steps](/operating/post-migration-data-steps-and-why-they-can-silently-not-run/), because the reindex and backfill are the part that can quietly not run.

## 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](/operating/multi-site-the-domain-field-and-host-based-resolution/)).
