python-corekit 0.1.0__py3-none-any.whl

corekit/connections/sql/fields/jsonb.py

@@ -0,0 +1,67 @@
+"""
+Columns that store a Pydantic model as JSON.
+
+``JSONBField`` round-trips a model through a JSON column, so a table can hold
+structured data without a separate table and without hand-written encoding at
+every call site::
+
+    class Profile(BaseModel):
+        theme: str = "dark"
+
+    class User(NamedTable, table=True):
+        id: str = Field(primary_key=True)
+        profile: Profile = JSONBField(Profile)
+
+Reading ``user.profile`` gives a ``Profile``, not a dict.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel
+from sqlalchemy import Column
+from sqlalchemy.types import JSON, TypeDecorator
+from sqlmodel import Field
+
+__all__ = ["JSONBField", "PydanticJSON"]
+
+
+class PydanticJSON(TypeDecorator):
+    """
+    A JSON column that decodes into a Pydantic model on the way out.
+    """
+
+    impl = JSON
+    cache_ok = True
+
+    def __init__(self, pydantic_model: type[BaseModel], *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.pydantic_model = pydantic_model
+
+    def process_bind_param(self, value: Any, dialect: Any) -> Any:
+        """
+        Encode a model, or an already-plain dict, for storage.
+        """
+        if value is None:
+            return None
+        if isinstance(value, BaseModel):
+            return value.model_dump(mode="json", exclude_unset=True)
+        if isinstance(value, dict):
+            return value
+        raise TypeError(
+            f"{type(self).__name__} expected {self.pydantic_model.__name__}, dict or None, got {type(value).__name__}"
+        )
+
+    def process_result_value(self, value: Any, dialect: Any) -> Any:
+        """
+        Decode stored JSON back into the model.
+        """
+        if value is None:
+            return None
+        return self.pydantic_model(**value)
+
+
+def JSONBField(pydantic_model: type[BaseModel], **kwargs: Any) -> Any:  # noqa: N802 - reads as a field constructor
+    """
+    Declare a column holding ``pydantic_model`` as JSON.
+    """
+    return Field(sa_column=Column(PydanticJSON(pydantic_model)), **kwargs)

corekit/connections/sql/migration/__init__.py

@@ -0,0 +1,57 @@
+"""
+Schema migrations with checksummed history.
+
+Define a migration by subclassing ``Migration`` and listing its operations::
+
+    class AddUserFlag(Migration):
+        version = 1
+        name = "user_is_active"
+        description = "Adds the is_active flag to users."
+
+        def operations(self) -> list[Operation]:
+            return [AddColumn(table="user", column="is_active", dtype="BOOLEAN", default="true")]
+
+Collect them from a package and run them::
+
+    MigrationRegistry.discover(my_app.migrations).run(conn)
+
+Each migration's checksum is taken over what its operations *do*, not over the
+SQL they render, so reformatting is safe but changing an already-applied
+migration is caught at startup.
+"""
+
+from corekit.connections.sql.migration.base import Migration
+from corekit.connections.sql.migration.operations import (
+    AddColumn,
+    AlterColumnType,
+    CreateIndex,
+    DataOperation,
+    DropColumn,
+    DropColumnDefault,
+    DropIndex,
+    DropTable,
+    Operation,
+    RenameColumn,
+    RenameTable,
+    SetColumnDefault,
+)
+from corekit.connections.sql.migration.registry import MigrationChecksumError, MigrationRegistry
+from corekit.connections.sql.migration.table import SchemaMigration
+
+__all__ = [
+    "AddColumn",
+    "AlterColumnType",
+    "CreateIndex",
+    "DataOperation",
+    "DropColumn",
+    "DropColumnDefault",
+    "DropIndex",
+    "DropTable",
+    "Migration",
+    "MigrationChecksumError",
+    "MigrationRegistry",
+    "Operation",
+    "RenameColumn",
+    "RenameTable",
+    "SchemaMigration",
+]

corekit/connections/sql/migration/base.py

@@ -0,0 +1,40 @@
+"""
+Base class for all migrations.
+
+A Migration is defined by:
+  - version:     unique positive integer, determines execution order
+  - name:        short human-readable label (used in logs and the DB table)
+  - description: longer explanation of what and why
+  - operations:  ordered list of Operation instances to execute
+
+The checksum is computed at class definition time from the canonical
+representations of all operations. It is stored in the schema_migration
+table when the migration is applied, and verified on every subsequent
+startup. A mismatch means the migration was changed after being applied
+and will cause a hard crash.
+"""
+
+import hashlib
+from abc import ABC, abstractmethod
+
+from corekit.connections.sql.migration.operations import Operation
+
+
+class Migration(ABC):
+    version: int
+    name: str
+    description: str
+
+    @abstractmethod
+    def operations(self) -> list[Operation]:
+        raise NotImplementedError
+
+    @property
+    def checksum(self) -> str:
+        canonical = "\n".join(op.canonical() for op in self.operations())
+        return hashlib.sha256(canonical.encode()).hexdigest()
+
+    def __repr__(self) -> str:
+        version = getattr(self, "version", None)
+        name = getattr(self, "name", None)
+        return f"{type(self).__name__}(version={version}, name={name!r})"

corekit/connections/sql/migration/operations.py

@@ -0,0 +1,416 @@
+"""
+Migration operations.
+
+Each Operation knows how to:
+  - render itself to SQL (for execution) OR execute Python logic
+  - render a canonical string (for checksumming)
+
+The canonical string must be deterministic and change whenever the
+operation's intent changes — it is intentionally human-readable so that
+diffs are obvious in code review.
+
+Operations use keyword-only arguments to keep call sites explicit and readable.
+
+The SQL rendered here targets Postgres. Most of it is standard and works on
+SQLite too, but SQLite cannot drop or alter a column in place, so those
+operations will fail there.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from corekit.connections.sql.connection import SQLConnection
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+ALTER = "ALTER"
+ADD = "ADD"
+DROP = "DROP"
+
+# Entities
+COLUMN = "COLUMN"
+INDEX = "INDEX"
+TABLE = "TABLE"
+TYPE = "TYPE"
+USING = "USING"
+
+DEFAULT = "DEFAULT"
+IF_EXISTS = "IF EXISTS"
+IF_NOT_EXISTS = "IF NOT EXISTS"
+NOT_NULL = "NOT NULL"
+
+
+# ---------------------------------------------------------------------------
+# Base classes
+# ---------------------------------------------------------------------------
+class QueryBuilder:
+    """ """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        self._query = ""
+
+    def __repr__(self) -> str:
+        return self.build()
+
+    def __str__(self) -> str:
+        return self.build()
+
+    @staticmethod
+    def _build_subcommand(command: str, entity: str, name: str | None = None) -> str:
+        """
+        Build a subcommand for the query
+        """
+        subcommand = f"{command} {entity} "
+        if name:
+            subcommand += f"{name} "
+        return subcommand
+
+    def append(self, part: str) -> QueryBuilder:
+        """
+        Append a string to the query
+        """
+        self._query += f"{part} "
+        return self
+
+    def extend(self, *parts: str) -> QueryBuilder:
+        """
+        Append multiple strings to the query
+        """
+        self._query += " ".join(parts) + " "
+        return self
+
+    def alter(self, entity: str, name: str | None = None) -> QueryBuilder:
+        """
+        Append ALTER command to the query
+        """
+        self._query += self._build_subcommand(ALTER, entity, name)
+        return self
+
+    def add(self, entity: str) -> QueryBuilder:
+        """
+        Append ADD command to the query
+        """
+        self._query += f"{ADD} {entity} "
+        return self
+
+    def drop(self, entity: str, name: str | None = None) -> QueryBuilder:
+        """
+        Append DROP command to the query
+        """
+        self._query += self._build_subcommand(DROP, entity, name)
+        return self
+
+    def not_null(self) -> QueryBuilder:
+        """
+        Append NOT NULL to the query
+        """
+        self._query += f"{NOT_NULL} "
+        return self
+
+    def if_not_exists(self) -> QueryBuilder:
+        """
+        Append IF NOT EXISTS to the query
+        """
+        self._query += f"{IF_NOT_EXISTS} "
+        return self
+
+    def if_exists(self) -> QueryBuilder:
+        """
+        Append IF EXISTS to the query
+        """
+        self._query += f"{IF_EXISTS} "
+        return self
+
+    def default(self, default: str) -> QueryBuilder:
+        self._query += f"{DEFAULT} {default} "
+        return self
+
+    def set_default(self, default: str) -> QueryBuilder:
+        self._query += f"SET {DEFAULT} {default} "
+        return self
+
+    def drop_default(self) -> QueryBuilder:
+        self._query += f"DROP {DEFAULT} "
+        return self
+
+    def type(self, name: str) -> QueryBuilder:
+        self._query += f"{TYPE} {name} "
+        return self
+
+    def using(self, name: str) -> QueryBuilder:
+        self._query += f"{USING} {name} "
+        return self
+
+    def build(self) -> str:
+        return self._query.strip()
+
+
+class Operation(ABC):
+    """
+    Base class for all operations.
+    """
+
+    def _builder(self) -> QueryBuilder:
+        return QueryBuilder()
+
+    @abstractmethod
+    def to_sql(self) -> str:
+        """
+        Render the SQL to execute against the database
+
+        Each sub-class must implement this method and provide and example in the docstring.
+        Examples must use the format:
+
+        Example: <PRE-DEFINED_COMMAND> <table_name> <PRE-DEFINED_COMMAND> [IF NOT EXISTS] <column_name> <dtype>
+
+        Where:
+        - <PRE-DEFINED_COMMAND>: (all-caps inside <>) represents a pre-defined SQL command unique to the sub-class
+        - <*>: (lowercase inside <>) represents a placeholder variable added at runtime
+        - [*]: (anything inside []) represents an optional part of the command
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def canonical(self) -> str:
+        """
+        Deterministic string representation used for checksumming
+        """
+        raise NotImplementedError
+
+    def __repr__(self) -> str:
+        return self.canonical()
+
+
+# ---------------------------------------------------------------------------
+# Column operations
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class AddColumn(Operation):
+    """
+    Add a column to an existing table.
+
+    ``safe`` emits ``IF NOT EXISTS``, which Postgres accepts and SQLite does
+    not. Set it to False when targeting SQLite.
+    """
+
+    table: str
+    column: str
+    dtype: str
+    safe: bool = True
+    nullable: bool = True
+    default: str | None = None
+
+    def to_sql(self) -> str:
+        """
+        Example: ALTER TABLE <table_name> ADD COLUMN [IF NOT EXISTS] <column_name> <dtype>
+        """
+        builder = self._builder().alter(TABLE, self.table).add(COLUMN)
+        if self.safe:
+            builder.if_not_exists()
+
+        builder.append(self.column).append(self.dtype)
+        if self.default is not None:
+            builder.default(self.default)
+
+        if not self.nullable:
+            builder.not_null()
+
+        return builder.build()
+
+    def canonical(self) -> str:
+        return (
+            f"AddColumn(table={self.table}, column={self.column}, dtype={self.dtype}, "
+            f"nullable={self.nullable}, default={self.default})"
+        )
+
+
+@dataclass
+class DropColumn(Operation):
+    table: str
+    column: str
+
+    def to_sql(self) -> str:
+        """
+        Example: ALTER TABLE <table_name> DROP COLUMN [IF EXISTS] <column_name>
+        """
+        return self._builder().alter(TABLE, self.table).drop(COLUMN).if_exists().append(self.column).build()
+
+    def canonical(self) -> str:
+        return f"DropColumn(table={self.table}, column={self.column})"
+
+
+@dataclass
+class AlterColumnType(Operation):
+    table: str
+    column: str
+    new_dtype: str
+    using: str | None = None
+
+    def to_sql(self) -> str:
+        """
+        Example: ALTER TABLE <table_name> ALTER COLUMN <column_name> TYPE <new_dtype> [USING <using>]
+        """
+        builder = self._builder().alter(TABLE, self.table).alter(COLUMN, self.column).type(self.new_dtype)
+        if self.using:
+            builder.using(self.using)
+
+        return builder.build()
+
+    def canonical(self) -> str:
+        return (
+            f"AlterColumnType(table={self.table}, column={self.column}, new_dtype={self.new_dtype}, using={self.using})"
+        )
+
+
+@dataclass
+class SetColumnDefault(Operation):
+    table: str
+    column: str
+    default: str
+
+    def to_sql(self) -> str:
+        """
+        Example: ALTER TABLE <table_name> ALTER COLUMN <column_name> SET DEFAULT <default>
+        """
+        return self._builder().alter(TABLE, self.table).alter(COLUMN, self.column).set_default(self.default).build()
+
+    def canonical(self) -> str:
+        return f"SetColumnDefault(table={self.table}, column={self.column}, default={self.default})"
+
+
+@dataclass
+class DropColumnDefault(Operation):
+    table: str
+    column: str
+
+    def to_sql(self) -> str:
+        """
+        Example: ALTER TABLE <table_name> ALTER COLUMN <column_name> DROP DEFAULT
+        """
+        return self._builder().alter(TABLE, self.table).alter(COLUMN, self.column).drop_default().build()
+
+    def canonical(self) -> str:
+        return f"DropColumnDefault(table={self.table}, column={self.column})"
+
+
+# ---------------------------------------------------------------------------
+# Index operations
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CreateIndex(Operation):
+    index_name: str
+    table: str
+    columns: list[str]
+    unique: bool = False
+
+    def to_sql(self) -> str:
+        unique_clause = "UNIQUE " if self.unique else ""
+        cols = ", ".join(self.columns)
+        return f"CREATE {unique_clause}INDEX IF NOT EXISTS {self.index_name} ON {self.table} ({cols})"
+
+    def canonical(self) -> str:
+        return f"CreateIndex(name={self.index_name}, table={self.table}, columns={self.columns}, unique={self.unique})"
+
+
+@dataclass
+class DropIndex(Operation):
+    index_name: str
+
+    def to_sql(self) -> str:
+        return f"DROP INDEX IF EXISTS {self.index_name}"
+
+    def canonical(self) -> str:
+        return f"DropIndex(name={self.index_name})"
+
+
+# ---------------------------------------------------------------------------
+# Table operations
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DropTable(Operation):
+    table: str
+    cascade: bool = False
+
+    def to_sql(self) -> str:
+        cascade_clause = " CASCADE" if self.cascade else ""
+        return f"DROP TABLE IF EXISTS {self.table}{cascade_clause}"
+
+    def canonical(self) -> str:
+        return f"DropTable(table={self.table}, cascade={self.cascade})"
+
+
+@dataclass
+class RenameTable(Operation):
+    old_name: str
+    new_name: str
+
+    def to_sql(self) -> str:
+        return f"ALTER TABLE {self.old_name} RENAME TO {self.new_name}"
+
+    def canonical(self) -> str:
+        return f"RenameTable(old={self.old_name}, new={self.new_name})"
+
+
+@dataclass
+class RenameColumn(Operation):
+    table: str
+    old_name: str
+    new_name: str
+
+    def to_sql(self) -> str:
+        return f"ALTER TABLE {self.table} RENAME COLUMN {self.old_name} TO {self.new_name}"
+
+    def canonical(self) -> str:
+        return f"RenameColumn(table={self.table}, old={self.old_name}, new={self.new_name})"
+
+
+# ---------------------------------------------------------------------------
+# Data operations
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DataOperation(Operation):
+    """
+    Executes a Python function for data migrations (seeding, transformations).
+
+    The function receives a SQLConnection and should use ORM methods to
+    read/write data. The `name` is used for checksumming - changing it will
+    invalidate the checksum, so choose a stable, descriptive name.
+
+    Example:
+        DataOperation(
+            name="seed_user_permissions_v1",
+            func=seed_permissions_from_roles,
+        )
+
+    IMPORTANT: It is not appropriate to use DataOperation in place of other operations. This is
+    reserved for the most complex operations that CANNOT be expressed otherwise.
+    """
+
+    name: str
+    func: Callable[[SQLConnection], None]
+
+    def execute(self, conn: SQLConnection) -> None:
+        """
+        Execute the data operation with the given connection
+        """
+        self.func(conn)
+
+    def to_sql(self) -> str:
+        raise NotImplementedError("DataOperation does not produce SQL; use execute() instead")
+
+    def canonical(self) -> str:
+        return f"DataOperation(name={self.name})"