snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/metadata/check.py

@@ -0,0 +1,37 @@
+"""Immutable metadata of a CHECK constraint: a domain rule the DATABASE enforces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from snakeorm.expressions import SnakeCondition, condition_paths
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeCheckInfo:
+    """A `CHECK (...)` rule over the table's columns.
+
+    It stores the `SnakeCondition` as an AST, not as emitted SQL: that keeps the metadata
+    engine-agnostic (the dialect supplies quoting and syntax) and the condition is the SAME one
+    `.filter()` takes, so it is validated at type-check time (`User.age >= 18` stops compiling if
+    you rename `age`).
+    """
+
+    condition: SnakeCondition
+    name: str | None = None
+
+    def resolved_name(self, table_name: str) -> str:
+        """The name the DB knows the constraint by: the explicit one, or `ck_{table}_{columns}`.
+
+        Creation, removal and diff must agree on the name or you create duplicates and drop things
+        that do not exist. The columns come from the condition, deduplicated (`age > 0 AND
+        age < 150` -> `ck_users_age`).
+        """
+        if self.name:
+            return self.name
+        columns: list[str] = []
+        for path in condition_paths(self.condition):
+            column = path[-1]
+            if column not in columns:
+                columns.append(column)
+        return f"ck_{table_name}_{'_'.join(columns)}"

snakeorm/metadata/column.py

@@ -0,0 +1,201 @@
+"""Immutable metadata of columns."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+
+from snakeorm.core.exceptions import SnakeModelDefinitionError
+from snakeorm.metadata.enum_storage import SnakeEnumStorage
+from snakeorm.metadata.int_size import SnakeIntSize
+from snakeorm.metadata.json_storage import SnakeJsonStorage
+from snakeorm.metadata.server_default import SnakeServerDefault
+from snakeorm.metadata.type_params import (
+    SnakeDateTimeParams,
+    SnakeDecimalParams,
+    SnakeIntParams,
+    SnakeJsonParams,
+    SnakeStrParams,
+    SnakeTypeParams,
+)
+
+
+def _width_of(enum_type: type[Enum]) -> SnakeStrParams | None:
+    """The WIDTH a text-backed enum needs, or `None` when there is none to derive.
+
+    An enum knows exactly how wide its column has to be: it has a longest member, and the length of
+    that member's VALUE is an exact number available at compile time. The value and not the name,
+    because the value is what `adapt_param` writes and what the `CHECK` enumerates.
+
+    Three cases give nothing back, each for its own reason:
+
+    - an `IntEnum`, because an integer has no length (it has a `SnakeIntSize`, which is not this);
+    - an enum with no members, because there is no longest one — and `SnakeStrParams` rejects
+      `max_length=0` on purpose, so guessing would turn a strange model into a crash at import;
+    - anything that is not a text-backed enum at all, because the shout for that already lives in
+      `storage_type`, and saying it twice from a `__post_init__` would move the failure to a place
+      nobody is looking at.
+
+    `int` is checked before `str` for the same reason `storage_type` checks it first: the two orders
+    have to agree, or a column could be stored as an integer and sized as text.
+    """
+    if not (isinstance(enum_type, type) and issubclass(enum_type, Enum)):
+        return None
+    if issubclass(enum_type, int) or not issubclass(enum_type, str):
+        return None
+    widths = [len(str(member.value)) for member in enum_type]
+    if not widths:
+        return None
+    return SnakeStrParams(max_length=max(widths))
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeColumnInfo:
+    """Metadata of a column.
+
+    The type ALWAYS comes from Python (`python_type`); everything else only adds SQL info.
+    Immutable (frozen) and with `slots`: it is part of the compiled graph, which never changes.
+    """
+
+    name: str
+    python_type: type
+    nullable: bool = False
+    unique: bool = False
+    default: object | None = None
+    index: bool = False
+    db_comment: str | None = None  # COMMENT ON COLUMN
+    attr_name: str = ""  # name of the Python attribute; enables the SQL→Python mapping
+    has_default: bool = (
+        False  # tells "no default" apart from "default = None" (for the DDL)
+    )
+    autoincrement: bool = False  # the DB generates the value; the dialect picks how (SERIAL, AUTOINCREMENT...)
+    # Callable that fills the value in Python when building the object; NEVER touches the DDL. Mutually exclusive with `default`.
+    default_factory: Callable[[], object] | None = None
+    # SERVER default, engine-agnostic (the dialect translates it): the column is OMITTED from the
+    # INSERT and the RETURNING brings it back. Mutually exclusive with `default`.
+    server_default: SnakeServerDefault | None = None
+    # Escape hatch: raw SQL for the server default. NOT PORTABLE. Mutually exclusive with `server_default`.
+    server_default_sql: str | None = None
+
+    # SQL parameters of the type's FAMILY (an int's width, a str's length, a Decimal's precision, a
+    # dict's backing), or None if the type has none (`bool`, `date`, `UUID`...).
+    # They travel grouped and not loose because loose they allowed writing `max_length` AND
+    # `precision` on the same column: a state no engine represents, living in the graph that IS the
+    # truth.
+    type_params: SnakeTypeParams | None = None
+    # Enum: the enum's type and how it is backed. Primitives only; the conversions are not stored,
+    # they are derived from `enum_type`.
+    enum_type: type[Enum] | None = None
+    enum_storage: SnakeEnumStorage | None = None
+
+    def __post_init__(self) -> None:
+        """Fills in the width of a text-backed enum, which the column already knew and threw away.
+
+        `storage_type` derives ONE thing from `enum_type` —the base type, so the dialect never has
+        to know what an enum is— and this is the SECOND, derived in the same place and for the same
+        reason. Without it `type_params` stayed `None`, MySQL read "a `str` with no declared length",
+        wrote `TEXT`, and a composite index over the column died with `1071, Specified key was too
+        long`. The information was there the whole time.
+
+        It is NOT a new knob: `snake_enum` grows no `max_length=`, because there is nothing left for
+        anybody to decide. The type ALWAYS comes from Python, and this is the metadata reading all
+        of what Python said instead of half.
+
+        Params written out by hand WIN, and that is what keeps a historical migration honest: a
+        generated file spells the width the enum had the day it was written, so replaying it rebuilds
+        the column the database really has and the diff can see that today's longer member is a
+        change. Re-deriving from the live class would make that change invisible.
+        """
+        if self.type_params is not None or self.enum_type is None:
+            return
+        derived = _width_of(self.enum_type)
+        if derived is None:
+            return
+        # `object.__setattr__` is how a frozen dataclass normalises itself: the guarantee is that
+        # nobody changes the column AFTERWARDS, and this runs before anyone has it.
+        object.__setattr__(self, "type_params", derived)
+
+    # The five properties below READ the family's parameters under their usual names.
+    # Writing remains impossible other than through `type_params`: reading is comfortable, writing
+    # is narrow. They return the family's default when the column is not of that family, which is
+    # exactly what a column with the knob unset used to read before.
+
+    @property
+    def int_size(self) -> SnakeIntSize:
+        """A DB-side `int` width. Default `BIGINT`: the widest of both engines, so Python's
+        unbounded `int` lines up in Postgres and SQLite."""
+        return (
+            self.type_params.size
+            if isinstance(self.type_params, SnakeIntParams)
+            else SnakeIntSize.BIGINT
+        )
+
+    @property
+    def max_length(self) -> int | None:
+        """Maximum length of a `str`. Without it TEXT; with it Postgres emits VARCHAR(n)."""
+        return (
+            self.type_params.max_length
+            if isinstance(self.type_params, SnakeStrParams)
+            else None
+        )
+
+    @property
+    def json_storage(self) -> SnakeJsonStorage:
+        """Backing of a `dict`. Default `JSONB` (indexable, normalised); `JSON` preserves the
+        exact text. SQLite collapses both to TEXT."""
+        return (
+            self.type_params.storage
+            if isinstance(self.type_params, SnakeJsonParams)
+            else SnakeJsonStorage.JSONB
+        )
+
+    @property
+    def precision(self) -> int | None:
+        """Digits of a NUMERIC. Without it Postgres accepts any number (rounding on money)."""
+        return (
+            self.type_params.precision
+            if isinstance(self.type_params, SnakeDecimalParams)
+            else None
+        )
+
+    @property
+    def with_timezone(self) -> bool:
+        """Whether the date column carries a zone (`TIMESTAMPTZ`) or is wall-clock (`TIMESTAMP`).
+
+        The declarator sets it (`snake_datetimetz()` / `snake_datetime()`) and the compiler demands
+        it match the annotation, so reading it from here is reading what both of them say.
+        """
+        return isinstance(self.type_params, SnakeDateTimeParams) and self.type_params.tz
+
+    @property
+    def scale(self) -> int | None:
+        """Decimal places of a NUMERIC."""
+        return (
+            self.type_params.scale
+            if isinstance(self.type_params, SnakeDecimalParams)
+            else None
+        )
+
+    @property
+    def storage_type(self) -> type:
+        """The Python type the DIALECT maps to SQL.
+
+        Normal column: its own type. Enum: its BASE type (`str`/`int`), so the dialect never needs
+        to know anything about enums.
+        """
+        if self.enum_type is None:
+            return self.python_type
+        if issubclass(self.enum_type, int):
+            return int
+        if issubclass(self.enum_type, str):
+            return str
+        raise SnakeModelDefinitionError(
+            f"Enum {self.enum_type.__name__} is neither a StrEnum nor an IntEnum, which leaves "
+            f"it without a base type to store it with."
+        )
+
+    @property
+    def has_server_default(self) -> bool:
+        """Tells whether the DB sets the value: the column is excluded from `__init__` and INSERT."""
+        return self.server_default is not None or self.server_default_sql is not None

