swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/database/identifiers.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "MAX_IDENTIFIER_LENGTH",
+    "quote_identifier",
+    "validate_column_identifier",
+    "validate_identifier",
+]
+
+MAX_IDENTIFIER_LENGTH: int = 63
+
+_IDENTIFIER_RE: re.Pattern[str] = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+_COLUMN_RE: re.Pattern[str] = re.compile(
+    r"^(?:"
+    r"\*"
+    r"|"
+    r"[a-zA-Z_][a-zA-Z0-9_]*"
+    r"(?:\.(?:[a-zA-Z_][a-zA-Z0-9_]*|\*))?"
+    r")$"
+)
+
+
+def validate_identifier(
+    identifier: str,
+    *,
+    allow_dotted: bool = False,
+    allow_wildcard: bool = False,
+    param_name: str | None = None,
+) -> str:
+    """
+    Validate that an SQL identifier is secure, strictly alphanumeric/underscores,
+    within the 63-character PostgreSQL identifier limit, and contains no newlines or SQL injection.
+    """
+    if not isinstance(identifier, str):
+        msg = (
+            f"Invalid {param_name} identifier '{identifier}'"
+            if param_name
+            else f"Invalid SQL identifier detected: {identifier}"
+        )
+        raise TypeError(msg)
+
+    if allow_wildcard and identifier == "*":
+        return identifier
+
+    if not identifier:
+        msg = (
+            f"Invalid {param_name} identifier '{identifier}'"
+            if param_name
+            else f"Invalid SQL identifier detected: {identifier}"
+        )
+        raise ValueError(msg)
+
+    segments = identifier.split(".") if allow_dotted else [identifier]
+    for seg in segments:
+        if allow_wildcard and seg == "*":
+            continue
+        if len(seg) > MAX_IDENTIFIER_LENGTH or not _IDENTIFIER_RE.fullmatch(seg):
+            msg = (
+                f"Invalid {param_name} identifier '{identifier}'"
+                if param_name
+                else f"Invalid SQL identifier detected: {identifier}"
+            )
+            raise ValueError(msg)
+
+    return identifier
+
+
+def validate_column_identifier(column: str) -> str:
+    """
+    Validate a column identifier used in projections, supporting '*' or 'table.*' or 'table.column'.
+    """
+    if not isinstance(column, str):
+        raise TypeError(
+            f"Invalid SQL column identifier type: expected str, got {type(column).__name__}"
+        )
+    if not _COLUMN_RE.fullmatch(column):
+        raise ValueError(f"Invalid SQL column identifier detected: {column}")
+
+    segments = column.split(".")
+    for seg in segments:
+        if seg != "*" and len(seg) > MAX_IDENTIFIER_LENGTH:
+            raise ValueError(f"Invalid SQL column identifier detected: {column}")
+
+    return column
+
+
+def quote_identifier(
+    identifier: str,
+    *,
+    allow_dotted: bool = True,
+    allow_wildcard: bool = True,
+) -> str:
+    """Validate, then quote each dotted segment: t.col becomes "t"."col"."""
+    validate_identifier(
+        identifier,
+        allow_dotted=allow_dotted,
+        allow_wildcard=allow_wildcard,
+    )
+    if identifier == "*":
+        return "*"
+    return ".".join(
+        f'"{part}"' if part != "*" else "*" for part in identifier.split(".")
+    )

swiftpy/database/migrations/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from swiftpy.database.migrations.blueprint import (
+    Blueprint,
+    ColumnDefinition,
+    DefaultRaw,
+    ForeignKeyDefinition,
+    IndexDefinition,
+    raw,
+)
+from swiftpy.database.migrations.lock import MigrationLock, MigrationLockError
+from swiftpy.database.migrations.migration import Migration, MigrationProtocol
+from swiftpy.database.migrations.migrator import (
+    MigrationFile,
+    MigrationRecord,
+    Migrator,
+)
+from swiftpy.database.migrations.schema import Schema, SchemaGrammar
+
+__all__ = [
+    "Blueprint",
+    "ColumnDefinition",
+    "DefaultRaw",
+    "ForeignKeyDefinition",
+    "IndexDefinition",
+    "Migration",
+    "MigrationFile",
+    "MigrationLock",
+    "MigrationLockError",
+    "MigrationProtocol",
+    "MigrationRecord",
+    "Migrator",
+    "Schema",
+    "SchemaGrammar",
+    "raw",
+]

swiftpy/database/migrations/blueprint.py

