comdab — Compare Database Schemas

comdab allows you to compare in depth two database schemas to find all differences: missing columns, different nullabilities or defaults, slight changes in function or triggers definitions...

[!WARNING]

comdab is still in development, only tested with PostgreSQL 14 — 18 to date.

All feedback and contributions are welcome!

Installation

Use pip to install comdab:

pip install comdab

Requirements

• Python >= 3.13
• sqlalchemy >= 2.0
• pydantic >= 2.0

Goals

comdab allows you to compare in depth two database schemas to find all differences (missing columns, different nullabilities or defaults, slight changes in function or triggers definitions...) and turn these reports into model migrations.

comdab migration generation supercharges migration tools like Alembic to create migrations that, when applied to an existing database, produce the exact same schema than a new database created from scratch.

Indeed, while migration tools can auto-detect model changes and write automatically the migrations to apply to pre-existing databases, it does not cover the whole schema complexity, and does not prevent human errors (like modifying the model without re-generating migrations, or manually editing migrations in a slightly wrong way...)

This may cause dangerous and hard to spot bugs, especially if your unit tests and CI run on a fresh database created from the Python-written model, and not on pre-existing databases with the new migration applied.

By running comdab, you can ensure the two are the nearly-exact same.

comdab is based on the wonderful SQLAlchemy library to connect to the database, and for most of schema introspection.

Usage

Comparing database schemas

comdab main reporting function is .compare_databases, which needs already established SQLAlchemy connections to the two databases to compare:

from comdab import compare_databases
from sqlalchemy import create_engine

engine_1 = create_engine("postgresql://user:pass@host/foo")
engine_2 = create_engine("postgresql://user:pass@host/bar")

with engine_1.connect() as left_conn, engine_2.connect() as right_conn:
    reports = compare_databases(left_conn, right_conn)

if reports:
    print("❌ Database schemas are different:", reports)
else:
    print("✅ Database schemas are the same!")

Generating migrations

To generate migrations, a user-defined MigrationGeneratorPort / PartialMigrationGeneratorPort subclass is additionally needed:

from comdab import generate_migrations, PartialMigrationGeneratorPort
from comdab.models import ComdabTable
from sqlalchemy import create_engine

class MyMigrationGenerator(PartialMigrationGeneratorPort):
    def __init__(self) -> None:
        self.sql_text = ""

    def create_table(self, *, table: ComdabTable) -> None:
        self.sql_text += f"CREATE TABLE {table.name} [...];\n"

    def drop_table(self, *, table: ComdabTable) -> None:
        self.sql_text += f"DROP TABLE {table.name};\n"

    ...

generator = MyMigrationGenerator()
engine_1 = create_engine("postgresql://user:pass@host/source")
engine_2 = create_engine("postgresql://user:pass@host/target")

with engine_1.connect() as source_conn, engine_2.connect() as target_conn:
    generate_migrations(source_conn, target_conn, generator)

print(generator.sql_text)

Advanced usage

See documentation for configuration and other details.

Contributing

Issues and pull requests are welcome!

License

This work is shared under the MIT license.

@ 2025 Loïc Simon (loic.simon@espci.org)