Spring Boot: Flyway schema migrations

Provisional documentation — target JoinedWorkz 1.3.80

This page was marked on 2026-07-26 as implementation-oriented draft material. Its exact file names, migration transitions and failure cases have not yet passed the required clean-project verification against a canonical release example. Treat them as expected behaviour, not as a release-backed operational contract, until the dedicated Flyway documentation task is complete.

The SpringBoot platform can generate Flyway SQL migrations directly from the persistence model of a component.

This feature is intended for projects that want to:

• keep database evolution under version control,
• generate migration scripts directly where Flyway expects them,
• and use JoinedWorkz as the source of truth for schema changes.

It supports two workflows:

• STRICT – generates versioned migration files and validates schema evolution strictly,
• DEVELOPMENT – generates an overwriteable development migration on top of the latest versioned schema snapshot.

1. Modeling persistence with schema versions

Flyway migration generation is driven by the persists block of a component.

package org.joinedworkz.demo.backend

import org.joinedworkz.facilities.profiles.springboot
import org.joinedworkz.facilities.common.profiles.java

import org.joinedworkz.demo.backend.api

platform SpringBoot

component JoinedWorkzDemoBackend {

    provide /api/v1/requests
    provide /api/v1/users

    persists Main version=1 {
        ...org.joinedworkz.demo.backend.domain
    }
}

The version value is the schema version of this persistence model.

JoinedWorkz uses this version to:

• generate versioned Flyway migration files,
• generate schema snapshot JSON files,
• validate whether schema changes and version changes are consistent.

2. Generated artefacts

For a persistence named Main, JoinedWorkz generates:

In STRICT mode

• V1__main_init.sql
• V2__main_migration.sql
• V1_main_schema.json
• V2_main_schema.json

In DEVELOPMENT mode

• R__DEV_work.sql
• DEV_main_schema.json

The SQL files are written to the Flyway migration directory. The schema JSON files are written to a separate schema snapshot directory.

3. Recommended outlet configuration

Configure the migration and schema outlets in joinedworkz.properties so that the generated files are written directly into the project resources used by Flyway.

# === Flyway migrations (SQL) =========================================
# generate migration scripts directly where Flyway expects them
outlet.generatedSchemaMigration.directory=../backend-spring-generated/src/main/resources/db/migration
outlet.generatedSchemaSnapshot.directory=../backend-spring-generated/src/main/resources/db/schema
schemaMigration.mode=DEVELOPMENT

Recommended target directories:

• migrations: src/main/resources/db/migration
• schema snapshots: src/main/resources/db/schema

These directories should not be cleaned on build, because versioned migration history and schema snapshots must remain in the project.

4. Schema migration modes

4.1 STRICT

schemaMigration.mode=STRICT

STRICT mode is the normal mode for versioned migration generation.

It:

• reads the latest versioned schema snapshot,
• compares it with the current persistence model,
• validates version consistency,
• generates a new versioned Flyway migration only when a valid next version exists.

STRICT mode enforces these rules:

• if schema changes exist, the schema version must be increased,
• the next schema version must be exactly the previous version plus one,
• existing versioned migration files are never overwritten,
• existing versioned schema snapshot files are never overwritten.

STRICT mode also refuses to run while development artefacts still exist:

• R__DEV_work.sql
• DEV_main_schema.json

This prevents accidental release generation while temporary development artefacts are still present.

4.2 DEVELOPMENT

schemaMigration.mode=DEVELOPMENT

DEVELOPMENT mode is intended for local iterative work.

It:

• uses the latest versioned schema snapshot as baseline,
• compares it with the current persistence model,
• writes the current work result to overwriteable development artefacts,
• does not create new versioned migration files.

Generated development artefacts:

• R__DEV_work.sql
• DEV_main_schema.json

These files are overwritten on each generation run.

This allows repeated local validation and testing while the persistence model is still evolving.

5. Workflow

5.1 Typical development workflow

1. Start from the latest versioned schema history.
2. Set schemaMigration.mode=DEVELOPMENT.
3. Change the persistence model.
4. Regenerate.
5. Test the generated R__DEV_work.sql locally.
6. Repeat until the schema change is stable.

During this phase, JoinedWorkz keeps overwriting:

• R__DEV_work.sql
• DEV_main_schema.json

5.2 Creating the real next migration

Once the schema change is ready:

1. increase the schema version in the model,
2. remove the development artefacts,
3. switch to schemaMigration.mode=STRICT,
4. regenerate.

JoinedWorkz then generates the next versioned artefacts, for example:

• V2__main_migration.sql
• V2_main_schema.json

6. Validation rules

6.1 No previous versioned snapshot exists

• if the current schema version is 1, JoinedWorkz generates the initial migration,
• otherwise generation fails.

6.2 No schema changes detected

• if the version is unchanged, no new versioned migration is generated,
• if the version was increased without schema changes, generation fails.

6.3 Schema changes detected

• if the version was not increased, generation fails,
• if the version skips the next expected version, generation fails,
• if the version is exactly the next version, the next migration is generated.

6.4 STRICT mode with development artefacts present

Generation fails until these files are removed:

• R__DEV_work.sql
• DEV_main_schema.json

7. Schema snapshots

JoinedWorkz generates schema snapshots as JSON files alongside Flyway migrations.

These snapshots are used to:

• reconstruct the previously generated schema state,
• compare it with the current persistence model,
• derive migration operations,
• validate schema version changes.

Schema snapshots are part of the migration workflow and should be committed together with the corresponding SQL migration files.

8. Current migration semantics

The current implementation supports schema diffs for:

• table creation and removal,
• simple table renames,
• column creation and removal,
• simple column renames,
• column type changes,
• nullability changes,
• default value changes,
• primary keys,
• foreign keys,
• unique constraints,
• indexes.

Schema comparison is semantic:

• tables are compared by name,
• columns are compared by name,
• column order is not diff-relevant,
• changes to primary keys, foreign keys, unique constraints and indexes are handled as replace operations.

8.1 Simple rename detection

JoinedWorkz detects simple rename operations for:

• tables,
• columns.

This detection is intentionally conservative.

A rename is only recognized when JoinedWorkz finds a clear 1:1 case:

• a dropped table and a created table with the same structure,
• or a dropped column and a created column with the same structure.

For table renames, derived constraint and index names are ignored during rename detection. This allows JoinedWorkz to recognize a table rename even if names such as primary key, foreign key, unique constraint or index names change together with the table name.

For column renames, only simple 1:1 rename cases are detected. If the situation is ambiguous or combined with other structural changes, JoinedWorkz falls back to normal drop/create or other diff operations.

Complex rename refactorings are currently not detected automatically.

9. Recommended usage

Use DEVELOPMENT while exploring or refining persistence changes.

Use STRICT when a schema change is ready to become part of the real versioned Flyway history.

This gives you:

• convenient local iteration,
• strict protection of versioned migration history,
• and a clear handover from development work to release-ready migration generation.

10. Notes

• The generated migration SQL is intended for Flyway-based workflows.
• Development artefacts are temporary and should not remain in the project when generating real versioned migrations.
• The schema version belongs to the persistence model, not to the migration file itself.