snakeorm/metadata/enum_storage.py

@@ -0,0 +1,33 @@
+"""How an enum is backed in the database."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SnakeEnumStorage(Enum):
+    """Which DB object checks that the column only ever holds valid enum members.
+
+    Engine-agnostic values (the dialect translates), like `SnakeServerDefault`/`SnakeFkAction`.
+
+    - `CHECK` (default): the base type plus a `CHECK col IN (...)`. Adding a value is reversible;
+      removing one fails at `migrate` if rows are still using it.
+    - `PLAIN`: base type only, no validation. An invalid value slipped in through raw SQL blows up
+      ON READ.
+
+    The BASE TYPE is not spelled out here, and the omission is deliberate: this class picks the DB
+    object that validates the column, not the SQL type, and the type is the dialect's answer to
+    `storage_type`. Measured on the three: `SnakeColumnInfo.__post_init__` derives a text enum's
+    width from its longest member, so a text-backed enum is `VARCHAR(n)` on PostgreSQL and MySQL
+    and `TEXT` only on SQLite, which has affinities and no widths; an int-backed one is `BIGINT` on
+    the first two and `INTEGER` on SQLite for the same reason.
+
+    There is no `NATIVE` on purpose: in Postgres `ADD VALUE` has no inverse (recreating the type
+    rewrites the table under `ACCESS EXCLUSIVE`), the value cannot be used in the same transaction
+    that adds it (and migrations are transactional), and if two models share the enum they share
+    the type. With `CHECK` none of that happens. A `NATIVE` that throws when used would be dead
+    metadata.
+    """
+
+    CHECK = "check"
+    PLAIN = "plain"

snakeorm/metadata/fk_action.py

@@ -0,0 +1,19 @@
+"""Referential actions of a foreign key (ON DELETE / ON UPDATE)."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SnakeFkAction(Enum):
+    """Referential action of an FK, valid for both ON DELETE and ON UPDATE.
+
+    Typed constants instead of magic strings. Each member's `value` is its SQL
+    fragment, ready for the DDL generator.
+    """
+
+    NO_ACTION = "NO ACTION"
+    RESTRICT = "RESTRICT"
+    CASCADE = "CASCADE"
+    SET_NULL = "SET NULL"
+    SET_DEFAULT = "SET DEFAULT"

