dbconform 0.1.0__py3-none-any.whl

dbconform/__init__.py

@@ -0,0 +1,24 @@
+"""
+dbconform — conform database schema to models.
+
+Document-driven project; requirements live under docs/requirements/.
+Library API: DbConform(connection=... | credentials=..., target_schema=...),
+compare(models) -> ConformPlan | ConformError, apply_changes(models) to apply.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dbconform")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+from dbconform.conform import DbConform
+from dbconform.errors import ConformError
+from dbconform.plan.steps import ConformPlan
+
+__all__ = [
+    "DbConform",
+    "ConformError",
+    "ConformPlan",
+]

dbconform/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""
+Adapters: third-party models (SQLAlchemy, SQLModel) → internal schema.
+
+See docs/technical/02-architecture.md (Core functions, Adapters).
+"""
+
+from dbconform.adapters.model_schema import ModelSchema
+from dbconform.adapters.sa_to_neutral import sa_column_to_neutral_type
+
+__all__ = [
+    "ModelSchema",
+    "sa_column_to_neutral_type",
+]

dbconform/adapters/model_schema.py

@@ -0,0 +1,219 @@
+"""
+Build internal schema from SQLAlchemy or SQLModel model classes.
+
+Callers pass a single model or sequence of models; we collect their Table
+definitions and build a ModelSchema (name -> TableDef). See docs/requirements/01-functional.md
+(Model discovery and API, Schema parity scope).
+
+**Read-only contract:** Ingestion does not mutate caller models. We only read from
+model.__table__ and its columns/constraints/indexes; we never assign to or modify
+the caller's Table or column objects. ModelSchema stores only internal TableDef
+instances, not references to the original tables.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Protocol
+
+from sqlalchemy import Table
+from sqlalchemy.engine import Dialect
+from sqlalchemy.schema import CheckConstraint, ForeignKeyConstraint, UniqueConstraint
+
+from dbconform.adapters.sa_to_neutral import sa_column_to_neutral_type
+from dbconform.internal.objects import (
+    CheckDef,
+    ColumnDef,
+    ForeignKeyDef,
+    IndexDef,
+    PrimaryKeyDef,
+    QualifiedName,
+    TableDef,
+    UniqueDef,
+)
+
+
+def _get_table_from_model(model: type) -> Table:
+    """Return the SQLAlchemy Table for a declarative or SQLModel class."""
+    table = getattr(model, "__table__", None)
+    if table is None:
+        raise TypeError(f"Model {model!r} has no __table__; not a mapped table class")
+    if not isinstance(table, Table):
+        raise TypeError(f"Model {model!r}.__table__ is not a Table: {type(table)}")
+    return table
+
+
+def _column_type_str(column: Any, dialect: Dialect | None) -> str:
+    """Return neutral type string for internal schema (dialect=None) or compiled type (dialect set)."""
+    if dialect is None:
+        return sa_column_to_neutral_type(column)
+    return column.type.compile(dialect=dialect)
+
+
+def _default_expr(column: Any, _dialect: Dialect) -> str | None:
+    """Return server default expression as string, or None."""
+    default = getattr(column, "server_default", None) or getattr(column, "default", None)
+    if default is None:
+        return None
+    if hasattr(default, "arg") and default.arg is not None:
+        if callable(default.arg):
+            return None  # Python-side default; no DDL expression
+        return str(default.arg)
+    if hasattr(default, "text") and default.text is not None:
+        return default.text
+    return None
+
+
+def _extract_table_def(
+    table: Table,
+    target_schema: str | None,
+    dialect: Dialect | None = None,
+) -> TableDef:
+    """Build a TableDef from a SQLAlchemy Table. When dialect is None, use neutral type names."""
+    schema = table.schema if table.schema is not None else target_schema
+    qualified_name = QualifiedName(schema=schema, name=table.name)
+
+    columns: list[ColumnDef] = []
+    # Only the single integer PK column should have autoincrement=True (SA uses "auto" on others too).
+    is_single_pk = (
+        table.primary_key
+        and len(table.primary_key.columns) == 1
+    )
+    pk_col_name = (
+        list(table.primary_key.columns)[0].name
+        if is_single_pk
+        else None
+    )
+    _integer_type_names = ("Integer", "INTEGER", "BigInteger", "BIGINT", "SmallInteger", "SMALLINT")
+    for col in table.c:
+        default = _default_expr(col, dialect)
+        type_str = _column_type_str(col, dialect)
+        comment = getattr(col, "comment", None)
+        sa_auto = getattr(col, "autoincrement", False)
+        if isinstance(sa_auto, str):
+            sa_auto = sa_auto == "auto"
+        is_pk_col = pk_col_name is not None and col.name == pk_col_name
+        is_integer = type(col.type).__name__ in _integer_type_names
+        autoincrement = bool(
+            is_single_pk and is_pk_col and is_integer and sa_auto
+        )
+        columns.append(
+            ColumnDef(
+                name=col.name,
+                data_type_name=type_str,
+                nullable=col.nullable,
+                default=default,
+                comment=comment,
+                autoincrement=autoincrement,
+            )
+        )
+
+    primary_key: PrimaryKeyDef | None = None
+    if table.primary_key and table.primary_key.columns:
+        primary_key = PrimaryKeyDef(column_names=tuple(c.name for c in table.primary_key.columns))
+
+    unique_constraints: list[UniqueDef] = []
+    foreign_keys: list[ForeignKeyDef] = []
+    check_constraints: list[CheckDef] = []
+
+    for constraint in table.constraints:
+        match constraint:
+            case UniqueConstraint() if constraint is not table.primary_key:
+                unique_constraints.append(
+                    UniqueDef(
+                        name=constraint.name,
+                        column_names=tuple(c.name for c in constraint.columns),
+                    )
+                )
+            case CheckConstraint():
+                expression = str(constraint.sqltext)
+                check_constraints.append(CheckDef(name=constraint.name, expression=expression))
+            case ForeignKeyConstraint():
+                ref_col = next(iter(constraint.elements)).column
+                ref_table = ref_col.table
+                ref_schema = ref_table.schema if ref_table.schema is not None else target_schema
+                ref_name = QualifiedName(schema=ref_schema, name=ref_table.name)
+                foreign_keys.append(
+                    ForeignKeyDef(
+                        name=constraint.name,
+                        column_names=tuple(c.name for c in constraint.columns),
+                        ref_table=ref_name,
+                        ref_column_names=tuple(el.column.name for el in constraint.elements),
+                    )
+                )
+
+    indexes: list[IndexDef] = []
+    for idx in table.indexes:
+        indexes.append(
+            IndexDef(
+                name=idx.name or f"ix_{table.name}_{'_'.join(c.name for c in idx.columns)}",
+                column_names=tuple(c.name for c in idx.columns),
+                unique=idx.unique or False,
+            )
+        )
+
+    comment = getattr(table, "comment", None)
+
+    return TableDef(
+        name=qualified_name,
+        columns=tuple(columns),
+        primary_key=primary_key,
+        unique_constraints=tuple(unique_constraints),
+        foreign_keys=tuple(foreign_keys),
+        check_constraints=tuple(check_constraints),
+        indexes=tuple(indexes),
+        comment=comment,
+    )
+
+
+class _SchemaNormalizer(Protocol):
+    """Protocol for normalizing a TableDef so it compares equal across backends."""
+
+    def normalize_reflected_table(self, table_def: TableDef) -> TableDef: ...
+
+
+class ModelSchema:
+    """
+    Internal schema derived from code models (SQLAlchemy/SQLModel).
+
+    Tables are keyed by QualifiedName. Built by from_models().
+    """
+
+    def __init__(self) -> None:
+        self._tables: dict[QualifiedName, TableDef] = {}
+
+    @property
+    def tables(self) -> dict[QualifiedName, TableDef]:
+        """Tables keyed by qualified name."""
+        return self._tables
+
+    @classmethod
+    def from_models(
+        cls,
+        models: type | Sequence[type],
+        target_schema: str | None = None,
+        *,
+        schema_normalizer: _SchemaNormalizer | None = None,
+    ) -> ModelSchema:
+        """
+        Build ModelSchema from one or more model classes.
+
+        Each model must have __table__ (SQLAlchemy Table). Column types are
+        mapped to neutral type names (no target database). target_schema is
+        used when table.schema is None (e.g. PostgreSQL default schema).
+        If schema_normalizer is provided (e.g. dbconform Dialect), its
+        normalize_reflected_table is applied so model-side internal schema
+        compares equal to database-side internal schema.
+        """
+        if isinstance(models, type):
+            model_seq: Sequence[type] = (models,)
+        else:
+            model_seq = models
+        instance = cls()
+        for model in model_seq:
+            table = _get_table_from_model(model)
+            table_def = _extract_table_def(table, target_schema, dialect=None)
+            if schema_normalizer is not None:
+                table_def = schema_normalizer.normalize_reflected_table(table_def)
+            instance._tables[table_def.name] = table_def
+        return instance

dbconform/adapters/sa_to_neutral.py

@@ -0,0 +1,90 @@
+"""
+Map SQLAlchemy column types to neutral type names (no dialect).
+
+Used when building internal schema from code models so that model-side schema
+does not depend on a target database. See docs/technical/02-architecture.md
+(Types, Internal schema: design goals) and the plan (Option B: neutral type vocabulary).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from dbconform.internal.types import (
+    CanonicalType,
+    canonical_char,
+    canonical_numeric,
+    canonical_varchar,
+)
+
+
+def sa_column_to_neutral_type(column: Any) -> str:
+    """
+    Return the neutral data_type_name for a SQLAlchemy column (no dialect).
+
+    Maps common SQLAlchemy types to the neutral vocabulary (INTEGER, VARCHAR(n),
+    TEXT, FLOAT, BOOLEAN, DATE, TIMESTAMP, NUMERIC(p,s), etc.). Used when building
+    ModelSchema from models so that no target database is assumed.
+    """
+    typ = column.type
+    type_cls = type(typ)
+    name = type_cls.__name__
+
+    if name in ("Integer", "INTEGER"):
+        return CanonicalType.INTEGER
+    if name in ("BigInteger", "BIGINT"):
+        return CanonicalType.BIGINT
+    if name in ("SmallInteger", "SMALLINT"):
+        return CanonicalType.SMALLINT
+    if name in ("Float", "FLOAT", "REAL"):
+        return CanonicalType.FLOAT
+    if name in ("Boolean", "BOOLEAN", "Bool"):
+        return CanonicalType.BOOLEAN
+    if name in ("Text", "TEXT", "CLOB"):
+        return CanonicalType.TEXT
+    if name in ("Date", "DATE", "Date"):
+        return CanonicalType.DATE
+    if name in ("DateTime", "DATETIME", "TIMESTAMP", "DateTime", "Timestamp"):
+        return CanonicalType.TIMESTAMP
+    if name in ("Numeric", "NUMERIC", "Decimal", "DECIMAL"):
+        precision = getattr(typ, "precision", None)
+        scale = getattr(typ, "scale", None)
+        return canonical_numeric(precision, scale)
+    if name in ("String", "VARCHAR", "CHAR", "Unicode"):
+        length = getattr(typ, "length", None)
+        if length is not None:
+            if name in ("CHAR", "Char"):
+                return canonical_char(length)
+            return canonical_varchar(length)
+        return canonical_varchar(255)  # common default when no length
+    if name in ("LargeBinary", "BLOB", "BYTEA"):
+        return CanonicalType.BLOB
+    if name in ("JSON", "JSONB"):
+        return CanonicalType.JSON
+
+    # Fallback: try compile with a generic dialect to get a string, then normalize
+    # so we don't fail on custom or rare types. Use SQLite as a simple dialect.
+    try:
+        from sqlalchemy.dialects import sqlite
+        compiled = typ.compile(dialect=sqlite.dialect())
+        # Normalize common SQLite outputs to neutral
+        c = str(compiled).strip().upper()
+        if c == "INTEGER":
+            return CanonicalType.INTEGER
+        if c in ("REAL", "DOUBLE", "DOUBLE PRECISION"):
+            return CanonicalType.FLOAT
+        if c == "TEXT":
+            return CanonicalType.TEXT
+        if c == "BLOB":
+            return CanonicalType.BLOB
+        if c == "BOOLEAN":
+            return CanonicalType.BOOLEAN
+        if "VARCHAR" in c or "CHAR" in c:
+            m = re.search(r"(\d+)", c)
+            if m:
+                return canonical_varchar(int(m.group(1)))
+            return canonical_varchar(255)
+        return str(compiled)
+    except Exception:
+        return CanonicalType.TEXT  # safe fallback