Flyway or Liquibase in Micronaut for DB Migrations

When building real-world applications, database schema changes are unavoidable.
Manual DDL changes or relying on Hibernate’s auto schema generation (hbm2ddl.auto) is risky for production.

βœ… Solution: Use Database Migration Tools like Flyway or Liquibase in Micronaut.

Micronaut fully supports two of the most popular tools:

  • Flyway
  • Liquibase

Both tools:

  • Version your database schema.
  • Apply migrations automatically.
  • Work across all supported databases (H2, PostgreSQL, MySQL, etc).
  • Integrate beautifully with Micronaut.
Flyway or Liquibase in Micronaut for DB Migrations

πŸ”§ Why Use Migration Tools?

ProblemSolution
Manual SQL scriptsVersion-controlled migrations
Deployment errorsAuto-run migrations
Inconsistent schemasSingle source of truth
Difficult rollbackVersioned rollbacks

πŸš€ Option 1: Flyway Integration


πŸ”¨ Adding Flyway Dependency

For Maven:

βœ… Micronaut will auto-discover Flyway and run migrations at startup.

πŸ”¨ Flyway Configuration

Add to application.yml:

You can configure multiple datasources if needed.

πŸ”¨ Create Migration Files

By default, Flyway expects migration files inside:

Sample Migration: V1__create_students.sql

βœ… The filename format V<version>__<description>.sql is important!

πŸ”¨ Flyway Run Flow

When Micronaut starts:

  • Flyway scans existing migrations.
  • Runs any pending migrations.
  • Ensures schema is up-to-date.

πŸ”¨ Verify Flyway Execution

You’ll see logs like:

βœ… Flyway maintains a flyway_schema_history table to track applied migrations.

πŸš€ Option 2: Liquibase Integration

πŸ”¨ Adding Liquibase Dependency

For Maven:

βœ… Like Flyway, Micronaut automatically configures Liquibase at startup.

πŸ”¨ Liquibase Configuration

Add to application.yml:

πŸ”¨ Create changelog XML

By default, Liquibase expects changelogs in:

Sample Master Changelog: db-changelog.xml

πŸ”¨ Liquibase Run Flow

  • Liquibase reads the changelog XML.
  • Applies changes not yet applied.
  • Tracks changes in DATABASECHANGELOG table.

βœ… Like Flyway, it’s fully versioned.

βš– Flyway vs Liquibase

FeatureFlywayLiquibase
LanguagePure SQL (or Java)XML, YAML, JSON, SQL
Learning CurveEasierSlightly steeper
Complex RefactoringLimitedMore powerful
CommunityVery activeVery active
Micronaut SupportNativeNative

βœ… Both are excellent; pick based on your team’s comfort level.

🐞 Common Migration Errors

ErrorCauseSolution
Migration failsInvalid SQLReview syntax carefully
Migration skippedIncorrect version numberUse consistent versioning
Duplicate executionChanging existing migration filesNever change files already applied

πŸ” Best Practices for Production

βœ… Always run migrations before app starts (CI/CD).
βœ… Use version control for migration files.
βœ… Never modify applied migrations β€” create new versions for changes.
βœ… Test migrations on staging before production.

🌐 External References

βœ… Summary

  • βœ… Flyway and Liquibase manage your DB schema versions.
  • βœ… Micronaut integrates with both seamlessly.
  • βœ… Pick Flyway for simplicity, Liquibase for complex migrations.
  • βœ… Never rely on hbm2ddl.auto for production.