Migrations

Keep DATABASE_URL in the project-root .env, then use the migration commands without repeating credentials:

rent migrate preflight
rent migrate dev --name add_users
rent migrate diff
rent migrate plan --name add_users
rent migrate create --name backfill_user_slugs
rent migrate seal
rent migrate validate
rent migrate apply
rent migrate status

These commands read the same RSL source as rent generate: rent/schema.rsl. Use --to only when a workspace keeps its RSL schema at another path.

Use a dedicated migration database role with access to the complete schema. PostgreSQL can hide individual columns, triggers, and trigger conditions from restricted application roles. Rent rejects incomplete inspection with an actionable error before planning changes; an invisible object is not treated as an absent object. Table ownership also grants visibility of trigger conditions. Keep the application's runtime role restricted; use migration credentials only for deployment and schema administration.

New migration files use 14-digit UTC timestamp prefixes such as 20260910022456_create_users.sql. Rent applies them lexically and rejects a pending migration that sorts before an already-applied version.

diff supports SQL and semantic JSON output. plan writes append-only SQL and refreshes rent.sum. validate proves that committed files still match the manifest. apply executes those exact files in version order; it never recalculates the reviewed migration. It uses backend locks and transactions, writes a dirty journal record before execution, and records each file checksum after success.

Destructive changes require both diff participation and explicit application approval:

rent migrate plan --name remove_legacy_sessions --drop-objects

rent migrate apply --allow-destructive

Use rent migrate drift after deployment to verify that the live database still matches the RSL schema. Use rent migrate history to inspect the durable journal. rent migrate repair is an explicit operator recovery command; it never runs automatically.

During local development, rent migrate dev combines plan, apply, and a final fixed-point inspection. rent migrate preflight is the read-only safety review before that step. rent migrate reset --yes rebuilds a disposable development database entirely from migration history.

Author a data migration

Schema diffs cannot decide how existing application data should be transformed. Create an editable migration for a backfill or cleanup:

rent migrate create --name backfill_user_slugs

Edit the generated SQL file, review it, then seal its checksum:

rent migrate seal
rent migrate validate
rent migrate apply

seal validates every edited draft before changing rent.sum. Destructive SQL is rejected unless the reviewed command includes --allow-destructive. The migration lifecycle tutorial executes an expand → backfill → contract release from beginning to end.