Database Migrations

Overview

We use Flyway for database schema versioning and migrations. All database changes are tracked through version-controlled SQL scripts, ensuring consistent database states across all environments.

Migration Files

Location

All migration scripts should be placed in:

src/main/resources/db/migration

Naming Convention

Format:

V<VERSION-NUMBER>__<description>.sql

Example:

V1__create_users.sql

The version number should be sequential and unique across all migrations.

Branching Strategy

Create migration files in feature branches
Use the next available version number (increment from the last existing version)
Rebase if conflicts occur
Test migrations locally before merging (just start application-server to apply migrations)
Merge to staging (and then to main when creating a release)

Warning

Never modify existing/committed migrations! Create new migration files for any necessary changes.

Handling Migration Conflicts

When working with multiple branches, you may encounter migration conflicts. Here’s how to handle them:

Clean existing migrations:
```
./gradlew flywayClean flywayMigrate
```
Apply current branch migrations:
- Start application-server to apply migrations automatically
When switching branches, clean and reapply migrations again:
```
./gradlew flywayClean flywayMigrate
```