snakeorm/metadata/foreign_key.py

@@ -0,0 +1,26 @@
+"""Immutable metadata of the foreign key (simple or composite)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from snakeorm.metadata.fk_action import SnakeFkAction
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeForeignKeyInfo:
+    """Foreign key: target model + (source_column, target_column) pairs.
+
+    ONE single structure for a simple FK (1 pair) and a composite one (N pairs). The join is
+    generated by AND-ing every pair together. `target` is the model's NAME (resolved in the Linker).
+    """
+
+    target: str
+    pairs: tuple[tuple[str, str], ...]
+    on_delete: SnakeFkAction = SnakeFkAction.NO_ACTION
+    on_update: SnakeFkAction = SnakeFkAction.NO_ACTION
+
+    @property
+    def is_composite(self) -> bool:
+        """Tells whether the key spans more than one column."""
+        return len(self.pairs) > 1

snakeorm/metadata/index.py

@@ -0,0 +1,43 @@
+"""Immutable metadata of an index."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from snakeorm.expressions import SnakeCondition
+from snakeorm.metadata.index_method import SnakeIndexMethod
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeIndexInfo:
+    """Index over one or more of the table's columns. 1 column = simple, N = composite."""
+
+    columns: tuple[str, ...]
+    unique: bool = False
+    name: str | None = None
+    # PARTIAL index: only indexes the rows that satisfy the condition (`WHERE deleted_at IS NULL`).
+    # It is what makes soft-delete and multi-tenancy usable.
+    where: SnakeCondition | None = None
+    # Access method, engine-agnostic (the dialect translates it). `None` = the default one.
+    method: SnakeIndexMethod | None = None
+
+    @property
+    def is_constraint(self) -> bool:
+        """Whether it produces a uniqueness CONSTRAINT instead of an index.
+
+        A plain `unique=True` is a constraint (`uq_*`); a PARTIAL one cannot be (Postgres does not
+        accept `CONSTRAINT ... UNIQUE ... WHERE`), so with `where=` uniqueness is a unique index and
+        nothing more.
+        """
+        return self.unique and self.where is None
+
+    def resolved_name(self, table_name: str) -> str:
+        """The name the DB knows the object by: the explicit one, or the one generated from its type.
+
+        The prefix says which object it is (`uq_` constraint, `ix_` index). It lives here and not in
+        the DDL emitter because the diff needs the same name as creation and removal, or it creates
+        duplicates and drops things that do not exist.
+        """
+        if self.name:
+            return self.name
+        return f"{'uq' if self.is_constraint else 'ix'}_{table_name}_{'_'.join(self.columns)}"

