Migrations

When you change a table’s structure on a local or development database, those changes belong in your app’s migrations. Alcuin keeps track of what you changed since the project’s last migration, and writes it out as a new migration file in your tool’s own layout.

This page covers what works today. The feature is young: the roadmap says what comes next.

Link your project folder

Alcuin reads your project folder to learn its databases and its migrations. It reads files and runs nothing.

1. Run Open project folder… from the command palette, or drop the folder on the launcher.
2. Alcuin reads compose files, .env files and migration folders, and lists Connections to save.
3. Choose Save as and the project’s name. The connections are saved with the folder linked.

To link a folder to a project you already have, choose Link folder… from the project’s menu in the launcher.

Alcuin knows the layout of Prisma, Drizzle, Supabase, Atlas, Sqitch, Liquibase, Spring Boot, Flyway, dbmate, goose, golang-migrate, node-pg-migrate, Rails, Django, Alembic, Knex, Sequelize, TypeORM, Kysely, Laravel and Ecto, plus plain SQL files and schema.sql.

To see what it found and what it passed over, run What Alcuin read in the project folder. Rescan project folder reads it again, and Unlink project folder stops the project following it.

Alcuin reads folders up to 6 levels deep, up to 20,000 entries, and files up to 1 MB.

The Migrations view

Migrations, in the sidebar, compares the database with the schema its migration files build. It shows only for Local and Development connections: a staging or production database gets its changes from your deploy, not from Alcuin.

The view shows:

• Next: the one thing to do now, such as Save your 3 changes as a migration, or that the database is up to date.
• Not in any file yet: each change on this database that no migration holds. Open in Structure shows it, and the revert button puts it back the way the folder has it.
• Questions: where Alcuin can’t tell a rename from a drop and an add, it asks Renamed, or dropped and added?. Answer each before saving.
• The folder’s migrations, each marked Run here, Not yet or Needs a look.

The Migrations view, with a question to answer before saving.

The status chip in the status bar shows where things stand: 3 changes to write, In sync with prisma/migrations (the folder’s name), or, when the folder has migrations the database hasn’t run, 2 incoming · 3 changes to write.

Show the next migration opens the SQL that would be written, as a draft. Nothing is saved until you choose to.

Save your changes as a migration

1. On a Local or Development connection, change the structure: add a column in the Structure tab, or run an ALTER TABLE.
2. Run Save as migration… from the command palette, or choose the changes count in the top bar.
3. The first time, choose the folder your migration tool reads, such as prisma/migrations. If the project’s folder is linked, Alcuin offers it.
4. Enter a Name for the migration.
5. Choose Preview to read the SQL, then Save as migration (⌘↩ on macOS, Ctrl+Enter on Windows and Linux).

Saving does three things, and lists them before you choose:

• adds the file to the folder, numbered the way the folder already numbers them;
• checks that the folder’s files, the new one included, rebuild this schema on a scratch database;
• records the migration in the tool’s history table on this database, so your tool won’t run it again. For tools whose history Alcuin doesn’t write, it shows the tool’s own command to run instead.

Nothing runs on your database: it has these changes already. Save the file only adds and checks the file but doesn’t record it, for a database you won’t run your tool against. Undo the save takes it back.

Tool	What Alcuin writes
Prisma	<timestamp>_<name>/migration.sql
Drizzle	<0000>_<name>.sql, and an entry in meta/_journal.json
Supabase	<timestamp>_<name>.sql
dbmate, goose	<timestamp>_<name>.sql, with the tool’s up and down markers
golang-migrate	<version>_<name>.up.sql and .down.sql
Flyway	V<version>__<name>.sql
Rails, Django, Alembic	A plain SQL file, with a note on how to wrap it in the framework’s migration
No tool	schema.sql

To copy the SQL without saving any file, choose Copy the SQL instead.

You’ll know it worked when the Written list shows Added to, with your folder’s name, and Rebuilds this schema; the new file opens from Open file; the chip in the top bar says In sync with and the folder’s name, and the view says In sync with the folder.

Bring in new migrations

When a teammate’s migrations arrive in the folder, the view shows them as incoming. Bring in new migrations… plans them first, so you see what will run, then runs them on this database in order and records them in the tool’s history. It works on Local and Development connections only.

Start from a project’s migrations… builds an empty database from every file in the folder.

Where Sketch fits

On a new database in Sketch, changes apply as you make them. Hand off…, in Sketch’s menu, opens Save as migration… with those changes.