Schema migrations

When the project has no migrations yet

A service whose schema was created by hand, by SchemaUtils.create, or by a DBA running SQL out of band has no migration history — and the first versioned migration you add has to account for what is already there.

Do not write V1__create_books.sql against a database where those tables already exist. Flyway will try to run it and fail on the first CREATE TABLE. The correct move is a baseline: capture the current schema as V1, then tell Flyway to treat existing databases as already at that version (baselineOnMigrate = true, baselineVersion = "1"). New environments run V1 and get the schema; existing ones record it and skip it.

Introducing Flyway is a change to how the service starts and how it is deployed, so say what you would add and wait for a yes: the dependency, the db/migration directory, the baseline file, and the startup call. Ask specifically whether any environment already has the schema — the answer decides whether you baseline or not, and getting it wrong fails the next deploy rather than the build in front of you.

The one rule

An applied migration is immutable. Once a file has run anywhere you do not control — a colleague's machine counts — it is history, and history is appended to, never edited.