snakeorm/metadata/index_method.py

@@ -0,0 +1,19 @@
+"""Access method of an index, declared ENGINE-AGNOSTIC."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SnakeIndexMethod(Enum):
+    """Structure the engine builds the index with.
+
+    Agnostic values (the dialect translates). `BTREE` is the de facto default and is emitted
+    IMPLICITLY (no `USING`).
+    """
+
+    BTREE = "btree"  # the usual one: equality and ordered ranges
+    HASH = "hash"  # equality only, more compact
+    GIN = "gin"  # composite values: JSONB, arrays, text search
+    GIST = "gist"  # geometry, ranges, proximity
+    BRIN = "brin"  # huge tables whose data correlates with physical order

snakeorm/metadata/int_size.py

@@ -0,0 +1,20 @@
+"""Storage size of an integer in the DATABASE (not in Python)."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class SnakeIntSize(StrEnum):
+    """How many bits an `int` reserves in the database.
+
+    Python always uses an unbounded `int`; this only decides how much room the engine takes. The
+    members are the SQL STANDARD (which is why the `StrEnum` earns its type); the dialect
+    translates (SQLite collapses them all to `INTEGER`). `BIGINT` is the default on purpose: it is
+    the widest of both engines, so Python's uncapped `int` lines up in Postgres and SQLite. You
+    step it down by hand when saving bytes matters.
+    """
+
+    SMALLINT = "SMALLINT"  # 16 signed bits (±32,767)
+    INTEGER = "INTEGER"  # 32 signed bits (±2,147,483,647)
+    BIGINT = "BIGINT"  # 64 signed bits (±9.2·10¹⁸) — DEFAULT: the engine's widest

snakeorm/metadata/json_storage.py