@@ -0,0 +1,431 @@
+from __future__ import annotations
+
+from typing import Any, Self
+
+from swiftpy.database.identifiers import validate_identifier
+
+__all__ = [
+    "ALLOWED_COLUMN_TYPES",
+    "Blueprint",
+    "ColumnDefinition",
+    "DefaultRaw",
+    "ForeignKeyDefinition",
+    "IndexDefinition",
+    "raw",
+    "validate_identifier",
+]
+
+_UNSET = object()
+
+ALLOWED_COLUMN_TYPES: frozenset[str] = frozenset(
+    {
+        "id",
+        "increments",
+        "big_increments",
+        "uuid",
+        "string",
+        "text",
+        "integer",
+        "big_integer",
+        "small_integer",
+        "boolean",
+        "decimal",
+        "float",
+        "json",
+        "jsonb",
+        "date",
+        "time",
+        "timestamp",
+        "timestamptz",
+        "vector",
+    }
+)
+
+
+def _validate_column_length(length: int | None) -> int | None:
+    if length is None:
+        return None
+    if (
+        isinstance(length, bool)
+        or not isinstance(length, int)
+        or length < 1
+        or length > 10_485_760
+    ):
+        raise ValueError(
+            f"Column length must be an integer between 1 and 10485760, got {length!r}"
+        )
+    return length
+
+
+def _validate_decimal_params(precision: int, scale: int) -> tuple[int, int]:
+    if (
+        isinstance(precision, bool)
+        or not isinstance(precision, int)
+        or precision < 1
+        or precision > 1000
+    ):
+        raise ValueError(
+            f"Decimal precision must be an integer between 1 and 1000, got {precision!r}"
+        )
+    if (
+        isinstance(scale, bool)
+        or not isinstance(scale, int)
+        or scale < 0
+        or scale > precision
+    ):
+        raise ValueError(
+            f"Decimal scale must be an integer between 0 and {precision}, got {scale!r}"
+        )
+    return precision, scale
+
+
+class DefaultRaw:
+    """Explicit marker for raw SQL default expressions in migrations (e.g. raw('now()'))."""
+
+    def __init__(self, sql: str) -> None:
+        if not isinstance(sql, str) or not sql.strip():
+            raise ValueError("Raw SQL default expression must be a non-empty string.")
+        self.sql: str = sql.strip()
+
+
+def raw(sql: str) -> DefaultRaw:
+    """Wrap a trusted SQL expression for use in ColumnDefinition.default()."""
+    return DefaultRaw(sql)
+
+
+class ColumnDefinition:
+    """Represents a fluent column definition inside a table blueprint."""
+
+    def __init__(self, name: str, type_name: str) -> None:
+        self.name: str = validate_identifier(name)
+        normalized_type = (
+            type_name.strip().lower() if isinstance(type_name, str) else ""
+        )
+        if normalized_type not in ALLOWED_COLUMN_TYPES:
+            raise ValueError(f"Unsupported column type: {type_name!r}")
+        self.type_name: str = normalized_type
+        self.length: int | None = None
+        self.precision: int | None = None
+        self.scale: int | None = None
+        self.is_nullable: bool = False
+        self.is_unique: bool = False
+        self.is_primary: bool = False
+        self.default_val: Any = _UNSET
+        self.is_index: bool = False
+        self.index_name: str | None = None
+        self.dimensions: int | None = None
+        self.comment_text: str | None = None
+        self.is_unsigned: bool = False
+
+    def nullable(self, value: bool = True) -> Self:
+        """Specify whether the column may accept NULL values."""
+        self.is_nullable = value
+        return self
+
+    def default(self, value: Any) -> Self:
+        """Specify the default value for the column."""
+        self.default_val = value
+        return self
+
+    def unique(self, name: str | None = None) -> Self:
+        """Add a unique constraint or index for this column."""
+        self.is_unique = True
+        if name:
+            self.index_name = validate_identifier(name)
+        return self
+
+    def index(self, name: str | None = None) -> Self:
+        """Add an index for this column."""
+        self.is_index = True
+        if name:
+            self.index_name = validate_identifier(name)
+        return self
+
+    def primary(self) -> Self:
+        """Mark this column as the primary key."""
+        self.is_primary = True
+        return self
+
+    def comment(self, text: str) -> Self:
+        """Set a comment on this column."""
+        self.comment_text = text
+        return self
+
+    def unsigned(self) -> Self:
+        """Mark an integer column as unsigned."""
+        self.is_unsigned = True
+        return self
+
+
+class ForeignKeyDefinition:
+    """Represents a fluent foreign key constraint definition."""
+
+    def __init__(self, column: str, name: str | None = None) -> None:
+        self.column: str = validate_identifier(column)
+        self.name: str | None = validate_identifier(name) if name else None
+        self.ref_column: str = "id"
+        self.ref_table: str | None = None
+        self.on_delete_action: str = "NO ACTION"
+        self.on_update_action: str = "NO ACTION"
+
+    def references(self, column: str) -> Self:
+        """Specify the referenced column on the foreign table."""
+        self.ref_column = validate_identifier(column)
+        return self
+
+    def on(self, table: str) -> Self:
+        """Specify the referenced foreign table."""
+        self.ref_table = validate_identifier(table)
+        return self
+
+    def on_delete(self, action: str) -> Self:
+        """Set ON DELETE referential action."""
+        action_clean = action.strip().upper()
+        allowed = {"CASCADE", "SET NULL", "SET DEFAULT", "RESTRICT", "NO ACTION"}
+        if action_clean not in allowed:
+            raise ValueError(f"Invalid ON DELETE action: {action!r}")
+        self.on_delete_action = action_clean
+        return self
+
+    def on_update(self, action: str) -> Self:
+        """Set ON UPDATE referential action."""
+        action_clean = action.strip().upper()
+        allowed = {"CASCADE", "SET NULL", "SET DEFAULT", "RESTRICT", "NO ACTION"}
+        if action_clean not in allowed:
+            raise ValueError(f"Invalid ON UPDATE action: {action!r}")
+        self.on_update_action = action_clean
+        return self
+
+    def cascade_on_delete(self) -> Self:
+        """Convenience method for ON DELETE CASCADE."""
+        return self.on_delete("CASCADE")
+
+    def cascade_on_update(self) -> Self:
+        """Convenience method for ON UPDATE CASCADE."""
+        return self.on_update("CASCADE")
+
+    def null_on_delete(self) -> Self:
+        """Convenience method for ON DELETE SET NULL."""
+        return self.on_delete("SET NULL")
+
+
+class IndexDefinition:
+    """Represents a table-level index or composite unique constraint."""
+
+    def __init__(
+        self,
+        columns: list[str],
+        name: str | None = None,
+        *,
+        is_unique: bool = False,
+    ) -> None:
+        self.columns: list[str] = [validate_identifier(c) for c in columns]
+        self.name: str | None = validate_identifier(name) if name else None
+        self.is_unique: bool = is_unique
+
+
+class Blueprint:
+    """Table definition Domain-Specific Language (DSL) for schema creation and modification."""
+
+    def __init__(self, table: str, *, is_create: bool = True) -> None:
+        self.table: str = validate_identifier(table)
+        self.is_create: bool = is_create
+        self.columns: list[ColumnDefinition] = []
+        self.foreign_keys: list[ForeignKeyDefinition] = []
+        self.indexes: list[IndexDefinition] = []
+        self.primary_columns: list[str] = []
+        self.primary_key_name: str | None = None
+        self.drop_columns_list: list[str] = []
+        self.rename_columns_map: dict[str, str] = {}
+        self.drop_indexes_list: list[str] = []
+        self.drop_unique_list: list[str] = []
+        self.drop_foreign_list: list[str] = []
+
+    def _add_column(self, name: str, type_name: str) -> ColumnDefinition:
+        col = ColumnDefinition(name, type_name)
+        self.columns.append(col)
+        return col
+
+    # --- Identity & Primary Keys ---
+
+    def id(self, name: str = "id") -> ColumnDefinition:
+        """Create a Bigint auto-incrementing identity primary key."""
+        col = self._add_column(name, "id")
+        col.is_primary = True
+        return col
+
+    def increments(self, name: str = "id") -> ColumnDefinition:
+        """Create a 32-bit serial auto-incrementing primary key."""
+        col = self._add_column(name, "increments")
+        col.is_primary = True
+        return col
+
+    def big_increments(self, name: str = "id") -> ColumnDefinition:
+        """Create a 64-bit bigserial auto-incrementing primary key."""
+        col = self._add_column(name, "big_increments")
+        col.is_primary = True
+        return col
+
+    # --- Data Types ---
+
+    def uuid(self, name: str) -> ColumnDefinition:
+        """Create a UUID column."""
+        return self._add_column(name, "uuid")
+
+    def string(self, name: str, length: int | None = 255) -> ColumnDefinition:
+        """Create a VARCHAR string column with optional max length."""
+        validated_length = _validate_column_length(length)
+        col = self._add_column(name, "string")
+        col.length = validated_length
+        return col
+
+    def text(self, name: str) -> ColumnDefinition:
+        """Create a TEXT column."""
+        return self._add_column(name, "text")
+
+    def integer(self, name: str) -> ColumnDefinition:
+        """Create a standard 32-bit INTEGER column."""
+        return self._add_column(name, "integer")
+
+    def big_integer(self, name: str) -> ColumnDefinition:
+        """Create a 64-bit BIGINT column."""
+        return self._add_column(name, "big_integer")
+
+    def small_integer(self, name: str) -> ColumnDefinition:
+        """Create a 16-bit SMALLINT column."""
+        return self._add_column(name, "small_integer")
+
+    def boolean(self, name: str) -> ColumnDefinition:
+        """Create a BOOLEAN column."""
+        return self._add_column(name, "boolean")
+
+    def decimal(
+        self, name: str, precision: int = 8, scale: int = 2
+    ) -> ColumnDefinition:
+        """Create a fixed-point NUMERIC/DECIMAL column."""
+        validated_precision, validated_scale = _validate_decimal_params(
+            precision, scale
+        )
+        col = self._add_column(name, "decimal")
+        col.precision = validated_precision
+        col.scale = validated_scale
+        return col
+
+    def float(self, name: str) -> ColumnDefinition:
+        """Create a floating-point DOUBLE PRECISION column."""
+        return self._add_column(name, "float")
+
+    def json(self, name: str) -> ColumnDefinition:
+        """Create a JSON column."""
+        return self._add_column(name, "json")
+
+    def jsonb(self, name: str) -> ColumnDefinition:
+        """Create a binary JSONB column."""
+        return self._add_column(name, "jsonb")
+
+    def date(self, name: str) -> ColumnDefinition:
+        """Create a DATE column."""
+        return self._add_column(name, "date")
+
+    def time(self, name: str) -> ColumnDefinition:
+        """Create a TIME column."""
+        return self._add_column(name, "time")
+
+    def timestamp(self, name: str, tz: bool = True) -> ColumnDefinition:
+        """Create a TIMESTAMP column (with or without time zone)."""
+        type_name = "timestamptz" if tz else "timestamp"
+        return self._add_column(name, type_name)
+
+    def timestamps(self, tz: bool = True) -> tuple[ColumnDefinition, ColumnDefinition]:
+        """Create created_at and updated_at timestamp columns with default CURRENT_TIMESTAMP."""
+        created = self.timestamp("created_at", tz=tz).default(raw("CURRENT_TIMESTAMP"))
+        updated = self.timestamp("updated_at", tz=tz).default(raw("CURRENT_TIMESTAMP"))
+        return created, updated
+
+    def soft_deletes(
+        self, name: str = "deleted_at", tz: bool = True
+    ) -> ColumnDefinition:
+        """Create a nullable deleted_at timestamp column for soft deletion."""
+        return self.timestamp(name, tz=tz).nullable()
+
+    def vector(self, name: str, dimensions: int = 1536) -> ColumnDefinition:
+        """Create a pgvector vector column with specified dimensions."""
+        if isinstance(dimensions, bool) or not isinstance(dimensions, int) or dimensions <= 0:
+            raise ValueError(
+                f"Vector dimensions must be a positive integer, got {dimensions}"
+            )
+        col = self._add_column(name, "vector")
+        col.dimensions = dimensions
+        return col
+
+    # --- Constraints & Indexes ---
+
+    def unique(self, columns: str | list[str], name: str | None = None) -> Self:
+        """Add a table-level or composite UNIQUE constraint."""
+        cols = [columns] if isinstance(columns, str) else columns
+        self.indexes.append(IndexDefinition(cols, name, is_unique=True))
+        return self
+
+    def index(self, columns: str | list[str], name: str | None = None) -> Self:
+        """Add a table-level or composite index."""
+        cols = [columns] if isinstance(columns, str) else columns
+        self.indexes.append(IndexDefinition(cols, name, is_unique=False))
+        return self
+
+    def primary(self, columns: str | list[str], name: str | None = None) -> Self:
+        """Define a table-level or composite primary key constraint."""
+        cols = [columns] if isinstance(columns, str) else columns
+        self.primary_columns = [validate_identifier(c) for c in cols]
+        if name:
+            self.primary_key_name = validate_identifier(name)
+        return self
+
+    def foreign(self, column: str, name: str | None = None) -> ForeignKeyDefinition:
+        """Define a fluent foreign key constraint on the given column."""
+        fk = ForeignKeyDefinition(column, name)
+        self.foreign_keys.append(fk)
+        return fk
+
+    def foreign_key(
+        self,
+        column: str,
+        references: str,
+        on: str,
+        on_delete: str = "NO ACTION",
+        on_update: str = "NO ACTION",
+        name: str | None = None,
+    ) -> Self:
+        """Direct helper to define a complete foreign key constraint."""
+        fk = self.foreign(column, name)
+        fk.references(references).on(on).on_delete(on_delete).on_update(on_update)
+        return self
+
+    # --- Alter Operations ---
+
+    def drop_column(self, *names: str) -> Self:
+        """Drop one or more columns from an existing table."""
+        for n in names:
+            self.drop_columns_list.append(validate_identifier(n))
+        return self
+
+    def rename_column(self, from_name: str, to_name: str) -> Self:
+        """Rename an existing column."""
+        self.rename_columns_map[validate_identifier(from_name)] = validate_identifier(
+            to_name
+        )
+        return self
+
+    def drop_index(self, name: str) -> Self:
+        """Drop an index by name."""
+        self.drop_indexes_list.append(validate_identifier(name))
+        return self
+
+    def drop_unique(self, name: str) -> Self:
+        """Drop a unique constraint by name."""
+        self.drop_unique_list.append(validate_identifier(name))
+        return self
+
+    def drop_foreign(self, name: str) -> Self:
+        """Drop a foreign key constraint by name."""
+        self.drop_foreign_list.append(validate_identifier(name))
+        return self

