丁久

Posted on May 16 • Originally published at dingjiu1989-hue.github.io

Database Migration Tools: Alembic, Flyway, Liquibase, Versioning

#database #backend #data

This article was originally published on AI Study Room. For the full version with working code examples and related articles, visit the original post.

Database Migration Tools: Alembic, Flyway, Liquibase, Versioning

Database migrations are the practice of version-controlling schema changes. A good migration tool applies changes in order, handles conflicts, and supports rollback. This article compares the three leading tools and covers migration strategies.

Why Migrations?

Without migrations, schema changes are applied manually or through ad-hoc scripts:

"Did we run the ALTER TABLE on staging?"
"Which servers have the new index?"
"The deploy failed because the migration hadn't run yet."

Migrations solve these problems by making schema changes repeatable, versioned, and automated.

Alembic

Alembic is the migration tool for SQLAlchemy (Python). It generates migration scripts from model definitions and supports auto-generation.

Setup

alembic.ini

[alembic]

script_location = alembic

sqlalchemy.url = postgresql://user:pass@localhost/mydb

alembic init alembic

Creating a Migration

alembic/versions/0001_create_users.py

"""create users table

Revision ID: 0001

Revises: None

Create Date: 2026-05-12

"""

from alembic import op

import sqlalchemy as sa

def upgrade():

op.create_table(

'users',

sa.Column('id', sa.Integer(), primary_key=True),

sa.Column('email', sa.String(255), nullable=False),

sa.Column('name', sa.String(100)),

sa.Column('created_at', sa.DateTime(), server_default=sa.func.now()),

)

op.create_index('idx_users_email', 'users', ['email'], unique=True)

def downgrade():

op.drop_index('idx_users_email')

op.drop_table('users')

Auto-Generation

Generate migration from model changes

alembic revision --autogenerate -m "add avatar column"

This compares the current database state against SQLAlchemy models and generates upgrade() and downgrade() functions.

Running Migrations

alembic upgrade head # Apply all pending migrations

alembic upgrade +2 # Apply next 2 migrations

alembic downgrade -1 # Rollback 1 migration

alembic history # View migration history

alembic current # Show current revision

Flyway

Flyway is a Java-based migration tool that works with SQL scripts. It is simple, opinionated, and supports multiple databases.

Directory Structure

sql/

V1__create_users.sql

V2__add_avatar_column.sql

V3__create_orders_table.sql

Migration Script

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\-- V1__create_users.sql

CREATE TABLE users (

id BIGSERIAL PRIMARY KEY,

email VARCHAR(255) NOT NULL UNIQUE,

name VARCHAR(100),

created_at TIMESTAMPTZ DEFAULT NOW()

);

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\-- V2__add_avatar_column.sql

ALTER TABLE users ADD COLUMN avatar_url VARCHAR(500);

Configuration

flyway.conf

flyway.url = jdbc:postgresql://localhost:5432/mydb

flyway.user = app_user

flyway.password = secure_password

flyway.locations = filesystem:sql

flyway.baselineOnMigrate = true

Running

flyway migrate

flyway undo # Flyway Teams only

flyway info # Show migration status

flyway validate # Check for changes to applied migrations

Checksum Validation

Flyway stores a checksum of each migration script. If a script is modified after being applied, flyway validate detects the change and warns:

If a deployed migration is edited, Flyway catches it and refuses to apply further migrations until the discrepancy is resolved.

Liquibase

Liquibase supports multiple change formats: SQL, XML, YAML, and JSON. It is the most flexible but most verbose option.

Changeset (XML)

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/n

Read the full article on AI Study Room for complete code examples, comparison tables, and related resources.

Found this useful? Check out more developer guides and tool comparisons on AI Study Room.

DEV Community

Database Migration Tools: Alembic, Flyway, Liquibase, Versioning

Database Migration Tools: Alembic, Flyway, Liquibase, Versioning