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.

π§ Why Use Migration Tools?
Problem | Solution |
---|---|
Manual SQL scripts | Version-controlled migrations |
Deployment errors | Auto-run migrations |
Inconsistent schemas | Single source of truth |
Difficult rollback | Versioned rollbacks |
π Option 1: Flyway Integration
π¨ Adding Flyway Dependency
For Maven:
1 2 3 4 5 6 7 |
<dependency> <groupId>io.micronaut.flyway</groupId> <artifactId>micronaut-flyway</artifactId> </dependency> |
β Micronaut will auto-discover Flyway and run migrations at startup.
π¨ Flyway Configuration
Add to application.yml
:
1 2 3 4 5 6 7 |
flyway: datasources: default: enabled: true |
You can configure multiple datasources if needed.
π¨ Create Migration Files
By default, Flyway expects migration files inside:
1 2 3 4 |
src/main/resources/db/migration/ |
Sample Migration: V1__create_students.sql
1 2 3 4 5 6 7 8 9 |
CREATE TABLE students ( id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255) NOT NULL, date_of_birth DATE, email VARCHAR(255) ); |
β
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:
1 2 3 4 5 6 |
Successfully validated 1 migration (execution time 00:00.012s) Current version of schema: 1 Schema version 1 is up to date. No migration necessary. |
β
Flyway maintains a flyway_schema_history
table to track applied migrations.
π Option 2: Liquibase Integration
π¨ Adding Liquibase Dependency
For Maven:
1 2 3 4 5 6 7 |
<dependency> <groupId>io.micronaut.liquibase</groupId> <artifactId>micronaut-liquibase</artifactId> </dependency> |
β Like Flyway, Micronaut automatically configures Liquibase at startup.
π¨ Liquibase Configuration
Add to application.yml
:
1 2 3 4 5 6 7 |
liquibase: datasources: default: enabled: true |
π¨ Create changelog
XML
By default, Liquibase expects changelogs in:
1 2 3 4 |
src/main/resources/db/liquibase/ |
Sample Master Changelog: db-changelog.xml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
<?xml version="1.0" encoding="UTF-8"?> <databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd"> <changeSet id="1" author="kscodes"> <createTable tableName="students"> <column name="id" type="BIGINT" autoIncrement="true"> <constraints primaryKey="true"/> </column> <column name="name" type="VARCHAR(255)"> <constraints nullable="false"/> </column> <column name="date_of_birth" type="DATE"/> <column name="email" type="VARCHAR(255)"/> </createTable> </changeSet> </databaseChangeLog> |
π¨ 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
Feature | Flyway | Liquibase |
---|---|---|
Language | Pure SQL (or Java) | XML, YAML, JSON, SQL |
Learning Curve | Easier | Slightly steeper |
Complex Refactoring | Limited | More powerful |
Community | Very active | Very active |
Micronaut Support | Native | Native |
β Both are excellent; pick based on your teamβs comfort level.
π Common Migration Errors
Error | Cause | Solution |
---|---|---|
Migration fails | Invalid SQL | Review syntax carefully |
Migration skipped | Incorrect version number | Use consistent versioning |
Duplicate execution | Changing existing migration files | Never 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.