swiftpy/database/migrations/lock.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Self
+
+import asyncpg
+
+logger = logging.getLogger(__name__)
+
+# Deterministic 64-bit signed integer key: 'SWIFTPY' in hex -> 0x53574946545059
+DEFAULT_MIGRATION_LOCK_KEY: int = 0x53574946545059
+
+
+class MigrationLockError(RuntimeError):
+    """Raised when an advisory lock cannot be acquired or timed out."""
+
+
+class MigrationLock:
+    """
+    PostgreSQL advisory lock manager.
+
+    Prevents concurrent migration runs across distributed workers, processes,
+    or containers using native pg_try_advisory_lock / pg_advisory_unlock.
+    """
+
+    def __init__(
+        self,
+        connection: asyncpg.Connection,
+        key: int = DEFAULT_MIGRATION_LOCK_KEY,
+        timeout: float = 30.0,
+        poll_interval: float = 0.2,
+    ) -> None:
+        self.connection: asyncpg.Connection = connection
+        self.key: int = key
+        self.timeout: float = timeout
+        self.poll_interval: float = poll_interval
+        self.is_locked: bool = False
+
+    async def acquire(self) -> bool:
+        """
+        Attempt to acquire the advisory lock, polling up to the specified timeout.
+        Raises MigrationLockError if the lock cannot be acquired within the timeout window.
+        """
+        start = time.monotonic()
+
+        while True:
+            # pg_try_advisory_lock returns boolean immediately without blocking PostgreSQL backend
+            locked: bool = await self.connection.fetchval(
+                "SELECT pg_try_advisory_lock($1);", self.key
+            )
+
+            if locked:
+                self.is_locked = True
+                return True
+
+            elapsed = time.monotonic() - start
+            if elapsed >= self.timeout:
+                raise MigrationLockError(
+                    f"Failed to acquire migration advisory lock (key={hex(self.key)}) "
+                    f"after {self.timeout:.1f}s. Another migration process is currently active."
+                )
+
+            await asyncio.sleep(self.poll_interval)
+
+    async def release(self) -> bool:
+        """Release the PostgreSQL advisory lock."""
+        if not self.is_locked:
+            return False
+
+        is_closed = getattr(self.connection, "is_closed", None)
+        if callable(is_closed) and is_closed():
+            self.is_locked = False
+            return False
+
+        unlocked: bool = await self.connection.fetchval(
+            "SELECT pg_advisory_unlock($1);", self.key
+        )
+        self.is_locked = False
+        return unlocked
+
+    async def __aenter__(self) -> Self:
+        await self.acquire()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        try:
+            await self.release()
+        except Exception as release_exc:
+            if exc_type is not None:
+                logger.warning(
+                    "Failed to release migration lock (key=%s) during exception unwind (%s): %s",
+                    hex(self.key),
+                    exc_type.__name__,
+                    release_exc,
+                )
+                return
+            raise

swiftpy/database/migrations/migration.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class MigrationProtocol(Protocol):
+    """Protocol satisfied by any migration class or instance providing up/down methods."""
+
+    async def up(self) -> None: ...
+
+    async def down(self) -> None: ...
+
+
+class Migration:
+    """Base class for all SwiftPY migrations."""
+
+    async def up(self) -> None:
+        """Run the forward migration changes."""
+
+    async def down(self) -> None:
+        """Reverse the migration changes."""