ferrum-orm 0.1.20__tar.gz → 0.1.21__tar.gz

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/Cargo.lock

@@ -223,7 +223,7 @@ checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "ferrum-core"
-version = "0.1.20"
+version = "0.1.21"
 dependencies = [
  "criterion",
  "proptest",
@@ -234,7 +234,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-migrate"
-version = "0.1.20"
+version = "0.1.21"
 dependencies = [
  "ferrum-core",
  "serde",
@@ -243,7 +243,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-pyo3"
-version = "0.1.20"
+version = "0.1.21"
 dependencies = [
  "ferrum-core",
  "ferrum-sql",
@@ -255,7 +255,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-sql"
-version = "0.1.20"
+version = "0.1.21"
 dependencies = [
  "criterion",
  "ferrum-core",

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/Cargo.toml

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

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferrum-orm
-Version: 0.1.20
+Version: 0.1.21
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -217,6 +217,17 @@ class Event(Model):
 `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.
+- A `ForeignKey` / `OneToOne` references the target model's primary-key column, so
+  natural keys work (e.g. `REFERENCES catalog_version(version)`). A target with a
+  composite primary key raises `FerrumSchemaError`, because a single-column foreign
+  key cannot reference it.
+- Every `AddForeignKey` comes after all `CreateTable` ops in the same migration, so
+  model order, self-references and cycles do not matter.
+- Several `primary_key=True` fields produce
+  `CreateTable(..., composite_pk_columns=[...])` → `PRIMARY KEY (a, b, ...)`.
+- A `Literal[...]` field produces `ops.Column(..., enum_values=[...])` →
+  `CHECK (col IN (...))`, with each value escaped.
+- `reverse_operations` undo in reverse order, so foreign keys drop before tables.
 - 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.

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/README.md

@@ -145,6 +145,17 @@ class Event(Model):
 `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.
+- A `ForeignKey` / `OneToOne` references the target model's primary-key column, so
+  natural keys work (e.g. `REFERENCES catalog_version(version)`). A target with a
+  composite primary key raises `FerrumSchemaError`, because a single-column foreign
+  key cannot reference it.
+- Every `AddForeignKey` comes after all `CreateTable` ops in the same migration, so
+  model order, self-references and cycles do not matter.
+- Several `primary_key=True` fields produce
+  `CreateTable(..., composite_pk_columns=[...])` → `PRIMARY KEY (a, b, ...)`.
+- A `Literal[...]` field produces `ops.Column(..., enum_values=[...])` →
+  `CHECK (col IN (...))`, with each value escaped.
+- `reverse_operations` undo in reverse order, so foreign keys drop before tables.
 - 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.

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/pyproject.toml

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

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/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.20"
+__version__ = "0.1.21"
 __all__ = [
     "Aggregate",
     "ConnectionRegistry",

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/python/ferrum/cli/makemigrations_cmd.py

@@ -142,6 +142,8 @@ def _col_source(col: dict[str, Any]) -> str:
         flags.append("primary_key=True")
     if col.get("default") is not None:
         flags.append(f"default={col['default']!r}")
+    if col.get("enum_values"):
+        flags.append(f"enum_values={list(col['enum_values'])!r}")
     extra = (", " + ", ".join(flags)) if flags else ""
     return f"ops.Column({col['name']!r}, {col['sql_type']!r}{extra})"
 
@@ -179,10 +181,12 @@ def _op_to_source(op: dict[str, Any]) -> str:
     if kind == "create_table":
         table = op["table"]
         col_lines = [f"            {_col_source(c)}," for c in op.get("columns", [])]
+        composite = op.get("composite_pk_columns")
+        pk_arg = f", composite_pk_columns={list(composite)!r}" if composite else ""
         if col_lines:
             cols_block = "\n".join(col_lines)
-            return f"        ops.CreateTable({table!r}, [\n{cols_block}\n        ]),"
-        return f"        ops.CreateTable({table!r}, []),"
+            return f"        ops.CreateTable({table!r}, [\n{cols_block}\n        ]{pk_arg}),"
+        return f"        ops.CreateTable({table!r}, []{pk_arg}),"
 
     if kind == "add_column":
         table = op["table"]
@@ -192,6 +196,7 @@ def _op_to_source(op: dict[str, Any]) -> str:
             "not_null": op.get("not_null", False),
             "default": op.get("default"),
             "primary_key": op.get("primary_key", False),
+            "enum_values": op.get("enum_values"),
         }
         return f"        ops.AddColumn({table!r}, {_col_source(col)}),"
 
@@ -260,7 +265,8 @@ def _build_reverse_block(ops: list[dict[str, Any]]) -> str:
     If any op has no known reverse, the block uses the irreversible-comment form
     with an empty list so the developer can fill it in manually.
     """
-    rev_lines = [_reverse_op_to_source(op) for op in ops]
+    # Undo in reverse order: FKs drop before the tables they reference.
+    rev_lines = [_reverse_op_to_source(op) for op in reversed(ops)]
     has_irreversible = any(line is None for line in rev_lines)
     if has_irreversible:
         return (

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/python/ferrum/migrations/autodiff.py

@@ -52,6 +52,7 @@ from ferrum.migrations.orchestrator import (
     IndexState,
     SchemaState,
     _is_op_destructive,
+    _resolve_fk_target,
     compute_plan,
 )
 
@@ -516,13 +517,12 @@ def compute_autodiff_plan(
         for rel in metadata.relations:
             if rel.kind in ("fk", "one_to_one") and rel.db_column:
                 constraint_name = f"fk_{table}_{rel.db_column}"
-                target_meta = meta_by_name.get(rel.to_model)
-                target_table = target_meta.table_name if target_meta else rel.to_model.lower()
+                ref_table, ref_column = _resolve_fk_target(rel, table, meta_by_name)
                 desired_fks[constraint_name] = ForeignKeyState(
                     table=table,
                     column=rel.db_column,
-                    ref_table=target_table,
-                    ref_column="id",
+                    ref_table=ref_table,
+                    ref_column=ref_column,
                     on_delete=rel.on_delete or "CASCADE",
                 )
         existing_fks = {

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/python/ferrum/migrations/drift.py

@@ -17,10 +17,13 @@ Security invariants:
 from __future__ import annotations
 
 import json
+import re
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
+from ferrum.errors import FerrumSchemaError
+from ferrum.migrations.orchestrator import _resolve_fk_target
 from ferrum.registry import all_models
 
 if TYPE_CHECKING:
@@ -1068,21 +1071,29 @@ def _expected_constraints(metadata: ModelMetadata) -> list[dict[str, Any]]:
                     "definition": f"UNIQUE ({field_meta.column_name})",
                 }
             )
-    # FK constraints from declared relations.
+    # FK constraints from declared relations. The name and target mirror what
+    # makemigrations emits (``fk_<table>_<column>``, target primary key).
+    meta_by_name = {name: model.get_metadata() for name, model in all_models().items()}
     for relation in metadata.relations:
         if relation.kind in ("fk", "one_to_one") and relation.db_column:
+            try:
+                ref_table, ref_column = _resolve_fk_target(
+                    relation, metadata.table_name, meta_by_name
+                )
+            except FerrumSchemaError:
+                ref_table, ref_column = relation.to_model, "?"
+            delete_rule = (relation.on_delete or "NO ACTION").upper()
             expected.append(
                 {
-                    "name": f"{metadata.table_name}_{relation.db_column}_fkey",
+                    "name": f"fk_{metadata.table_name}_{relation.db_column}",
                     "type": "FOREIGN KEY",
                     "column": relation.db_column,
-                    "foreign_table": None,  # resolved by metadata caller if needed
-                    "foreign_column": None,
-                    "delete_rule": (relation.on_delete or "NO ACTION").upper(),
+                    "foreign_table": ref_table,
+                    "foreign_column": ref_column,
+                    "delete_rule": delete_rule,
                     "definition": (
                         f"FOREIGN KEY ({relation.db_column}) REFERENCES "
-                        f"{relation.to_model} (id) ON DELETE "
-                        f"{(relation.on_delete or 'NO ACTION').upper()}"
+                        f"{ref_table}({ref_column}) ON DELETE {delete_rule}"
                     ),
                 }
             )
@@ -1101,6 +1112,31 @@ def _expected_constraints(metadata: ModelMetadata) -> list[dict[str, Any]]:
     return expected
 
 
+_CHECK_IN_RE = re.compile(
+    r"^CHECK\s*\(\s*\"?(\w+)\"?\s+IN\s*\((.*)\)\s*\)$", re.IGNORECASE | re.DOTALL
+)
+_CHECK_ANY_RE = re.compile(
+    r"^CHECK\s*\(\s*\(\s*\"?(\w+)\"?\s*=\s*ANY\s*\(\s*ARRAY\s*\[(.*)\]\s*\)\s*\)\s*\)$",
+    re.IGNORECASE | re.DOTALL,
+)
+_CHECK_LITERAL_RE = re.compile(r"'((?:[^']|'')*)'(?:::[\w ]+)?")
+
+
+def _canonical_check(definition: str) -> str:
+    """Normalize an enum CHECK so model and live forms compare equal.
+
+    PostgreSQL stores ``col IN ('a', 'b')`` as
+    ``((col = ANY (ARRAY['a'::text, 'b'::text])))``. Both reduce to
+    ``CHECK (COL IN ('a', 'b'))``; other definitions are only uppercased.
+    """
+    text = definition.strip()
+    match = _CHECK_IN_RE.match(text) or _CHECK_ANY_RE.match(text)
+    if match is None:
+        return text.upper()
+    values = _CHECK_LITERAL_RE.findall(match.group(2))
+    return f"CHECK ({match.group(1).upper()} IN ({', '.join(repr(v) for v in values)}))"
+
+
 def _compare_constraints(
     table: str,
     expected: list[dict[str, Any]],
@@ -1110,6 +1146,17 @@ def _compare_constraints(
     actual_by_name = {str(a["name"]): a for a in actual}
     expected_by_name = {str(e["name"]): e for e in expected}
 
+    # A live FK on the expected column satisfies the expectation under any
+    # name (e.g. PostgreSQL's default ``<table>_<column>_fkey``).
+    actual_fk_by_column = {
+        str(a.get("column")): str(a["name"]) for a in actual if a["type"] == "FOREIGN KEY"
+    }
+    for name, expected_c in list(expected_by_name.items()):
+        if expected_c["type"] == "FOREIGN KEY" and name not in actual_by_name:
+            live_name = actual_fk_by_column.get(str(expected_c["column"]))
+            if live_name is not None and live_name not in expected_by_name:
+                expected_by_name[live_name] = expected_by_name.pop(name)
+
     for name, expected_c in expected_by_name.items():
         if name not in actual_by_name:
             diffs.append(
@@ -1142,8 +1189,8 @@ def _compare_constraints(
                     )
             # For CHECK constraints, compare the normalized definition.
             if expected_c["type"] == "CHECK":
-                expected_def = str(expected_c.get("definition") or "").upper()
-                actual_def = str(actual_c.get("definition") or "").upper()
+                expected_def = _canonical_check(str(expected_c.get("definition") or ""))
+                actual_def = _canonical_check(str(actual_c.get("definition") or ""))
                 if expected_def and actual_def and expected_def != actual_def:
                     diffs.append(
                         ConstraintDifference(

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/python/ferrum/migrations/operations.py

@@ -41,22 +41,33 @@ class Column:
         not_null: bool = False,
         default: str | None = None,
         primary_key: bool = False,
+        enum_values: list[str] | None = None,
     ) -> None:
+        """Describe one column.
+
+        Args:
+            enum_values: Allowed values of a ``Literal[...]`` field. The DDL
+                adds ``CHECK (<column> IN (...))`` with each value escaped.
+        """
         self.name = name
         self.sql_type = sql_type
         self.not_null = not_null
         self.default = default
         self.primary_key = primary_key
+        self.enum_values = list(enum_values) if enum_values is not None else None
 
     def to_col_dict(self) -> dict[str, Any]:
         """Return a column-def dict consumed by ``_col_def`` / ``_op_to_sql``."""
-        return {
+        col: dict[str, Any] = {
             "name": self.name,
             "sql_type": self.sql_type,
             "not_null": self.not_null,
             "default": self.default,
             "primary_key": self.primary_key,
         }
+        if self.enum_values:
+            col["enum_values"] = list(self.enum_values)
+        return col
 
     def __repr__(self) -> str:
         flags = []
@@ -66,6 +77,8 @@ class Column:
             flags.append("primary_key=True")
         if self.default is not None:
             flags.append(f"default={self.default!r}")
+        if self.enum_values:
+            flags.append(f"enum_values={self.enum_values!r}")
         extra = (", " + ", ".join(flags)) if flags else ""
         return f"Column({self.name!r}, {self.sql_type!r}{extra})"
 
@@ -101,7 +114,12 @@ class CreateTable(Operation):
         return "safe"
 
     def __repr__(self) -> str:
-        return f"CreateTable({self.table_name!r}, {self.columns!r})"
+        extra = (
+            f", composite_pk_columns={self.composite_pk_columns!r}"
+            if self.composite_pk_columns
+            else ""
+        )
+        return f"CreateTable({self.table_name!r}, {self.columns!r}{extra})"
 
 
 class DropTable(Operation):

{ferrum_orm-0.1.20 → ferrum_orm-0.1.21}/python/ferrum/migrations/orchestrator.py

@@ -29,7 +29,7 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import TYPE_CHECKING, Any, ClassVar
 
-from ferrum.errors import FerrumMigrationError
+from ferrum.errors import FerrumMigrationError, FerrumSchemaError
 from ferrum.migrations.ledger import (
     ADVISORY_LOCK_KEY_1,
     ADVISORY_LOCK_KEY_2,
@@ -44,7 +44,7 @@ from ferrum.migrations.tokens import verify_token
 if TYPE_CHECKING:
     from ferrum.connection import Connection, ConnectionLike
     from ferrum.migrations.loader import MigrationModule
-    from ferrum.models import FieldMeta, Model, ModelMetadata
+    from ferrum.models import FieldMeta, Model, ModelMetadata, RelationMeta
 
 
 # ---------------------------------------------------------------------------
@@ -484,11 +484,22 @@ def _col_def(col: dict[str, Any], *, dialect: str = "postgres") -> str:
         parts.append("PRIMARY KEY")
     if col.get("unique"):
         parts.append("UNIQUE")
-    if col.get("enum_check"):
-        parts.append(str(col["enum_check"]))
+    enum_values = col.get("enum_values")
+    if enum_values:
+        parts.append(_enum_check_sql(col["name"], enum_values, dialect))
     return " ".join(parts)
 
 
+def _enum_check_sql(column: str, values: list[str], dialect: str) -> str:
+    """Build ``CHECK (col IN ('a', 'b'))`` for a ``Literal`` field.
+
+    Values come from the model's ``Literal[...]`` annotation. Each one is
+    emitted as an escaped string literal, never interpolated raw.
+    """
+    literals = ", ".join("'" + str(v).replace("'", "''") + "'" for v in values)
+    return f"CHECK ({_quote_ident(column, dialect)} IN ({literals}))"
+
+
 def _op_to_sql(op: dict[str, Any], *, dialect: str = "postgres") -> str:
     """Generate DDL SQL from a MigrationOp dict.
 
@@ -860,7 +871,7 @@ def _field_to_col_def(field_meta: FieldMeta, *, is_pk: bool) -> dict[str, Any]:
     # insert-time value, not a DB default: the sequence owns the DB default.
     if default is None and sql_type.upper() not in _SERIAL_SQL_TYPES:
         default = _python_default_to_sql(value=field_meta.python_default, field_meta=field_meta)
-    return {
+    col_def: dict[str, Any] = {
         "name": field_meta.column_name,
         "sql_type": sql_type,
         "not_null": not field_meta.nullable,
@@ -868,6 +879,37 @@ def _field_to_col_def(field_meta: FieldMeta, *, is_pk: bool) -> dict[str, Any]:
         "primary_key": is_pk,
         "unique": field_meta.unique,
     }
+    if field_meta.field_type == "enum" and field_meta.enum_values:
+        col_def["enum_values"] = list(field_meta.enum_values)
+    return col_def
+
+
+def _resolve_fk_target(
+    rel: RelationMeta,
+    owner_table: str,
+    meta_by_name: dict[str, ModelMetadata],
+) -> tuple[str, str]:
+    """Return ``(ref_table, ref_column)`` for an FK / one-to-one relation.
+
+    The referenced column is the target model's primary-key column. A target
+    outside the planned model set keeps the legacy ``<model>.id`` fallback.
+
+    Raises:
+        FerrumSchemaError: the target has a composite primary key, which a
+            single-column foreign key cannot reference.
+    """
+    target_meta = meta_by_name.get(rel.to_model)
+    if target_meta is None:
+        return rel.to_model.lower(), "id"
+    pk_columns = [target_meta.fields[i].column_name for i in target_meta.pk_fields]
+    if len(pk_columns) != 1:
+        raise FerrumSchemaError(
+            f"Foreign key {owner_table}.{rel.db_column} references {rel.to_model}, "
+            f"which has a composite primary key ({', '.join(pk_columns)}). A "
+            "single-column foreign key cannot reference it. [FERR-S001]",
+            model=rel.to_model,
+        )
+    return target_meta.table_name, pk_columns[0]
 
 
 def _autodiff_existing_table(
@@ -1051,6 +1093,7 @@ def compute_plan(
     # Track M2M join tables already emitted to avoid duplicate CREATE TABLE ops
     # when both sides of the relationship appear in model_classes.
     emitted_m2m_tables: set[str] = set()
+    fk_ops: list[dict[str, Any]] = []
 
     for cls in model_classes:
         # ModelMetadata is built once at class-definition time and is read-only.
@@ -1069,13 +1112,6 @@ def compute_plan(
                 cd = _field_to_col_def(f, is_pk=f.pk)
                 if is_composite_pk and f.pk:
                     cd = {**cd, "primary_key": False, "composite_pk": True}
-                # Enum columns get an inline CHECK constraint in the DDL.
-                if f.field_type == "enum" and f.enum_values:
-                    quoted_vals = ", ".join(f"'{v}'" for v in f.enum_values)
-                    # Store check expression; _col_def doesn't handle it, so we embed
-                    # it as a suffix directly on the column entry via a post-pass.
-                    check = f"CHECK ({_quote_ident(f.column_name, 'postgres')} IN ({quoted_vals}))"
-                    cd = {**cd, "enum_check": check}
                 col_defs.append(cd)
 
             create_op: dict[str, Any] = {
@@ -1118,20 +1154,20 @@ def compute_plan(
                     index_op["opclasses"] = opclasses
                 ops.append(index_op)
 
-            # Emit AddForeignKey ops for FK / OneToOne relations on new tables.
+            # AddForeignKey ops for new tables are deferred until every table
+            # exists, so the target may be declared later, be the table itself,
+            # or form a cycle.
             for rel in metadata.relations:
                 if rel.kind in ("fk", "one_to_one"):
-                    target_meta = meta_by_name.get(rel.to_model)
-                    target_table = target_meta.table_name if target_meta else rel.to_model.lower()
-                    constraint_name = f"fk_{table}_{rel.db_column}"
-                    ops.append(
+                    ref_table, ref_column = _resolve_fk_target(rel, table, meta_by_name)
+                    fk_ops.append(
                         {
                             "kind": "add_fk",
                             "table": table,
-                            "name": constraint_name,
+                            "name": f"fk_{table}_{rel.db_column}",
                             "column": rel.db_column,
-                            "ref_table": target_table,
-                            "ref_column": "id",
+                            "ref_table": ref_table,
+                            "ref_column": ref_column,
                             "on_delete": rel.on_delete or "CASCADE",
                         }
                     )
@@ -1174,7 +1210,7 @@ def compute_plan(
                                 ],
                             }
                         )
-                        ops.append(
+                        fk_ops.append(
                             {
                                 "kind": "add_fk",
                                 "table": through,
@@ -1185,7 +1221,7 @@ def compute_plan(
                                 "on_delete": "CASCADE",
                             }
                         )
-                        ops.append(
+                        fk_ops.append(
                             {
                                 "kind": "add_fk",
                                 "table": through,
@@ -1235,6 +1271,7 @@ def compute_plan(
                     schema_state.indexes,
                 )
 
+    ops.extend(fk_ops)
     return {
         "version": 1,
         "name": f"auto_{timestamp}",