ferrum-orm 0.1.7__tar.gz → 0.1.9__tar.gz

{ferrum_orm-0.1.7 → ferrum_orm-0.1.9}/Cargo.lock

@@ -174,9 +174,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-epoch"
-version = "0.9.18"
+version = "0.9.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
 dependencies = [
  "crossbeam-utils",
 ]
@@ -223,7 +223,7 @@ checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "ferrum-core"
-version = "0.1.6"
+version = "0.1.9"
 dependencies = [
  "criterion",
  "proptest",
@@ -234,7 +234,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-migrate"
-version = "0.1.6"
+version = "0.1.9"
 dependencies = [
  "ferrum-core",
  "serde",
@@ -243,7 +243,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-pyo3"
-version = "0.1.6"
+version = "0.1.9"
 dependencies = [
  "ferrum-core",
  "ferrum-sql",
@@ -255,7 +255,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-sql"
-version = "0.1.6"
+version = "0.1.9"
 dependencies = [
  "criterion",
  "ferrum-core",

{ferrum_orm-0.1.7 → ferrum_orm-0.1.9}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferrum-core", "crates/ferrum-sql", "crates/ferrum-pyo3"]
 resolver = "2"
 
 [workspace.package]
-version = "0.1.6"
+version = "0.1.9"
 edition = "2021"
 authors = ["Ferrum Contributors"]
 license = "Apache-2.0"

{ferrum_orm-0.1.7 → ferrum_orm-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferrum-orm
-Version: 0.1.7
+Version: 0.1.9
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -121,6 +121,14 @@ user = await User.objects.create(
     email="john@example.com",
 )
 
+# Insert from an instance (sentinel PK is dropped so the DB default runs)
+draft = User(id=0, email="dana@example.com")
+created = await User.objects.create(conn, draft)
+
+# Persist one instance's changes by primary key
+created.is_active = False
+await User.objects.update_instance(conn, created, fields=["is_active"])
+
 users = await (
     User.objects
     .filter(is_active=True)
@@ -160,6 +168,49 @@ class User(Model):
 
 No duplicate schema definitions.
 
+### Field Options
+
+`ferrum.Field()` accepts column-level constraints that are carried through to DDL:
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `db_default` | `str \| None` | DB-side `DEFAULT` expression (e.g. `"NOW()"`, `"''"`, `"GEN_RANDOM_UUID()"`). Token casing is normalised (`now()` → `NOW()`). |
+| `nullable` | `bool \| None` | Override annotation-derived nullability. Use `nullable=False` to force `NOT NULL` even on a `T \| None`-annotated field. |
+| `db_index` | `bool` | Emit a `CREATE INDEX` on this column (auto-named `idx_{table}_{field}`). |
+| `unique` | `bool` | Emit a `UNIQUE` constraint. |
+| `db_column` | `str \| None` | Override the database column name. |
+| `primary_key` | `bool` | Declare this field as the primary key. |
+| `uuid_generate` | `"v4" \| "v7" \| None` | Set `GEN_RANDOM_UUID()` / `UUIDV7()` as the DB default for UUID PK columns. |
+| `max_length` | `int \| None` | Emit `VARCHAR(n)` instead of `TEXT`. |
+| `max_digits` / `decimal_places` | `int \| None` | Emit `NUMERIC(p,s)`. |
+| `vector_dimensions` | `int \| None` | Required for `Vector` columns; emits `VECTOR(n)`. |
+
+```python
+from datetime import datetime
+from typing import Annotated
+from ferrum import Model, Field
+
+class Event(Model):
+    id: int
+    # DB-side timestamp default; Python annotation allows None but column is NOT NULL
+    created_at: Annotated[datetime | None, Field(db_default="now()", nullable=False)]
+    # Indexed text column
+    kind: Annotated[str, Field(db_index=True, max_length=64)]
+```
+
+`makemigrations` honours these field attributes:
+- `db_default` / `nullable` are written into `CREATE TABLE` and `ADD COLUMN` DDL.
+- `db_index=True` emits `CREATE INDEX` after the table op.
+- For **already-existing tables**, `makemigrations` now **autodiffs** index and column
+  attribute changes against the state projected from prior migration files:
+  - Adding `db_index=True` to an existing field → `AddIndex` op.
+  - Removing `db_index=True` → `DropIndex` op.
+  - Adding or changing `db_default` → `AlterColumn … SET DEFAULT …` op.
+  - Removing `db_default` → `AlterColumn … DROP DEFAULT` op.
+  - Changing nullability → `AlterColumn … SET / DROP NOT NULL` op (SET NOT NULL is
+    classified destructive and requires `--confirm`).
+  - Column type changes, renames, and drops remain manual (out of scope for v0.1).
+
 ### Django-Inspired API
 
 Familiar query interface.
@@ -301,6 +352,8 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 - [x] `call_function` for allowlisted stored-procedure calls
 - [x] Migration ops for extensions, RLS policies, and function DDL
 - [x] pgvector similarity score projection (`vector_search` helper)
+- [x] `Field(db_default=..., nullable=...)` — first-class DB-side defaults and nullability override
+- [x] `makemigrations` autodiff for index / default / nullability changes on existing tables
 - [ ] Query optimization (deferred fields, prefetch tuning)
 - [ ] Advanced relationship loading
 

{ferrum_orm-0.1.7 → ferrum_orm-0.1.9}/README.md

@@ -49,6 +49,14 @@ user = await User.objects.create(
     email="john@example.com",
 )
 
+# Insert from an instance (sentinel PK is dropped so the DB default runs)
+draft = User(id=0, email="dana@example.com")
+created = await User.objects.create(conn, draft)
+
+# Persist one instance's changes by primary key
+created.is_active = False
+await User.objects.update_instance(conn, created, fields=["is_active"])
+
 users = await (
     User.objects
     .filter(is_active=True)
@@ -88,6 +96,49 @@ class User(Model):
 
 No duplicate schema definitions.
 
+### Field Options
+
+`ferrum.Field()` accepts column-level constraints that are carried through to DDL:
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `db_default` | `str \| None` | DB-side `DEFAULT` expression (e.g. `"NOW()"`, `"''"`, `"GEN_RANDOM_UUID()"`). Token casing is normalised (`now()` → `NOW()`). |
+| `nullable` | `bool \| None` | Override annotation-derived nullability. Use `nullable=False` to force `NOT NULL` even on a `T \| None`-annotated field. |
+| `db_index` | `bool` | Emit a `CREATE INDEX` on this column (auto-named `idx_{table}_{field}`). |
+| `unique` | `bool` | Emit a `UNIQUE` constraint. |
+| `db_column` | `str \| None` | Override the database column name. |
+| `primary_key` | `bool` | Declare this field as the primary key. |
+| `uuid_generate` | `"v4" \| "v7" \| None` | Set `GEN_RANDOM_UUID()` / `UUIDV7()` as the DB default for UUID PK columns. |
+| `max_length` | `int \| None` | Emit `VARCHAR(n)` instead of `TEXT`. |
+| `max_digits` / `decimal_places` | `int \| None` | Emit `NUMERIC(p,s)`. |
+| `vector_dimensions` | `int \| None` | Required for `Vector` columns; emits `VECTOR(n)`. |
+
+```python
+from datetime import datetime
+from typing import Annotated
+from ferrum import Model, Field
+
+class Event(Model):
+    id: int
+    # DB-side timestamp default; Python annotation allows None but column is NOT NULL
+    created_at: Annotated[datetime | None, Field(db_default="now()", nullable=False)]
+    # Indexed text column
+    kind: Annotated[str, Field(db_index=True, max_length=64)]
+```
+
+`makemigrations` honours these field attributes:
+- `db_default` / `nullable` are written into `CREATE TABLE` and `ADD COLUMN` DDL.
+- `db_index=True` emits `CREATE INDEX` after the table op.
+- For **already-existing tables**, `makemigrations` now **autodiffs** index and column
+  attribute changes against the state projected from prior migration files:
+  - Adding `db_index=True` to an existing field → `AddIndex` op.
+  - Removing `db_index=True` → `DropIndex` op.
+  - Adding or changing `db_default` → `AlterColumn … SET DEFAULT …` op.
+  - Removing `db_default` → `AlterColumn … DROP DEFAULT` op.
+  - Changing nullability → `AlterColumn … SET / DROP NOT NULL` op (SET NOT NULL is
+    classified destructive and requires `--confirm`).
+  - Column type changes, renames, and drops remain manual (out of scope for v0.1).
+
 ### Django-Inspired API
 
 Familiar query interface.
@@ -229,6 +280,8 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 - [x] `call_function` for allowlisted stored-procedure calls
 - [x] Migration ops for extensions, RLS policies, and function DDL
 - [x] pgvector similarity score projection (`vector_search` helper)
+- [x] `Field(db_default=..., nullable=...)` — first-class DB-side defaults and nullability override
+- [x] `makemigrations` autodiff for index / default / nullability changes on existing tables
 - [ ] Query optimization (deferred fields, prefetch tuning)
 - [ ] Advanced relationship loading
 

{ferrum_orm-0.1.7 → ferrum_orm-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "ferrum-orm"
-version = "0.1.7"
+version = "0.1.9"
 description = "Next-generation async ORM for Python with a Rust-powered core"
 license = { text = "Apache-2.0" }
 readme = "README.md"

{ferrum_orm-0.1.7 → ferrum_orm-0.1.9}/python/ferrum/__init__.py

@@ -6,7 +6,7 @@ Import paths are stable API; internal module paths are not.
 
 from __future__ import annotations
 
-__version__ = "0.1.7"
+__version__ = "0.1.9"
 __all__ = [
     "CreateExtension",
     "CreateFunction",

{ferrum_orm-0.1.7 → ferrum_orm-0.1.9}/python/ferrum/cli/makemigrations_cmd.py

@@ -23,7 +23,7 @@ if TYPE_CHECKING:
     from ferrum.models import Model
 
 from ferrum.migrations import loader
-from ferrum.migrations.orchestrator import compute_plan
+from ferrum.migrations.orchestrator import ColumnState, IndexState, SchemaState, compute_plan
 
 _MIGRATION_TEMPLATE = """\
 # Generated by ferrum makemigrations
@@ -59,34 +59,77 @@ def _get_all_model_subclasses() -> list[type[Model]]:
     return result
 
 
+def _normalize_state_default(value: str | None) -> str | None:
+    """Normalize a state default token to uppercase for consistent comparison."""
+    if value is None:
+        return None
+    from ferrum.models import _normalize_db_default
+
+    return _normalize_db_default(value)
+
+
 def _build_existing_state(
     migrations: list[loader.MigrationModule],
-) -> dict[str, list[str]]:
-    """Replay prior migration operations to produce {table: [column_names]} state.
+) -> SchemaState:
+    """Replay prior migration operations to produce a rich ``SchemaState``.
 
-    This is a static reconstruction — no database connection is used.  Only
-    ``create_table``, ``add_column``, ``drop_table``, and ``drop_column`` ops
-    are handled because those are the only kinds that change the column
-    inventory tracked by ``compute_plan``.
+    This is a static reconstruction — no database connection is used.
+    Handles: ``create_table``, ``add_column``, ``drop_table``, ``drop_column``,
+    ``add_index``, ``drop_index``, and ``alter_column`` (default / not_null).
     """
-    state: dict[str, list[str]] = {}
+    state = SchemaState()
     for mig_mod in migrations:
         for op in mig_mod.migration.operations:
             op_dict = op.to_op_dict()
             kind = op_dict.get("kind")
             if kind == "create_table":
                 table = op_dict["table"]
-                state[table] = [c["name"] for c in op_dict.get("columns", [])]
+                state.tables[table] = {
+                    c["name"]: ColumnState(
+                        sql_type=c.get("sql_type", ""),
+                        not_null=bool(c.get("not_null", False)),
+                        default=_normalize_state_default(c.get("default")),
+                    )
+                    for c in op_dict.get("columns", [])
+                }
             elif kind == "add_column":
                 table = op_dict["table"]
-                state.setdefault(table, []).append(op_dict["name"])
+                col_name = op_dict["name"]
+                state.tables.setdefault(table, {})[col_name] = ColumnState(
+                    sql_type=op_dict.get("sql_type", ""),
+                    not_null=bool(op_dict.get("not_null", False)),
+                    default=_normalize_state_default(op_dict.get("default")),
+                )
             elif kind == "drop_table":
-                state.pop(op_dict.get("table", ""), None)
+                state.tables.pop(op_dict.get("table", ""), None)
             elif kind == "drop_column":
                 table = op_dict.get("table", "")
                 col = op_dict.get("column", "")
-                if table in state and col in state[table]:
-                    state[table].remove(col)
+                if table in state.tables:
+                    state.tables[table].pop(col, None)
+            elif kind == "add_index":
+                idx_name = op_dict.get("name", "")
+                if idx_name:
+                    state.indexes[idx_name] = IndexState(
+                        table=op_dict.get("table", ""),
+                        columns=list(op_dict.get("columns", [])),
+                        unique=bool(op_dict.get("unique", False)),
+                        using=op_dict.get("using", "btree"),
+                        where=op_dict.get("where"),
+                    )
+            elif kind == "drop_index":
+                state.indexes.pop(op_dict.get("name", ""), None)
+            elif kind == "alter_column":
+                table = op_dict.get("table", "")
+                col = op_dict.get("column", "")
+                if table in state.tables and col in state.tables[table]:
+                    col_state = state.tables[table][col]
+                    if op_dict.get("not_null") is not None:
+                        col_state.not_null = bool(op_dict["not_null"])
+                    if op_dict.get("default") is not None:
+                        col_state.default = _normalize_state_default(op_dict["default"])
+                    if op_dict.get("drop_default"):
+                        col_state.default = None
     return state
 
 
@@ -125,8 +168,8 @@ def _index_source(op: dict[str, Any]) -> str:
 def _op_to_source(op: dict[str, Any]) -> str:
     """Convert a plan op dict to an 8-space-indented Python source line.
 
-    Handles ``create_table``, ``add_column``, ``add_index``, and ``add_fk`` — the kinds
-    emitted by ``compute_plan`` in v0.1.
+    Handles ``create_table``, ``add_column``, ``add_index``, ``drop_index``,
+    ``add_fk``, and ``alter_column`` — the kinds emitted by ``compute_plan``.
 
     Raises:
         ValueError: if the op kind cannot be rendered to Python source.
@@ -155,6 +198,9 @@ def _op_to_source(op: dict[str, Any]) -> str:
     if kind == "add_index":
         return f"        {_index_source(op)},"
 
+    if kind == "drop_index":
+        return f"        ops.DropIndex({op['name']!r}),"
+
     if kind == "add_fk":
         return (
             f"        ops.AddForeignKey({op['table']!r}, {op['name']!r}, "
@@ -198,6 +244,9 @@ def _reverse_op_to_source(op_dict: dict[str, Any]) -> str | None:
         return f"        ops.DropColumn({op_dict['table']!r}, {op_dict['name']!r}),"
     if kind == "add_index":
         return f"        ops.DropIndex({op_dict['name']!r}),"
+    if kind == "drop_index":
+        # Can't auto-reverse a drop_index without knowing all original parameters.
+        return None
     if kind == "add_fk":
         return f"        ops.DropForeignKey({op_dict['table']!r}, {op_dict['name']!r}),"
     return None

{ferrum_orm-0.1.7 → ferrum_orm-0.1.9}/python/ferrum/migrations/__init__.py

@@ -36,9 +36,18 @@ from ferrum.migrations.operations import (
     DropPolicy,
     EnableRLS,
 )
-from ferrum.migrations.orchestrator import MigrationResult, _op_to_sql, apply, compute_plan
+from ferrum.migrations.orchestrator import (
+    ColumnState,
+    IndexState,
+    MigrationResult,
+    SchemaState,
+    _op_to_sql,
+    apply,
+    compute_plan,
+)
 
 __all__ = [
+    "ColumnState",
     "CreateExtension",
     "CreateFullTextCatalog",
     "CreateFullTextIndex",
@@ -50,8 +59,10 @@ __all__ = [
     "DropFunction",
     "DropPolicy",
     "EnableRLS",
+    "IndexState",
     "Migration",
     "MigrationResult",
+    "SchemaState",
     "_op_to_sql",
     "apply",
     "compute_plan",

{ferrum_orm-0.1.7 → ferrum_orm-0.1.9}/python/ferrum/migrations/orchestrator.py

@@ -20,6 +20,7 @@ Security invariants:
 
 from __future__ import annotations
 
+import dataclasses
 import datetime
 import hashlib
 import json
@@ -36,6 +37,43 @@ if TYPE_CHECKING:
     from ferrum.models import FieldMeta, Model, ModelMetadata
 
 
+# ---------------------------------------------------------------------------
+# Schema state dataclasses — projected migration state used by makemigrations
+# ---------------------------------------------------------------------------
+
+
+@dataclasses.dataclass
+class ColumnState:
+    """Projected state of a single table column after replaying migration ops."""
+
+    sql_type: str
+    not_null: bool = False
+    default: str | None = None
+
+
+@dataclasses.dataclass
+class IndexState:
+    """Projected state of a single index after replaying migration ops."""
+
+    table: str
+    columns: list[str] = dataclasses.field(default_factory=list)
+    unique: bool = False
+    using: str = "btree"
+    where: str | None = None
+
+
+@dataclasses.dataclass
+class SchemaState:
+    """Full projected schema state derived by replaying prior migration files.
+
+    ``tables`` maps table name → column name → ``ColumnState``.
+    ``indexes`` maps index name → ``IndexState``.
+    """
+
+    tables: dict[str, dict[str, ColumnState]] = dataclasses.field(default_factory=dict)
+    indexes: dict[str, IndexState] = dataclasses.field(default_factory=dict)
+
+
 class OperationClass(Enum):
     """Classification of a migration operation by safety profile."""
 
@@ -744,28 +782,139 @@ def _field_to_col_def(field_meta: FieldMeta, *, is_pk: bool) -> dict[str, Any]:
     }
 
 
+def _autodiff_existing_table(
+    ops: list[dict[str, Any]],
+    metadata: ModelMetadata,
+    table: str,
+    existing_col_names: set[str],
+    existing_col_attrs: dict[str, ColumnState],
+    existing_indexes: dict[str, IndexState],
+) -> None:
+    """Emit index and column-attribute diff ops for an existing table.
+
+    Called from ``compute_plan`` only when a rich ``SchemaState`` is available.
+    Appends ``add_index``, ``drop_index``, and ``alter_column`` ops to *ops*.
+
+    Security: all identifiers come from model metadata allowlists or
+    ``SchemaState`` that was itself built from prior migration ops — never user
+    input.  Default values are checked against ``_DEFAULT_VALUE_ALLOWLIST`` by
+    ``_op_to_sql`` when the plan is applied.
+
+    Out of scope: sql_type changes, renames, drops (unchanged v0.1 rule).
+    ``SET NOT NULL`` is emitted but classified destructive by ``AlterColumn``.
+    """
+    # Build the set of desired indexes for this table.
+    # Key: index name → op dict for add_index.
+    desired_indexes: dict[str, dict[str, Any]] = {}
+
+    # db_index=True fields on *existing* columns (new columns are handled above).
+    for f in metadata.fields:
+        if f.column_name in existing_col_names and f.db_index:
+            idx_name = f"idx_{table}_{f.name}"
+            desired_indexes[idx_name] = {
+                "kind": "add_index",
+                "table": table,
+                "name": idx_name,
+                "columns": [f.column_name],
+                "unique": False,
+                "using": "btree",
+            }
+
+    # Meta.indexes entries.
+    for index in metadata.indexes:
+        # Only consider indexes whose columns all exist already.
+        column_names = [
+            next((f.column_name for f in metadata.fields if f.name == fn), fn)
+            for fn in index.fields
+        ]
+        idx_op: dict[str, Any] = {
+            "kind": "add_index",
+            "table": table,
+            "name": index.name,
+            "columns": column_names,
+            "unique": index.unique,
+            "using": index.using,
+        }
+        if index.where is not None:
+            idx_op["where"] = index.where
+        opclasses = _resolve_gin_opclasses(metadata, index.fields, using=index.using)
+        if opclasses is not None:
+            idx_op["opclasses"] = opclasses
+        desired_indexes[index.name] = idx_op
+
+    # Emit add_index for desired indexes not yet in state.
+    for idx_name, idx_op in desired_indexes.items():
+        if idx_name not in existing_indexes:
+            ops.append(idx_op)
+
+    # Emit drop_index for Ferrum-tracked indexes that are no longer desired.
+    for idx_name, idx_state in existing_indexes.items():
+        if idx_state.table == table and idx_name not in desired_indexes:
+            ops.append({"kind": "drop_index", "name": idx_name, "table": table})
+
+    # Column default / nullability autodiff.
+    for f in metadata.fields:
+        if f.column_name not in existing_col_attrs:
+            continue  # New column — already emitted as add_column above.
+        col_state = existing_col_attrs[f.column_name]
+
+        desired_not_null = not f.nullable
+        desired_default = f.db_default  # already normalized in FieldMeta
+
+        # Compare case-insensitively to handle legacy lowercase defaults in state.
+        state_default_upper = col_state.default.upper() if col_state.default else None
+        desired_default_upper = desired_default.upper() if desired_default else None
+
+        alter_kwargs: dict[str, Any] = {}
+
+        if desired_not_null != col_state.not_null:
+            alter_kwargs["not_null"] = desired_not_null
+
+        if desired_default_upper != state_default_upper:
+            if desired_default is not None:
+                alter_kwargs["default"] = desired_default
+            elif col_state.default is not None:
+                alter_kwargs["drop_default"] = True
+
+        if alter_kwargs:
+            ops.append(
+                {
+                    "kind": "alter_column",
+                    "table": table,
+                    "column": f.column_name,
+                    **alter_kwargs,
+                }
+            )
+
+
 def compute_plan(
     model_classes: list[type[Model]] | None = None,
-    existing_tables: dict[str, list[str]] | None = None,
+    existing_tables: dict[str, list[str]] | SchemaState | None = None,
     *,
     conn: Connection | None = None,
     models: list[type[Model]] | None = None,
 ) -> dict[str, Any]:
     """Compute a migration plan from model classes against the current DB schema.
 
-    Compares ``model_classes`` against ``existing_tables`` (table → column names)
-    and emits ``create_table`` ops for absent tables and ``add_column`` ops for
-    columns present in the model but absent from the DB.
+    Compares ``model_classes`` against ``existing_tables`` and emits:
+    - ``create_table`` ops for absent tables (with ``add_index`` for ``db_index`` fields
+      and ``Meta.indexes`` entries).
+    - ``add_column`` ops for columns present in the model but absent from the DB.
+    - When ``existing_tables`` is a :class:`SchemaState` (returned by
+      ``_build_existing_state``): also emits ``add_index`` / ``drop_index`` for
+      index changes on existing columns, and ``alter_column`` for default /
+      nullability changes.
 
-    This is a v0.1 additive-only schema diff.  Column type changes, renames,
-    and drops are out of scope and will be addressed in a future release.
+    This is a v0.1 additive schema diff.  Column type changes, renames, and
+    drops are out of scope.
 
     Args:
         model_classes: Ferrum ``Model`` subclasses to inspect.  Their
             ``ModelMetadata`` (built at class-definition time) is the sole source
             of table/column names; no user input reaches SQL identifiers.
-        existing_tables: Mapping of table name → list of existing column names,
-            as returned by DB introspection.  Pass ``{}`` for a fresh database.
+        existing_tables: Either a ``dict[str, list[str]]`` (table → column names,
+            legacy/backward-compat), a :class:`SchemaState` (richer projected
+            state from ``_build_existing_state``), or ``None`` for a fresh database.
         conn: Reserved for a future DB-introspection path.  ``None`` means use
             the supplied/static ``existing_tables`` mapping.
         models: Keyword alias for ``model_classes`` used by CLI/tests.
@@ -781,8 +930,28 @@ def compute_plan(
         model_classes = models
     if model_classes is None:
         raise TypeError("compute_plan() requires model_classes or models.")
+
+    # Normalize existing_tables to SchemaState for uniform handling.
+    # When the caller passes a legacy dict[str, list[str]], we build a SchemaState
+    # with column-name-only entries (no default/not_null/index info) and suppress
+    # the index/default autodiff so existing callers are unaffected.
+    has_rich_state: bool
+    schema_state: SchemaState
     if existing_tables is None:
-        existing_tables = {}
+        schema_state = SchemaState()
+        has_rich_state = True
+    elif isinstance(existing_tables, SchemaState):
+        schema_state = existing_tables
+        has_rich_state = True
+    else:
+        # Legacy dict[str, list[str]] — columns only, no index/default state.
+        schema_state = SchemaState(
+            tables={
+                tbl: {col: ColumnState(sql_type="") for col in cols}
+                for tbl, cols in existing_tables.items()
+            }
+        )
+        has_rich_state = False
 
     ops: list[dict[str, Any]] = []
     timestamp = datetime.datetime.now(tz=datetime.UTC).strftime("%Y%m%d_%H%M%S")
@@ -800,7 +969,7 @@ def compute_plan(
         metadata = cls.get_metadata()
         table = metadata.table_name
 
-        if table not in existing_tables:
+        if table not in schema_state.tables:
             # Detect composite PK: more than one field has pk=True.
             pk_fields_list = [f for f in metadata.fields if f.pk]
             is_composite_pk = len(pk_fields_list) > 1
@@ -892,7 +1061,7 @@ def compute_plan(
                     owner_col = f"{table}_id"
                     target_col = f"{target_table}_id"
 
-                    if through not in existing_tables:
+                    if through not in schema_state.tables:
                         ops.append(
                             {
                                 "kind": "create_table",
@@ -940,9 +1109,13 @@ def compute_plan(
                             }
                         )
         else:
-            existing_cols = set(existing_tables[table])
+            # Table already exists — add new columns and (when rich state is
+            # available) diff indexes and column default/nullability.
+            existing_col_attrs = schema_state.tables.get(table, {})
+            existing_col_names: set[str] = set(existing_col_attrs.keys())
+
             for f in metadata.fields:
-                if f.column_name not in existing_cols:
+                if f.column_name not in existing_col_names:
                     col_def = _field_to_col_def(f, is_pk=False)
                     ops.append(
                         {
@@ -964,6 +1137,16 @@ def compute_plan(
                             }
                         )
 
+            if has_rich_state:
+                _autodiff_existing_table(
+                    ops,
+                    metadata,
+                    table,
+                    existing_col_names,
+                    existing_col_attrs,
+                    schema_state.indexes,
+                )
+
     return {
         "version": 1,
         "name": f"auto_{timestamp}",