@@ -0,0 +1,21 @@
+"""How a `dict` is backed in the database: normalised binary or exact text."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class SnakeJsonStorage(StrEnum):
+    """The DB object that stores a `dict`.
+
+    Members = the literal name of the type in Postgres; the dialect translates (SQLite collapses
+    both to TEXT).
+
+    - `JSONB` (default): binary, indexable, NORMALISES (reorders keys, drops duplicates, loses
+      `100.0` vs `100`). What nearly every real case wants.
+    - `JSON`: stores the text as-is (not indexable, preserved bit for bit). It also makes Postgres
+      line up with SQLite.
+    """
+
+    JSONB = "JSONB"  # binary, indexable, normalised — DEFAULT
+    JSON = "JSON"  # exact text, not indexable

snakeorm/metadata/polymorphic.py

@@ -0,0 +1,30 @@
+"""POLYMORPHIC inheritance: several classes share ONE table and are told apart by a column.
+
+Against concrete inheritance (a table per class, duplicated columns), here `session.all(Animal)`
+returns `Dog`/`Cat` with their real class and `session.all(Dog)` filters by the discriminator.
+The metadata is just two strings (column and value): no references to Python classes, because this
+travels into a rendered migration file and a class reference would couple it to the generating code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class SnakePolymorphicInfo:
+    """How a class takes part in a polymorphic hierarchy.
+
+    `column` (the discriminator) is carried by every class. `value` is `None` on the BASE (which
+    sees the whole hierarchy) and, on each CHILD, its own value, used as an automatic filter and on
+    insert. An optional field instead of a separate `is_base`: two fields would allow illegal
+    combinations.
+    """
+
+    column: str
+    value: str | None = None
+
+    @property
+    def is_base(self) -> bool:
+        """The root of the hierarchy: the one that sees every row, no discriminator filter."""
+        return self.value is None

snakeorm/metadata/primary_key.py

@@ -0,0 +1,23 @@
+"""Immutable metadata of the primary key (simple or composite)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from snakeorm.metadata.column import SnakeColumnInfo
+
+
+@dataclass(frozen=True, slots=True)
+class SnakePrimaryKeyInfo:
+    """Primary key as a tuple of columns.
+
+    ONE single structure for a simple PK (1 column) and a composite one (N columns): no special
+    cases. Order is preserved because it matters for mapping FKs by position.
+    """
+
+    columns: tuple[SnakeColumnInfo, ...]
+
+    @property
+    def is_composite(self) -> bool:
+        """Tells whether the key spans more than one column."""
+        return len(self.columns) > 1

snakeorm/metadata/relationship.py

@@ -0,0 +1,60 @@
+"""Immutable metadata of a relationship between models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from snakeorm.metadata.foreign_key import SnakeForeignKeyInfo
+from snakeorm.metadata.relationship_kind import SnakeRelationshipKind
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeThroughInfo:
+    """The BRIDGE of a many-to-many: its table and both hops, already resolved.
+
+    `to_parent`/`to_target` are `(bridge_column, endpoint_column)` pairs, resolved by the linker and
+    not by name (bug #14: resolving by class name sent the FK to a different table with the same
+    name). A composite FK fits with no special case: tuples of pairs, as in `SnakeForeignKeyInfo`.
+    """
+
+    table: str
+    """The bridge's table, QUALIFIED (`schema.table`)."""
+    to_parent: tuple[tuple[str, str], ...]
+    to_target: tuple[tuple[str, str], ...]
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeRelationshipInfo:
+    """A navigation view over an FK.
+
+    `kind` tells to_one (`user.owner` -> `User`) apart from to_many (`country.cities` ->
+    `list[City]`). `target` is the NAME of the target model.
+
+    `target_table` is that target already resolved and qualified (`schema.table`). It exists
+    because a class name does not identify a model (two apps each with their own `Customer`; the
+    index keyed by `__name__` was kept by whichever registered last -> FK to the wrong table,
+    depending on import order). The qualified table IS unique (the registry's collision guard).
+
+    A DERIVED field, not a declared one: the linker fills it in, it is NOT serialised and does NOT
+    enter the diff. Old migrations keep replaying with an empty `target_table` and fall back to
+    resolving by name.
+    """
+
+    name: str
+    target: str
+    kind: SnakeRelationshipKind
+    foreign_key: SnakeForeignKeyInfo
+    through: SnakeThroughInfo | None = None
+    """The bridge, only on `to_many_through`. It tells a to-many over a direct FK apart from one
+    that crosses an intermediate table: they load differently, and mixing them up would fire a
+    select-in against the wrong table."""
+    target_table: str = ""
+
+    def __post_init__(self) -> None:
+        """Normalises `kind` to the enum, accepting the string of already-written history.
+
+        Converting at the boundary lets everything inside compare with `is`, no exceptions.
+        `object.__setattr__` because the dataclass is `frozen` (the same mechanism the generated
+        `__init__` uses).
+        """
+        object.__setattr__(self, "kind", SnakeRelationshipKind.coerce(self.kind))

