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!
Use pip to install comdab:
pip install comdab- Python
>= 3.13 - sqlalchemy
>= 2.0 - pydantic
>= 2.0
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.
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!")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)See documentation for configuration and other details.
Issues and pull requests are welcome!
This work is shared under the MIT license.
@ 2025 Loïc Simon (loic.simon@espci.org)