Post-migration data steps and why they can silently not run
Five data steps run around the schema migration, and a database pre-flight that fails skips all five while the migration itself still reports success.
kywi migrate is not only drizzle-kit. Two of its five data steps run before drizzle-kit, against the live connection it pre-flights; three run after drizzle-kit exits zero. Four of the five are Postgres-only and silent when they have nothing to do; the fifth, reconcileConfigSites, runs on every provider and prints a summary line on every successful run whether or not it had anything to do. All five depend on that same pre-flight connection succeeding — which is the part that can fail without failing the migrate.
The five steps, in the order they run
Before drizzle-kit is spawned, on the same connection the pre-flight opened, two steps run — both Postgres-only, because the cleanup reads ctid and jsonb, which MySQL does not have the same way:
dedupeMembershipRows- Removes pre-0.2.2 duplicate rows on
kywi_user_groups/kywi_site_membershipsthat the new primary keys would refuse. dedupeContentPermissionRows- Same shape, on
kywi_content_permissions.
After drizzle-kit exits 0, on the same connection, three more steps run:
reconcileConfigSites— every provider- Creates the
kywi_sitesrow for a sitekywi.config.tsdeclares but the database has never seen. reindexComponentInstances— Postgres only- Rebuilds the linked-component placement index.
backfillContentLayoutText— Postgres only- Rebuilds the layout search-text projection.
reconcileConfigSites runs on every provider. reindexComponentInstances and backfillContentLayoutText are skipped on MySQL — the reindex's candidate filter is Postgres-only SQL, and the search-text column feeds full-text search that does not exist on MySQL at all, so there is nothing for it to backfill. Running migrations against a live database covers what a clean run of all five prints, in order.
Why steps 4 and 5 exist
Both rebuild a value that is normally maintained on every write, and both ship empty on the upgrade that introduces them — an existing site's layouts and pages were saved before the column existed, and nothing rewrites them on its own. Until each page happens to be re-saved by hand, every component usage count reads zero and full-text search returns nothing for any layout-composed page, which on a real site is every page. The rebuild is what makes the upgrade complete itself instead of waiting on that. It is also idempotent, so it is the repair path any time one of these projections is suspected of drift, not only on the release that introduced it.
The pre-flight can fail without failing the migrate
All five steps run inside, or depend on, one try block that opens the database connection and sets a variable the rest of the command reads. If that block throws for any reason other than a recognised connection error — wrong password, missing database, connection refused, unknown host, all of which get their own friendly message and a hard exit — the variable is left unset, every one of the five steps is skipped, and the schema migration still runs and still exits 0. A run that did two thirds of its job used to print exactly what a complete run printed. The line that now names the gap:
Warning: the database pre-flight did not complete (<message>).
Skipped: membership dedupe (#40), content-permission grant dedupe, the config-site reconcile (#275), the component instance reindex (#147/#156), and the layout search-text rebuild (#231). The schema migration below still runs; re-run `kywi migrate` once the cause is fixed to complete these steps.Each step also warns on its own, and none of those change the exit code either
If the pre-flight connection succeeds but one individual step then fails, that step warns by itself and the rest still run — a bad row in one table does not stop the others:
Warning: could not dedupe membership rows (<message>). If drizzle-kit fails adding a primary key on kywi_user_groups/kywi_site_memberships, deduplicate those tables and re-run.
Warning: could not dedupe content-permission rows (<message>). If drizzle-kit fails adding an index on kywi_content_permissions, deduplicate that table and re-run.
Warning: could not reconcile config sites (<message>). A site declared in kywi.config.ts with no kywi_sites row will not resolve until this succeeds.
Warning: could not rebuild the component instance index (<message>). Component usage counts may read low until the next `kywi migrate`.
Warning: could not rebuild layout search text (<message>). Full-text search will not match copy that lives in page layouts until the next `kywi migrate`.A sixth, similarly-shaped warning — could not verify admin-table coverage … proceeding — belongs to a different check entirely: the guard ahead of drizzle-kit that refuses to run when a live content-type table is missing from the generated schema. That guard, and the refusal it protects, are Running migrations against a live database's to cover, not one of the five data steps here.
Recovering
Re-run kywi migrate once the underlying cause — usually the same connection problem the pre-flight hit — is fixed. All five steps are idempotent: a healthy re-run issues no writes it does not need to, and backfillContentLayoutText specifically updates only the rows whose projection actually changed, so re-running it on a site that was never affected does nothing. What confirms a clean run: the sites: N created, M updated line always prints, and the reindex and search-text lines print only when they had rows to touch — their silence on a repeat run is success, not a sign the step was skipped again.