rent migrate plan

Use rent migrate plan after reviewing the diff. It writes the SQL to rent/migrations and records its checksum in rent.sum, giving the team a stable artifact to review and commit. The checksum printed here is the migration file's SHA-256 in hex. rent.sum records its own cumulative h1: digests.

Create a migration

rent migrate plan --name create_posts

Migration: create_posts

Created ./rent/migrations/20260910022456_create_posts.sql
Changes   2 operations
Checksum  7dd6a3c1e94b2f08a5d7c3e1b9f04a6d2c8e5b7f1a3d9c0e4b6f8a2d5c7e9b1a

The generated version is a 14-digit UTC timestamp (YYYYMMDDHHMMSS). Timestamp prefixes preserve creation order in the filesystem and migration journal. If two migrations are created within one second, Rent advances the later version while preserving a valid timestamp.

Plan several changes before applying

A plan holds what your migration files do not yet do, whatever state your database is in. Plan a column, change the schema again, and the next plan holds only the new change:

rent migrate plan --name add_post_title
rent migrate plan --name add_post_summary

Rent works this out by replaying your migrations into a temporary database it creates beside your development database and removes when the plan is written. There is nothing to set up. If your database user cannot create databases, set SHADOW_DATABASE_URL (or pass --shadow-database-url) to an empty database Rent may reset before each plan.

On MySQL and MariaDB the files name no database, so a migration planned against a development database applies to a production database named otherwise.

Supply a release-controlled version

rent migrate plan --name add_post_versions --migration-version 20260910030000

Migration: add_post_versions

Created ./rent/migrations/20260910030000_add_post_versions.sql
Changes   1 operation
Checksum  c7fb91a4d2e8b6f03c5a7d9e1b4f6a8c2e0d3b5f7a9c1e4b6d8f0a2c5e7b9d1e

An explicit version is useful when migrations must align with a release train. Keep it in the same YYYYMMDDHHMMSS form so later automatic versions remain chronological.

Choose a migration directory

rent migrate plan --name add_comments --directory crates/blog/migrations

Migration: add_comments

Created ./crates/blog/migrations/20260910022512_add_comments.sql
Changes   3 operations
Checksum  39b2d0f5a8c1e7b3d6f9a2c4e8b0d5f7a1c3e6b9d2f4a7c0e5b8d1f3a6c9e2b4

Use a custom directory when each service or workspace crate owns its own database lifecycle.

Plan removals

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

Planning records destructive SQL but does not execute it. Application still requires explicit destructive approval.

Without --drop-objects, plan leaves those deletions out of the file and lists them after the summary, so a table the schema no longer declares is never forgotten silently.

No schema changes

When your migrations already produce the RSL schema, Rent does not create an empty migration:

rent migrate plan --name unnecessary

Ready: No schema changes.