Evolve Your Schema

Schema evolution in Kizaki follows a fixed workflow:

1. Edit your Inspire schema.
2. Generate a committed migration.
3. Review the plan.
4. Apply locally.
5. Deploy.

Every database change becomes reviewable and repeatable. The schema is easy to change, but nothing reaches your database as hidden local state.

A Concrete Example

Suppose you have a Project entity and want to add a status field:

entity Project {
  name: string
  ownerId: __User.id
  status: ProjectStatus = "Active"   // new field
}

enum ProjectStatus { Active, Archived }

After editing the schema, generate a migration:

kizaki migrate plan --name add_project_status

This creates migrations/0002_add_project_status/ containing:

• plan.migration — the human-readable migration plan describing what changes.
• snapshot.json — a snapshot of the full schema at this point in time.

Review plan.migration first. Confirm that Kizaki understood your intent: the new status field should be added with a default value, and the ProjectStatus enum should be created.

Commit the migration files. The dev server applies the migration on next start.

What Does Not Need A Migration

Not every Inspire change affects the database. These changes hot-reload without a migration:

• Adding, changing, or removing @grant or @deny policy rules.
• Changing schedule cron expressions or timeouts.
• Changing route declarations.
• Changing effect retry or backoff configuration.

The rule: if the database shape changes (tables, columns, indexes, enums), plan a migration. If only runtime behavior changes (policies, schedules, routes), you do not need one.

Handling RESOLVE Markers

When the compiler cannot determine your intent from the schema diff alone, it inserts [RESOLVE] markers in the migration plan. This happens when a change is ambiguous. A renamed field, for instance, could also be interpreted as a drop-and-add.

Edit the plan to clarify your intent before committing. The markers include both possible interpretations. See the Migrations guide for a detailed walkthrough of resolving ambiguous changes.

Apply Locally

kizaki migrate apply

kizaki dev uses committed migrations as the local source of truth. If your schema moves ahead without a committed migration for a schema-affecting change, startup fails closed and tells you what to do.

This prevents local development from drifting into a state that cannot be reproduced or deployed. A migration that does not exist locally cannot be applied in staging or production, so the error catches the problem early.

Checking Migration Status

You can check whether the local database is current with your committed migrations at any point:

kizaki migrate status

This shows which migrations have been applied, which are pending, and whether the current schema has uncommitted changes that would require a new migration.

Check migration status before deploying. A deploy applies pending migrations automatically, but confirming the state locally first avoids surprises.

Next Step

When your app is ready, continue with Deploy Your App.