pg-schema-diff 0.2.0__py3-none-any.whl

pg_schema_diff-0.2.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: pg-schema-diff
+Version: 0.2.0
+Summary: CLI tool to detect schema drift between PostgreSQL databases and generate safe migration SQL
+Author-email: Asad Shah <asadshah7950@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Asadshah7950/schemadrift
+Project-URL: Repository, https://github.com/Asadshah7950/schemadrift
+Project-URL: Bug Tracker, https://github.com/Asadshah7950/schemadrift/issues
+Keywords: postgresql,schema,migration,diff,database,devops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg2-binary>=2.9.9
+Requires-Dist: click>=8.1.7
+Requires-Dist: rich>=13.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Dynamic: license-file
+
+# schemadrift
+
+> **Detect schema drift between PostgreSQL databases and generate safe, ordered migration SQL — from the command line.**
+
+[![CI](https://github.com/Asadshah7950/schemadrift/actions/workflows/ci.yml/badge.svg)](https://github.com/Asadshah7950/schemadrift/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/schemadrift.svg)](https://pypi.org/project/schemadrift/)
+[![Python versions](https://img.shields.io/pypi/pyversions/schemadrift.svg)](https://pypi.org/project/schemadrift/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Features
+
+- 🔍 **Schema inspection** — Introspects live PostgreSQL databases via `psycopg2` (tables, columns, indexes, foreign keys, enums)
+- 🔄 **Drift detection** — Pure-Python diff engine with zero database dependency for the comparison step
+- 📝 **Safe SQL generation** — Produces `BEGIN`/`COMMIT`-wrapped migration scripts in the correct dependency order (drop FKs first, create tables before adding columns, etc.)
+- 🖥️ **Rich CLI** — Beautiful terminal output powered by [Rich](https://github.com/Textualize/rich)
+- 📦 **Multiple output formats** — SQL, JSON, or human-readable summary
+- ✅ **95%+ unit test coverage** — All core logic tested without a live database
+
+---
+
+## Installation
+
+```bash
+pip install schemadrift
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/Asadshah7950/schemadrift.git
+cd schemadrift
+pip install -e '.[dev]'
+```
+
+---
+
+## Quick Start
+
+### Python API
+
+```python
+from schemadrift.inspector import SchemaInspector
+from schemadrift.differ import SchemaDiffer
+from schemadrift.generator import MigrationGenerator
+
+# Introspect both databases
+source = SchemaInspector("postgres://user:pass@source-host/mydb").snapshot()
+target = SchemaInspector("postgres://user:pass@target-host/mydb").snapshot()
+
+# Compute the diff
+diff = SchemaDiffer(source, target).diff()
+
+# Generate migration SQL
+sql = MigrationGenerator(diff).generate()
+print(sql)
+```
+
+### Output example
+
+```sql
+BEGIN;
+
+-- Drop foreign key: fk_orders_user
+ALTER TABLE "orders" DROP CONSTRAINT "fk_orders_user";
+
+-- Add table: payments
+CREATE TABLE "payments" (
+    "id" integer NOT NULL,
+    "amount" numeric NOT NULL,
+    PRIMARY KEY ("id")
+);
+
+-- Add column: users.phone
+ALTER TABLE "users" ADD COLUMN "phone" text;
+
+-- Add foreign key: fk_orders_user
+ALTER TABLE "orders" ADD CONSTRAINT "fk_orders_user"
+  FOREIGN KEY ("user_id") REFERENCES "users" ("id") ON DELETE NO ACTION;
+
+COMMIT;
+```
+
+---
+
+## CLI Usage
+
+### `diff` — Compare two schemas
+
+```bash
+# Print migration SQL to stdout
+schemadrift diff \
+  --source "postgres://user:pass@source-host/db" \
+  --target "postgres://user:pass@target-host/db"
+
+# Save to a file
+schemadrift diff \
+  --source "postgres://user:pass@source-host/db" \
+  --target "postgres://user:pass@target-host/db" \
+  --output migration.sql
+
+# JSON output
+schemadrift diff \
+  --source "postgres://user:pass@source-host/db" \
+  --target "postgres://user:pass@target-host/db" \
+  --format json
+
+# Human-readable summary
+schemadrift diff \
+  --source "postgres://user:pass@source-host/db" \
+  --target "postgres://user:pass@target-host/db" \
+  --format summary
+
+# GitHub Actions / PR Markdown report
+schemadrift diff \
+  --source "postgres://user:pass@source-host/db" \
+  --target "postgres://user:pass@target-host/db" \
+  --format markdown >> $GITHUB_STEP_SUMMARY
+
+# CI/CD Gate: Fail pipeline (exit code 1) if schema drift is detected
+schemadrift diff \
+  --source "postgres://user:pass@source-host/db" \
+  --target "postgres://user:pass@target-host/db" \
+  --fail-on-drift
+
+# Rollback / down migration (revert target back to source)
+schemadrift diff \
+  --source "postgres://user:pass@source-host/db" \
+  --target "postgres://user:pass@target-host/db" \
+  --direction down \
+  --output rollback.sql
+
+# Non-transactional execution (omit BEGIN / COMMIT)
+schemadrift diff \
+  --source "postgres://user:pass@source-host/db" \
+  --target "postgres://user:pass@target-host/db" \
+  --no-transaction
+
+# Zero-downtime index management (CREATE / DROP INDEX CONCURRENTLY)
+schemadrift diff \
+  --source "postgres://user:pass@source-host/db" \
+  --target "postgres://user:pass@target-host/db" \
+  --concurrently
+```
+
+
+### `inspect` — Print a schema overview
+
+```bash
+schemadrift inspect --dsn "postgres://user:pass@host/db"
+```
+
+Output:
+
+```
+              Schema Summary
+┌──────────────┬─────────┬─────────┐
+│ Table        │ Columns │ Indexes │
+├──────────────┼─────────┼─────────┤
+│ orders       │       6 │       3 │
+│ payments     │       4 │       1 │
+│ users        │       8 │       4 │
+└──────────────┴─────────┴─────────┘
+Foreign keys: 2
+```
+
+---
+
+## Architecture
+
+| Module | Description |
+|---|---|
+| [`schemadrift/models.py`](schemadrift/models.py) | Dataclasses for all schema objects (`ColumnDef`, `TableDef`, `IndexDef`, `ForeignKeyDef`, `SchemaSnapshot`, `DiffResult`) |
+| [`schemadrift/inspector.py`](schemadrift/inspector.py) | `SchemaInspector` — connects to PostgreSQL and builds a `SchemaSnapshot` using `information_schema` and `pg_catalog` queries |
+| [`schemadrift/differ.py`](schemadrift/differ.py) | `SchemaDiffer` — pure-Python comparison engine; no DB connection required |
+| [`schemadrift/generator.py`](schemadrift/generator.py) | `MigrationGenerator` — converts a `DiffResult` into safe, ordered SQL wrapped in a transaction |
+| [`schemadrift/cli.py`](schemadrift/cli.py) | Click CLI exposing `diff` and `inspect` commands with Rich terminal output |
+
+---
+
+## Contributing
+
+Contributions, bug reports, and feature requests are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup instructions.
+
+---
+
+## License
+
+[MIT](LICENSE) © 2024 Asad Shah

pg_schema_diff-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pg_schema_diff-0.2.0.dist-info/licenses/LICENSE,sha256=tIyCf7UMktYxgZqh7Q7VBj9fFU95gw67a2ny_VqjLUA,1066
+schemadrift/__init__.py,sha256=ZI1H1EWBzMmmpiAkQF_GTmDbwlON9IuKK7ABSY_Urz8,133
+schemadrift/cli.py,sha256=cvbsfvZSprDnf2hJ7bsn_4KOtOxcLqlypHoIXroF8GQ,9363
+schemadrift/differ.py,sha256=lmuThsvRD1pWtD3dV9_L-86kP2gBFy4OqJVpkjV21lI,4538
+schemadrift/generator.py,sha256=ovB9snXUNlFCMhv02xeBlGSqhjITBwEJfkeGxLzQRS8,7171
+schemadrift/inspector.py,sha256=0K7zZ5xrrJBQHBN-rypBSTgsPnTGmDOzzxWGa6z5CHU,6186
+schemadrift/models.py,sha256=TFZ7JlR_NH8_8rhTosnJaoWarupLKjyk9tGPML51DKA,2937
+pg_schema_diff-0.2.0.dist-info/METADATA,sha256=vnTAKpiADOFz7QzxSvrobg-15MKs02naOKv7Ce8McYI,7705
+pg_schema_diff-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pg_schema_diff-0.2.0.dist-info/entry_points.txt,sha256=ae4gX3EasGh9bXv9vaZg013LO9IXSrJNW5c1dzOsCJs,53
+pg_schema_diff-0.2.0.dist-info/top_level.txt,sha256=ZxF_yEm1D9MfmfoTtQP3c_8EYvoU79KGDLUb4jXxlI8,12
+pg_schema_diff-0.2.0.dist-info/RECORD,,

pg_schema_diff-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pg_schema_diff-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+schemadrift = schemadrift.cli:main

pg_schema_diff-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Asad Shah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pg_schema_diff-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+schemadrift

schemadrift/__init__.py

@@ -0,0 +1,4 @@
+"""schemadrift: PostgreSQL schema drift detector and migration SQL generator."""
+
+__version__ = "0.2.0"
+__author__ = "Asad Shah"

schemadrift/cli.py

@@ -0,0 +1,250 @@
+"""CLI entry point for pg-schema-diff."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from schemadrift.differ import SchemaDiffer
+from schemadrift.generator import MigrationGenerator
+from schemadrift.inspector import SchemaInspector
+from schemadrift.models import DiffResult
+
+console = Console()
+
+
+@click.group()
+
+@click.version_option()
+def main() -> None:
+    """pg-schema-diff: Detect schema drift between PostgreSQL databases."""
+
+
+# ---------------------------------------------------------------------------
+# diff command
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.option("--source", required=True, help="Source database DSN (e.g. postgres://user:pass@host/db).")
+@click.option("--target", required=True, help="Target database DSN.")
+@click.option("--output", "-o", default=None, help="Write migration SQL to this file path.")
+@click.option(
+    "--format",
+    "fmt",
+    default="sql",
+    type=click.Choice(["sql", "json", "summary", "markdown"]),
+    show_default=True,
+    help="Output format.",
+)
+@click.option(
+    "--direction",
+    "-d",
+    type=click.Choice(["up", "down"]),
+    default="up",
+    show_default=True,
+    help="Migration direction (up=forward source->target, down=rollback target->source).",
+)
+@click.option(
+    "--transaction/--no-transaction",
+    default=True,
+    show_default=True,
+    help="Wrap migration SQL in a BEGIN/COMMIT transaction block.",
+)
+@click.option(
+    "--concurrently",
+    is_flag=True,
+    default=False,
+    help="Create/drop indexes concurrently (disables transaction blocks).",
+)
+@click.option(
+    "--fail-on-drift",
+    is_flag=True,
+    default=False,
+    help="Exit with status code 1 if schema drift is detected (useful for CI/CD checks).",
+)
+def diff(
+    source: str,
+    target: str,
+    output: str | None,
+    fmt: str,
+    direction: str,
+    transaction: bool,
+    concurrently: bool,
+    fail_on_drift: bool,
+) -> None:
+    """Compare SOURCE and TARGET schemas and generate a migration script."""
+    if output or fmt == "summary":
+        console.print("[bold blue]Inspecting source schema…[/bold blue]")
+    try:
+        src_snapshot = SchemaInspector(source).snapshot()
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"Error connecting to source database: {exc}", err=True)
+        sys.exit(1)
+
+    if output or fmt == "summary":
+        console.print("[bold blue]Inspecting target schema…[/bold blue]")
+    try:
+        tgt_snapshot = SchemaInspector(target).snapshot()
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"Error connecting to target database: {exc}", err=True)
+        sys.exit(1)
+
+    if direction == "down":
+        diff_result = SchemaDiffer(tgt_snapshot, src_snapshot).diff()
+    else:
+        diff_result = SchemaDiffer(src_snapshot, tgt_snapshot).diff()
+
+    if fmt == "sql":
+        use_transaction = False if concurrently else transaction
+        content = MigrationGenerator(
+            diff_result,
+            transaction=use_transaction,
+            concurrent_indexes=concurrently,
+        ).generate()
+    elif fmt == "json":
+        content = _diff_to_json(diff_result)
+    elif fmt == "markdown":
+        content = _diff_to_markdown(diff_result)
+    else:  # summary
+        content = _diff_summary(diff_result)
+
+    if output:
+        with open(output, "w", encoding="utf-8") as fh:
+            fh.write(content)
+        console.print(f"[green]Migration written to {output}[/green]")
+    else:
+        click.echo(content)
+
+    if fail_on_drift and diff_result.has_drift:
+        sys.exit(1)
+
+
+
+# ---------------------------------------------------------------------------
+# inspect command
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.option("--dsn", required=True, help="Database DSN to inspect.")
+def inspect(dsn: str) -> None:
+    """Inspect a PostgreSQL schema and print a summary table."""
+    try:
+        snapshot = SchemaInspector(dsn).snapshot()
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"Error connecting to database: {exc}", err=True)
+        sys.exit(1)
+
+    table = Table(title="Schema Summary", show_header=True, header_style="bold magenta")
+    table.add_column("Table", style="cyan", no_wrap=True)
+    table.add_column("Columns", justify="right")
+    table.add_column("Indexes", justify="right")
+
+    for tbl_name, tbl in sorted(snapshot.tables.items()):
+        table.add_row(tbl_name, str(len(tbl.columns)), str(len(tbl.indexes)))
+
+    console.print(table)
+
+    if snapshot.enums:
+        console.print(f"\n[bold]Enums ({len(snapshot.enums)}):[/bold] " + ", ".join(snapshot.enums))
+
+    if snapshot.foreign_keys:
+        console.print(f"[bold]Foreign keys:[/bold] {len(snapshot.foreign_keys)}")
+
+
+# ---------------------------------------------------------------------------
+# Formatters
+# ---------------------------------------------------------------------------
+
+
+def _diff_to_json(diff_result: DiffResult) -> str:
+    """Serialize the diff result to a JSON string."""
+    data = {
+        "tables_added": [t.name for t in diff_result.tables_added],
+        "tables_dropped": list(diff_result.tables_dropped),
+        "columns_added": [
+            {"table": t, "column": c.name, "type": c.data_type}
+            for t, c in diff_result.columns_added
+        ],
+        "columns_dropped": [
+            {"table": t, "column": c} for t, c in diff_result.columns_dropped
+        ],
+        "columns_altered": [
+            {"table": t, "column": s.name, "from_type": s.data_type, "to_type": g.data_type}
+            for t, s, g in diff_result.columns_altered
+        ],
+        "indexes_added": [i.name for i in diff_result.indexes_added],
+        "indexes_dropped": [i.name for i in diff_result.indexes_dropped],
+        "fks_added": [fk.name for fk in diff_result.fks_added],
+        "fks_dropped": [fk.name for fk in diff_result.fks_dropped],
+    }
+    return json.dumps(data, indent=2)
+
+
+def _diff_summary(diff_result: DiffResult) -> str:
+    """Return a human-readable plain-text summary of the diff."""
+    lines = ["Schema Diff Summary", "=" * 40]
+    lines.append(f"Tables added:    {len(diff_result.tables_added)}")
+    lines.append(f"Tables dropped:  {len(diff_result.tables_dropped)}")
+    lines.append(f"Columns added:   {len(diff_result.columns_added)}")
+    lines.append(f"Columns dropped: {len(diff_result.columns_dropped)}")
+    lines.append(f"Columns altered: {len(diff_result.columns_altered)}")
+    lines.append(f"Indexes added:   {len(diff_result.indexes_added)}")
+    lines.append(f"Indexes dropped: {len(diff_result.indexes_dropped)}")
+    lines.append(f"FKs added:       {len(diff_result.fks_added)}")
+    lines.append(f"FKs dropped:     {len(diff_result.fks_dropped)}")
+    return "\n".join(lines)
+
+
+def _md_row(label: str, badge: str, items: list[str]) -> str:
+    details = ", ".join(items)
+    return f"| **{label}** | {badge} | `{len(items)}` | {details} |"
+
+
+
+def _diff_to_markdown(diff_result: DiffResult) -> str:
+    """Serialize the diff result to a GitHub-flavored Markdown report."""
+    if not diff_result.has_drift:
+        return "### 🟢 Schema Diff: No Changes Detected\n\nDatabase schemas are in sync."
+
+    lines = [
+        "### 🔍 PostgreSQL Schema Drift Report\n",
+        "| Component | Status | Count | Details |",
+        "| :--- | :--- | :---: | :--- |",
+    ]
+    if diff_result.tables_added:
+        items = [f"`{t.name}`" for t in diff_result.tables_added]
+        lines.append(_md_row("Tables Added", "🟢 Added", items))
+    if diff_result.tables_dropped:
+        items = [f"`{t}`" for t in diff_result.tables_dropped]
+        lines.append(_md_row("Tables Dropped", "🔴 Dropped", items))
+    if diff_result.columns_added:
+        items = [f"`{t}.{c.name}`" for t, c in diff_result.columns_added]
+        lines.append(_md_row("Columns Added", "🟢 Added", items))
+    if diff_result.columns_dropped:
+        items = [f"`{t}.{c}`" for t, c in diff_result.columns_dropped]
+        lines.append(_md_row("Columns Dropped", "🔴 Dropped", items))
+    if diff_result.columns_altered:
+        items = [f"`{t}.{s.name}`" for t, s, _ in diff_result.columns_altered]
+        lines.append(_md_row("Columns Altered", "🟡 Altered", items))
+    if diff_result.indexes_added:
+        items = [f"`{i.name}`" for i in diff_result.indexes_added]
+        lines.append(_md_row("Indexes Added", "🟢 Added", items))
+    if diff_result.indexes_dropped:
+        items = [f"`{i.name}`" for i in diff_result.indexes_dropped]
+        lines.append(_md_row("Indexes Dropped", "🔴 Dropped", items))
+    if diff_result.fks_added:
+        items = [f"`{fk.name}`" for fk in diff_result.fks_added]
+        lines.append(_md_row("Foreign Keys Added", "🟢 Added", items))
+    if diff_result.fks_dropped:
+        items = [f"`{fk.name}`" for fk in diff_result.fks_dropped]
+        lines.append(_md_row("Foreign Keys Dropped", "🔴 Dropped", items))
+
+    return "\n".join(lines)
+
+

schemadrift/differ.py

@@ -0,0 +1,130 @@
+"""Schema differ: compares two SchemaSnapshot objects and produces a DiffResult."""
+
+from __future__ import annotations
+
+from schemadrift.models import (
+    ColumnDef,
+    DiffResult,
+    SchemaSnapshot,
+    TableDef,
+)
+
+
+class SchemaDiffer:
+    """Compares a source and target SchemaSnapshot and returns a DiffResult."""
+
+    def __init__(self, source: SchemaSnapshot, target: SchemaSnapshot) -> None:
+        self.source = source
+        self.target = target
+
+    def diff(self) -> DiffResult:
+        """Compare source vs target and return all detected differences."""
+        result = DiffResult()
+
+        self._diff_tables(result)
+        self._diff_foreign_keys(result)
+        self._diff_enums(result)
+
+        return result
+
+    def _diff_tables(self, result: DiffResult) -> None:
+        src_tables = self.source.tables
+        tgt_tables = self.target.tables
+
+        src_names = set(src_tables.keys())
+        tgt_names = set(tgt_tables.keys())
+
+        # Tables in target that don't exist in source → added
+        for name in tgt_names - src_names:
+            result.tables_added.append(tgt_tables[name])
+
+        # Tables in source that don't exist in target → dropped
+        for name in src_names - tgt_names:
+            result.tables_dropped.append(name)
+
+        # Tables in both → compare columns and indexes
+        for name in src_names & tgt_names:
+            self._diff_columns(result, name, src_tables[name], tgt_tables[name])
+            self._diff_indexes(result, src_tables[name], tgt_tables[name])
+
+    def _diff_columns(
+        self,
+        result: DiffResult,
+        table_name: str,
+        src_table: TableDef,
+        tgt_table: TableDef,
+    ) -> None:
+        src_cols = {c.name: c for c in src_table.columns}
+        tgt_cols = {c.name: c for c in tgt_table.columns}
+
+        src_col_names = set(src_cols.keys())
+        tgt_col_names = set(tgt_cols.keys())
+
+        # Columns in target not in source → added
+        for col_name in tgt_col_names - src_col_names:
+            result.columns_added.append((table_name, tgt_cols[col_name]))
+
+        # Columns in source not in target → dropped
+        for col_name in src_col_names - tgt_col_names:
+            result.columns_dropped.append((table_name, col_name))
+
+        # Columns in both → check for alterations
+        for col_name in src_col_names & tgt_col_names:
+            src_col = src_cols[col_name]
+            tgt_col = tgt_cols[col_name]
+            if self._column_changed(src_col, tgt_col):
+                result.columns_altered.append((table_name, src_col, tgt_col))
+
+    @staticmethod
+    def _column_changed(src: ColumnDef, tgt: ColumnDef) -> bool:
+        """Return True if anything meaningful changed on a column."""
+        return (
+            src.data_type != tgt.data_type
+            or src.nullable != tgt.nullable
+            or src.default != tgt.default
+        )
+
+    def _diff_indexes(
+        self,
+        result: DiffResult,
+        src_table: TableDef,
+        tgt_table: TableDef,
+    ) -> None:
+        src_idx = {i.name: i for i in src_table.indexes}
+        tgt_idx = {i.name: i for i in tgt_table.indexes}
+
+        src_names = set(src_idx.keys())
+        tgt_names = set(tgt_idx.keys())
+
+        for name in tgt_names - src_names:
+            result.indexes_added.append(tgt_idx[name])
+
+        for name in src_names - tgt_names:
+            result.indexes_dropped.append(src_idx[name])
+
+    def _diff_foreign_keys(self, result: DiffResult) -> None:
+        src_fks = {fk.name: fk for fk in self.source.foreign_keys}
+        tgt_fks = {fk.name: fk for fk in self.target.foreign_keys}
+
+        src_names = set(src_fks.keys())
+        tgt_names = set(tgt_fks.keys())
+
+        for name in tgt_names - src_names:
+            result.fks_added.append(tgt_fks[name])
+
+        for name in src_names - tgt_names:
+            result.fks_dropped.append(src_fks[name])
+
+    def _diff_enums(self, result: DiffResult) -> None:
+        src_enums = self.source.enums
+        tgt_enums = self.target.enums
+
+        src_names = set(src_enums.keys())
+        tgt_names = set(tgt_enums.keys())
+
+        for name in tgt_names - src_names:
+            result.enums_added.append((name, tgt_enums[name]))
+
+        for name in src_names & tgt_names:
+            if src_enums[name] != tgt_enums[name]:
+                result.enums_altered.append((name, src_enums[name], tgt_enums[name]))

schemadrift/generator.py

@@ -0,0 +1,191 @@
+"""Migration SQL generator: turns a DiffResult into a safe, ordered SQL script."""
+
+from __future__ import annotations
+
+from schemadrift.models import ColumnDef, DiffResult, TableDef
+
+
+class MigrationGenerator:
+    """Generates an ordered SQL migration script from a DiffResult."""
+
+    def __init__(
+        self,
+        diff: DiffResult,
+        transaction: bool | None = None,
+        concurrent_indexes: bool = False,
+    ) -> None:
+        self.diff = diff
+        self.concurrent_indexes = concurrent_indexes
+        if transaction is None:
+            self.transaction = not concurrent_indexes
+        else:
+            self.transaction = transaction
+
+    def generate(self) -> str:
+        """
+        Return a full SQL migration script.
+
+        Order of operations (safe for FK/index dependencies):
+        1. DROP foreign keys
+        2. DROP indexes
+        3. ALTER / DROP columns
+        4. DROP tables
+        5. CREATE tables
+        6. ADD columns
+        7. CREATE indexes
+        8. ADD foreign keys
+        """
+        if self.diff.is_empty():
+            if self.transaction:
+                return "BEGIN;\n-- No schema differences detected.\nCOMMIT;\n"
+            return "-- No schema differences detected.\n"
+
+        statements: list[str] = []
+
+        # 1. DROP foreign keys
+        for fk in self.diff.fks_dropped:
+            statements.append(
+                f"-- Drop foreign key: {fk.name}\n"
+                f"ALTER TABLE {_q(fk.table)} DROP CONSTRAINT {_q(fk.name)};"
+            )
+
+        # 2. DROP indexes
+        for idx in self.diff.indexes_dropped:
+            concurrent_kw = "CONCURRENTLY " if self.concurrent_indexes else ""
+            statements.append(
+                f"-- Drop index: {idx.name}\n"
+                f"DROP INDEX {concurrent_kw}IF EXISTS {_q(idx.name)};"
+            )
+
+        # 3. ALTER columns (type changes), DROP columns
+        for table_name, src_col, tgt_col in self.diff.columns_altered:
+            statements.extend(_alter_column_statements(table_name, src_col, tgt_col))
+
+        for table_name, col_name in self.diff.columns_dropped:
+            statements.append(
+                f"-- Drop column: {table_name}.{col_name}\n"
+                f"ALTER TABLE {_q(table_name)} DROP COLUMN IF EXISTS {_q(col_name)};"
+            )
+
+        # 4. DROP tables
+        for table_name in self.diff.tables_dropped:
+            statements.append(
+                f"-- Drop table: {table_name}\nDROP TABLE IF EXISTS {_q(table_name)};"
+            )
+
+        # 5. CREATE tables
+        for table in self.diff.tables_added:
+            statements.append(_create_table_statement(table))
+
+        # 6. ADD columns
+        for table_name, col in self.diff.columns_added:
+            statements.append(
+                f"-- Add column: {table_name}.{col.name}\n"
+                f"ALTER TABLE {_q(table_name)} ADD COLUMN {_column_def_sql(col)};"
+            )
+
+        # 7. CREATE indexes
+        for idx in self.diff.indexes_added:
+            unique_kw = "UNIQUE " if idx.unique else ""
+            concurrent_kw = "CONCURRENTLY " if self.concurrent_indexes else ""
+            cols = ", ".join(_q(c) for c in idx.columns)
+            statements.append(
+                f"-- Add index: {idx.name}\n"
+                f"CREATE {unique_kw}INDEX {concurrent_kw}{_q(idx.name)} ON {_q(idx.table)} "
+                f"USING {idx.method} ({cols});"
+            )
+
+        # 8. ADD foreign keys
+        for fk in self.diff.fks_added:
+            src_cols = ", ".join(_q(c) for c in fk.columns)
+            ref_cols = ", ".join(_q(c) for c in fk.ref_columns)
+            statements.append(
+                f"-- Add foreign key: {fk.name}\n"
+                f"ALTER TABLE {_q(fk.table)} ADD CONSTRAINT {_q(fk.name)} "
+                f"FOREIGN KEY ({src_cols}) REFERENCES {_q(fk.ref_table)} ({ref_cols}) "
+                f"ON DELETE {fk.on_delete};"
+            )
+
+        # 9. Enum additions (informational – add values)
+        for enum_name, labels in self.diff.enums_added:
+            for label in labels:
+                statements.append(
+                    f"-- Add enum value to {enum_name}\n"
+                    f"ALTER TYPE {_q(enum_name)} ADD VALUE IF NOT EXISTS '{label}';"
+                )
+
+        body = "\n\n".join(statements)
+        if self.transaction:
+            return f"BEGIN;\n\n{body}\n\nCOMMIT;\n"
+        return f"{body}\n"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _q(name: str) -> str:
+    """Quote a PostgreSQL identifier."""
+    return f'"{name}"'
+
+
+def _column_def_sql(col: ColumnDef) -> str:
+    """Return the SQL fragment for a column definition (name type [NOT NULL] [DEFAULT ...])."""
+    parts = [_q(col.name), col.data_type]
+    if not col.nullable:
+        parts.append("NOT NULL")
+    if col.default is not None:
+        parts.append(f"DEFAULT {col.default}")
+    return " ".join(parts)
+
+
+def _create_table_statement(table: TableDef) -> str:
+    """Return a CREATE TABLE SQL statement for the given TableDef."""
+    col_lines = []
+    pk_cols = [c.name for c in table.columns if c.is_primary_key]
+
+    for col in table.columns:
+        col_lines.append(f"    {_column_def_sql(col)}")
+
+    if pk_cols:
+        pk_list = ", ".join(_q(c) for c in pk_cols)
+        col_lines.append(f"    PRIMARY KEY ({pk_list})")
+
+    cols_sql = ",\n".join(col_lines)
+    return f"-- Add table: {table.name}\nCREATE TABLE {_q(table.name)} (\n{cols_sql}\n);"
+
+
+def _alter_column_statements(table_name: str, src: ColumnDef, tgt: ColumnDef) -> list[str]:
+    """Return ALTER TABLE statements needed to transition src column to tgt column."""
+    stmts = []
+    if src.data_type != tgt.data_type:
+        stmts.append(
+            f"-- Alter column type: {table_name}.{tgt.name}\n"
+            f"ALTER TABLE {_q(table_name)} ALTER COLUMN {_q(tgt.name)} "
+            f"TYPE {tgt.data_type};"
+        )
+    if src.nullable != tgt.nullable:
+        if tgt.nullable:
+            stmts.append(
+                f"-- Allow NULL: {table_name}.{tgt.name}\n"
+                f"ALTER TABLE {_q(table_name)} ALTER COLUMN {_q(tgt.name)} DROP NOT NULL;"
+            )
+        else:
+            stmts.append(
+                f"-- Set NOT NULL: {table_name}.{tgt.name}\n"
+                f"ALTER TABLE {_q(table_name)} ALTER COLUMN {_q(tgt.name)} SET NOT NULL;"
+            )
+    if src.default != tgt.default:
+        if tgt.default is None:
+            stmts.append(
+                f"-- Drop default: {table_name}.{tgt.name}\n"
+                f"ALTER TABLE {_q(table_name)} ALTER COLUMN {_q(tgt.name)} DROP DEFAULT;"
+            )
+        else:
+            stmts.append(
+                f"-- Set default: {table_name}.{tgt.name}\n"
+                f"ALTER TABLE {_q(table_name)} ALTER COLUMN {_q(tgt.name)} "
+                f"SET DEFAULT {tgt.default};"
+            )
+    return stmts

schemadrift/inspector.py

@@ -0,0 +1,185 @@
+"""Schema inspector: connects to PostgreSQL and produces a SchemaSnapshot."""
+
+from __future__ import annotations
+
+import re
+
+import psycopg2
+import psycopg2.extras
+
+from schemadrift.models import (
+    ColumnDef,
+    ForeignKeyDef,
+    IndexDef,
+    SchemaSnapshot,
+    TableDef,
+)
+
+_SQL_TABLES = """
+SELECT table_name
+FROM information_schema.tables
+WHERE table_schema = 'public'
+  AND table_type = 'BASE TABLE'
+ORDER BY table_name;
+"""
+
+_SQL_COLUMNS = """
+SELECT column_name, data_type, is_nullable, column_default
+FROM information_schema.columns
+WHERE table_schema = 'public'
+  AND table_name = %s
+ORDER BY ordinal_position;
+"""
+
+_SQL_PRIMARY_KEYS = """
+SELECT kcu.column_name
+FROM information_schema.table_constraints tc
+JOIN information_schema.key_column_usage kcu
+  ON tc.constraint_name = kcu.constraint_name
+  AND tc.table_schema = kcu.table_schema
+WHERE tc.constraint_type = 'PRIMARY KEY'
+  AND tc.table_schema = 'public'
+  AND tc.table_name = %s;
+"""
+
+_SQL_INDEXES = """
+SELECT indexname, indexdef
+FROM pg_indexes
+WHERE schemaname = 'public'
+  AND tablename = %s;
+"""
+
+_SQL_FOREIGN_KEYS = """
+SELECT
+    rc.constraint_name,
+    kcu.table_name,
+    kcu.column_name,
+    ccu.table_name  AS ref_table,
+    ccu.column_name AS ref_column,
+    rc.delete_rule
+FROM information_schema.referential_constraints rc
+JOIN information_schema.key_column_usage kcu
+  ON rc.constraint_name = kcu.constraint_name
+  AND rc.constraint_schema = kcu.constraint_schema
+JOIN information_schema.constraint_column_usage ccu
+  ON rc.unique_constraint_name = ccu.constraint_name
+  AND rc.unique_constraint_schema = ccu.constraint_schema
+WHERE rc.constraint_schema = 'public'
+ORDER BY rc.constraint_name, kcu.ordinal_position;
+"""
+
+_SQL_ENUMS = """
+SELECT t.typname, e.enumlabel
+FROM pg_type t
+JOIN pg_enum e ON t.oid = e.enumtypid
+JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+WHERE n.nspname = 'public'
+ORDER BY t.typname, e.enumsortorder;
+"""
+
+
+def _parse_index_columns(indexdef: str) -> list[str]:
+    """Extract column names from an index definition string."""
+    match = re.search(r"\((.+)\)$", indexdef)
+    if not match:
+        return []
+    raw = match.group(1)
+    return [col.strip().split()[0] for col in raw.split(",")]
+
+
+class SchemaInspector:
+    """Inspects a live PostgreSQL schema and returns a SchemaSnapshot."""
+
+    def __init__(self, dsn: str) -> None:
+        """Store DSN; no connection is made until snapshot() is called."""
+        self.dsn = dsn
+
+    def snapshot(self) -> SchemaSnapshot:
+        """Connect to the database and return a full SchemaSnapshot."""
+        conn = psycopg2.connect(self.dsn)
+        try:
+            return self._build_snapshot(conn)
+        finally:
+            conn.close()
+
+    def _build_snapshot(self, conn: psycopg2.connection) -> SchemaSnapshot:
+        with conn.cursor() as cur:
+            tables = self._fetch_tables(cur)
+            foreign_keys = self._fetch_foreign_keys(cur)
+            enums = self._fetch_enums(cur)
+        return SchemaSnapshot(tables=tables, foreign_keys=foreign_keys, enums=enums)
+
+    def _fetch_tables(self, cur: psycopg2.cursor) -> dict[str, TableDef]:
+        cur.execute(_SQL_TABLES)
+        table_names = [row[0] for row in cur.fetchall()]
+        tables: dict[str, TableDef] = {}
+        for name in table_names:
+            columns = self._fetch_columns(cur, name)
+            indexes = self._fetch_indexes(cur, name)
+            tables[name] = TableDef(name=name, columns=columns, indexes=indexes)
+        return tables
+
+    def _fetch_columns(self, cur: psycopg2.cursor, table: str) -> list[ColumnDef]:
+        cur.execute(_SQL_COLUMNS, (table,))
+        rows = cur.fetchall()
+
+        cur.execute(_SQL_PRIMARY_KEYS, (table,))
+        pk_cols = {row[0] for row in cur.fetchall()}
+
+        columns = []
+        for col_name, data_type, is_nullable, col_default in rows:
+            columns.append(
+                ColumnDef(
+                    name=col_name,
+                    data_type=data_type,
+                    nullable=(is_nullable == "YES"),
+                    default=col_default,
+                    is_primary_key=(col_name in pk_cols),
+                )
+            )
+        return columns
+
+    def _fetch_indexes(self, cur: psycopg2.cursor, table: str) -> list[IndexDef]:
+        cur.execute(_SQL_INDEXES, (table,))
+        indexes = []
+        for indexname, indexdef in cur.fetchall():
+            unique = "UNIQUE" in indexdef.upper()
+            method_match = re.search(r"USING\s+(\w+)", indexdef, re.IGNORECASE)
+            method = method_match.group(1).lower() if method_match else "btree"
+            columns = _parse_index_columns(indexdef)
+            indexes.append(
+                IndexDef(
+                    name=indexname,
+                    table=table,
+                    columns=columns,
+                    unique=unique,
+                    method=method,
+                )
+            )
+        return indexes
+
+    def _fetch_foreign_keys(self, cur: psycopg2.cursor) -> list[ForeignKeyDef]:
+        cur.execute(_SQL_FOREIGN_KEYS)
+        rows = cur.fetchall()
+
+        fks: dict[str, ForeignKeyDef] = {}
+        for constraint_name, table, column, ref_table, ref_col, delete_rule in rows:
+            if constraint_name not in fks:
+                fks[constraint_name] = ForeignKeyDef(
+                    name=constraint_name,
+                    table=table,
+                    columns=[],
+                    ref_table=ref_table,
+                    ref_columns=[],
+                    on_delete=delete_rule,
+                )
+            fks[constraint_name].columns.append(column)
+            fks[constraint_name].ref_columns.append(ref_col)
+        return list(fks.values())
+
+    def _fetch_enums(self, cur: psycopg2.cursor) -> dict[str, list[str]]:
+        cur.execute(_SQL_ENUMS)
+        enums: dict[str, list[str]] = {}
+        for typname, enumlabel in cur.fetchall():
+            enums.setdefault(typname, []).append(enumlabel)
+        return enums

schemadrift/models.py

@@ -0,0 +1,96 @@
+"""Data models for pg-schema-diff schema objects and diff results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ColumnDef:
+    """Represents a single column in a PostgreSQL table."""
+
+    name: str
+    data_type: str
+    nullable: bool = True
+    default: str | None = None
+    is_primary_key: bool = False
+
+
+@dataclass
+class IndexDef:
+    """Represents a PostgreSQL index on a table."""
+
+    name: str
+    table: str
+    columns: list[str]
+    unique: bool = False
+    method: str = "btree"
+
+
+@dataclass
+class TableDef:
+    """Represents a PostgreSQL table with its columns and indexes."""
+
+    name: str
+    columns: list[ColumnDef] = field(default_factory=list)
+    indexes: list[IndexDef] = field(default_factory=list)
+
+
+@dataclass
+class ForeignKeyDef:
+    """Represents a foreign key constraint."""
+
+    name: str
+    table: str
+    columns: list[str]
+    ref_table: str
+    ref_columns: list[str]
+    on_delete: str = "NO ACTION"
+
+
+@dataclass
+class SchemaSnapshot:
+    """A complete snapshot of a PostgreSQL schema."""
+
+    tables: dict[str, TableDef] = field(default_factory=dict)
+    foreign_keys: list[ForeignKeyDef] = field(default_factory=list)
+    enums: dict[str, list[str]] = field(default_factory=dict)
+
+
+@dataclass
+class DiffResult:
+    """The result of comparing two SchemaSnapshot objects."""
+
+    tables_added: list[TableDef] = field(default_factory=list)
+    tables_dropped: list[str] = field(default_factory=list)
+    columns_added: list[tuple[str, ColumnDef]] = field(default_factory=list)
+    columns_dropped: list[tuple[str, str]] = field(default_factory=list)
+    columns_altered: list[tuple[str, ColumnDef, ColumnDef]] = field(default_factory=list)
+    indexes_added: list[IndexDef] = field(default_factory=list)
+    indexes_dropped: list[IndexDef] = field(default_factory=list)
+    fks_added: list[ForeignKeyDef] = field(default_factory=list)
+    fks_dropped: list[ForeignKeyDef] = field(default_factory=list)
+    enums_added: list[tuple[str, list[str]]] = field(default_factory=list)
+    enums_altered: list[tuple[str, list[str], list[str]]] = field(default_factory=list)
+
+    def is_empty(self) -> bool:
+        """Return True if there are no detected differences."""
+        return (
+            not self.tables_added
+            and not self.tables_dropped
+            and not self.columns_added
+            and not self.columns_dropped
+            and not self.columns_altered
+            and not self.indexes_added
+            and not self.indexes_dropped
+            and not self.fks_added
+            and not self.fks_dropped
+            and not self.enums_added
+            and not self.enums_altered
+        )
+
+    @property
+    def has_drift(self) -> bool:
+        """Return True if schema drift is detected."""
+        return not self.is_empty()
+