What Changes When Migration Planning Is Offline

Database migrations are often treated as a moment of contact with a live database. That is convenient, but it can make the most important question difficult to answer in review: what exactly are we about to do?

Gaman takes a different starting point. It reads the migration history already committed to the repository and the desired schema described in source. From there, it can replay the known history, compare that result with the desired state, and produce a migration plan without opening a database connection.

Planning before permission

An offline plan is not just useful when credentials are unavailable. It changes the normal order of work. A developer can generate SQL, inspect the diff, and discuss a migration in a pull request before asking a shared environment to accept it.

That matters most when the database is expensive to disturb. The plan is based on repository state, so it is reproducible for another developer and suitable for CI. A live connection is still needed for actions such as applying a migration or verifying an existing database, but it is no longer the first requirement for understanding the change.

A migration is a reviewable artifact

Gaman turns the result into migration YAML and dialect-specific SQL rather than concealing the result behind a command. The generated artifact can be read, committed, and questioned like the rest of the codebase.

This does not remove the need for judgement. Data backfills, destructive changes, and application-level rollouts still deserve careful design. A deterministic schema plan is a foundation, not an excuse to stop thinking.

Gaman is an early project and its APIs and file format may evolve before 1.0. The direction is already clear, though: migration tooling should help make change visible, not make it feel magical.