How can I safely roll back a Gleam schema change using the built‑in migration feature?

Answer the exact question first

To guarantee data integrity when you need to revert a schema change in Gleam, write the down function so that it is idempotent, wrapped in a transaction, and performs only the minimal reversible operations. Then, in CI, run the rollback against a brand‑new database instance and verify that the application still passes its tests. Gleam itself does not ship a dedicated “transaction helper” – you have to use the database’s transaction syntax inside the migration file.

Step‑by‑step rollback procedure

1. Inspect the migration file. Each migration lives in migrations/xxxx_description.gleam and contains two functions:

   pub fn up() { … }
   pub fn down() { … }

2. Write a safe down function. For a column addition, use an IF EXISTS guard and wrap the change in a transaction.

   pub fn down() {
     // Begin a transaction – most DB drivers used by Gleam support it.
     run_sql("BEGIN;");
     run_sql("ALTER TABLE users DROP COLUMN IF EXISTS new_column;");
     run_sql("COMMIT;");
   }

   Using IF EXISTS makes the statement safe to run multiple times and BEGIN/COMMIT guarantees that the operation can be rolled back if the migration fails partway.

3. Verify the migration file hasn’t changed. If the file was edited after it was applied, the down code may no longer match the original state. Compare the file against the commit that originally ran the migration.
4. Run the rollback locally. Execute:

   gleam migrate down

   or target a specific revision:

   gleam migrate down 20230915120000

   The CLI will locate the last applied migration (or the one you specify) and execute its down function.
5. Check the revision state. After the rollback, confirm that gleam migrate status shows one fewer applied migration and that the schema_migrations table reflects the expected revision.

Automating rollback testing in CI

In a CI pipeline, you can validate that a rollback works without touching production data by following this pattern:

1. Spin up a fresh test database (e.g., Docker, Testcontainers, or a dedicated test instance).
2. Run gleam migrate up to bring the schema to the latest state.
3. Optionally seed the database with a small dataset to exercise real‑world constraints.
4. Run gleam migrate down and then gleam migrate status to ensure the revision count has decreased.
5. Execute your integration or end‑to‑end tests against the rolled‑back schema.
6. If any test fails, the CI job fails, preventing a faulty migration from reaching staging or production.

Because the database is freshly created for each job, the rollback cannot affect real data. You can use a --dry-run flag if your database driver supports it to preview the SQL without applying it.

Gleam helpers and patterns

• Transaction handling. Gleam’s migration system does not automatically wrap each migration in a transaction. If your driver supports explicit transaction statements, include BEGIN; and COMMIT; inside the migration file as shown above.
• Idempotency helpers. Use IF EXISTS / IF NOT EXISTS in DDL statements. For example, ALTER TABLE … ADD COLUMN … IF NOT EXISTS in up and DROP COLUMN IF EXISTS in down.
• Version‑controlled migrations. Keep migration files in source control and avoid editing them after they have been applied. If you need to change a migration, create a new one instead of rewriting an old one.
• Pre‑deploy checks. Add a pre‑deploy step that runs gleam migrate down on a staging environment to confirm that the rollback will succeed before the new migration is applied to production.

Missing diagnostic detail (optional)

If your application uses a database other than PostgreSQL (e.g., MySQL, SQLite), the exact DDL syntax may differ. Let us know your DB engine so we can tailor the down statements accordingly.