snakeorm/metadata/relationship_kind.py

@@ -0,0 +1,43 @@
+"""What CARDINALITY a relationship has: one, many, or many through a bridge."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SnakeRelationshipKind(Enum):
+    """Cardinality of a relationship. An enum, not a `Literal[...]` of strings, on purpose.
+
+    A `Literal` protects assignment but NOT comparison, and every use of the field is a comparison
+    (`rel.kind == "to_onee"` compiles clean in both checkers and switches off a branch without
+    warning: a JOIN that never gets emitted, an FK that never gets created). The enum makes the typo
+    unwritable. Same decision as `SnakeTableKind`.
+
+    - `TO_ONE`: FK. This model points to ONE on the other side.
+    - `TO_MANY`: the inverse. N on the other side point here.
+    - `TO_MANY_THROUGH`: many-to-many via a DECLARED bridge model.
+    """
+
+    TO_ONE = "to_one"
+    TO_MANY = "to_many"
+    TO_MANY_THROUGH = "to_many_through"
+
+    @classmethod
+    def coerce(cls, value: object) -> SnakeRelationshipKind:
+        """Accepts the enum, or the string carried by already-generated history.
+
+        Old migrations carry the literal string (`"to_one"`) and are immutable; without converting,
+        `is` comparisons would return `False` (the very silent failure the enum came to kill off).
+        An unknown value blows up HERE, not twelve branches later.
+        """
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, str):
+            try:
+                return cls(value)
+            except ValueError:
+                pass
+        valid = ", ".join(repr(member.value) for member in cls)
+        raise ValueError(
+            f"Invalid relationship cardinality: {value!r}. The available ones are: {valid}."
+        )

snakeorm/metadata/routine.py

@@ -0,0 +1,26 @@
+"""Immutable metadata of a DB ROUTINE (stored function or procedure).
+
+OPAQUE SQL that lives in the DB: the ORM does not check what it does. `body` is the whole
+`CREATE [OR REPLACE] FUNCTION ...`, raw and non-portable; with no columns to diff, the diff only
+compares the `body` string. It is declared with `snake_function(...)` and autodetect emits
+Create/Alter/DropFunction.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from snakeorm.core.placement import DEFAULT_SCHEMA
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeRoutineInfo:
+    """Metadata of a routine: name, raw SQL body and schema.
+
+    `body` is the whole `CREATE OR REPLACE FUNCTION ...` (opaque): the diff only compares the
+    string, and the creation DDL IS the body itself.
+    """
+
+    name: str
+    body: str
+    schema: str = DEFAULT_SCHEMA

snakeorm/metadata/server_default.py

@@ -0,0 +1,20 @@
+"""Default value set by the SERVER (not by the Python client)."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SnakeServerDefault(Enum):
+    """Default value generated by the DATABASE when the row is inserted.
+
+    Unlike `default` (a literal in the INSERT) and `default_factory` (a client-side callable), it
+    OMITS the column from the INSERT so the server fills it in, and the RETURNING brings it back.
+    Engine-agnostic values (not SQL): the dialect translates (`dialect.server_default_sql`).
+    """
+
+    NOW = "now"  # the server's current timestamp
+    UUID_V4 = "uuid_v4"  # random uuid (version 4) generated by the DB
+    TRUE = "true"  # boolean true
+    FALSE = "false"  # boolean false
+    ZERO = "zero"  # numeric zero