pyoq-sql 1.0.2__py3-none-any.whl

pyoq/schema/models.py

@@ -0,0 +1,604 @@
+"""Immutable database schema model."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol, TypeAlias, TypeVar
+
+from pyoq.config import DatabaseDialect
+from pyoq.errors import SchemaValidationError
+
+SCHEMA_FORMAT_VERSION = 1
+UniqueValue = TypeVar("UniqueValue", bound=Hashable)
+
+
+class NamedSchemaItem(Protocol):
+    @property
+    def name(self) -> Identifier | None: ...
+
+
+JsonScalar: TypeAlias = bool | int | float | str | None
+JsonValue: TypeAlias = JsonScalar | list["JsonValue"] | dict[str, "JsonValue"]
+"""What JSON can hold, said once for everything that needs to know.
+
+A JSON number is not always whole, so a float is one of them.
+"""
+
+
+class TypeKind(StrEnum):
+    BOOLEAN = "boolean"
+    SMALL_INTEGER = "small-integer"
+    INTEGER = "integer"
+    BIG_INTEGER = "big-integer"
+    DECIMAL = "decimal"
+    REAL = "real"
+    DOUBLE = "double"
+    STRING = "string"
+    BINARY = "binary"
+    DATE = "date"
+    TIME = "time"
+    DATETIME = "datetime"
+    INTERVAL = "interval"
+    UUID = "uuid"
+    JSON = "json"
+    ENUM = "enum"
+    ARRAY = "array"
+    DOMAIN = "domain"
+    OTHER = "other"
+
+
+class GeneratedKind(StrEnum):
+    IDENTITY_ALWAYS = "identity-always"
+    IDENTITY_BY_DEFAULT = "identity-by-default"
+    COMPUTED_STORED = "computed-stored"
+    COMPUTED_VIRTUAL = "computed-virtual"
+
+
+class KeyKind(StrEnum):
+    PRIMARY = "primary"
+    UNIQUE = "unique"
+
+
+class ReferentialAction(StrEnum):
+    NO_ACTION = "no-action"
+    RESTRICT = "restrict"
+    CASCADE = "cascade"
+    SET_NULL = "set-null"
+    SET_DEFAULT = "set-default"
+
+
+class Capability(StrEnum):
+    CATALOGS = "catalogs"
+    SCHEMAS = "schemas"
+    VIEWS = "views"
+    MATERIALIZED_VIEWS = "materialized-views"
+    ENUMS = "enums"
+    ARRAYS = "arrays"
+    GENERATED_COLUMNS = "generated-columns"
+    IDENTITY_COLUMNS = "identity-columns"
+    EXPRESSION_INDEXES = "expression-indexes"
+    PARTIAL_INDEXES = "partial-indexes"
+    CHECK_CONSTRAINTS = "check-constraints"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class Identifier:
+    value: str
+
+    def __post_init__(self) -> None:
+        _require_text(self.value, "identifier")
+        if "\x00" in self.value:
+            message = "identifier cannot contain a null character"
+            raise SchemaValidationError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class ObjectReference:
+    name: Identifier
+    schema: Identifier | None = None
+    catalog: Identifier | None = None
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class MetadataEntry:
+    key: str
+    value: str
+
+    def __post_init__(self) -> None:
+        _require_text(self.key, "metadata key")
+        _require_text(self.value, "metadata value")
+
+
+@dataclass(frozen=True, slots=True)
+class SqlExpression:
+    text: str
+
+    def __post_init__(self) -> None:
+        _require_text(self.text, "SQL expression")
+
+
+@dataclass(frozen=True, slots=True)
+class SqlType:
+    kind: TypeKind
+    source_name: str
+    length: int | None = None
+    precision: int | None = None
+    scale: int | None = None
+    element_type: SqlType | None = None
+    named_type: ObjectReference | None = None
+    metadata: tuple[MetadataEntry, ...] = ()
+
+    def __post_init__(self) -> None:
+        _require_text(self.source_name, "source type name")
+        _require_positive(self.length, "type length")
+        _require_positive(self.precision, "type precision")
+        _validate_scale(self.precision, self.scale)
+        _validate_nested_type(self.kind, self.element_type, self.named_type)
+        object.__setattr__(self, "metadata", _canonical_metadata(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedValue:
+    kind: GeneratedKind
+    expression: SqlExpression | None = None
+
+    def __post_init__(self) -> None:
+        computed = self.kind in {
+            GeneratedKind.COMPUTED_STORED,
+            GeneratedKind.COMPUTED_VIRTUAL,
+        }
+        if computed != (self.expression is not None):
+            message = "computed generation requires an expression; identity does not"
+            raise SchemaValidationError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class Column:
+    name: Identifier
+    data_type: SqlType
+    nullable: bool
+    default: SqlExpression | None = None
+    generated: GeneratedValue | None = None
+    comment: str | None = None
+    metadata: tuple[MetadataEntry, ...] = ()
+
+    def __post_init__(self) -> None:
+        _validate_optional_text(self.comment, "column comment")
+        object.__setattr__(self, "metadata", _canonical_metadata(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class Key:
+    kind: KeyKind
+    columns: tuple[Identifier, ...]
+    name: Identifier | None = None
+
+    def __post_init__(self) -> None:
+        _require_identifiers(self.columns, "key columns")
+
+
+@dataclass(frozen=True, slots=True)
+class Relation:
+    columns: tuple[Identifier, ...]
+    target: ObjectReference
+    target_columns: tuple[Identifier, ...]
+    name: Identifier | None = None
+    on_update: ReferentialAction = ReferentialAction.NO_ACTION
+    on_delete: ReferentialAction = ReferentialAction.NO_ACTION
+
+    def __post_init__(self) -> None:
+        _require_identifiers(self.columns, "relation columns")
+        _require_identifiers(self.target_columns, "relation target columns")
+        if len(self.columns) != len(self.target_columns):
+            message = "relation source and target column counts must match"
+            raise SchemaValidationError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class IndexTerm:
+    column: Identifier | None = None
+    expression: SqlExpression | None = None
+    descending: bool = False
+
+    def __post_init__(self) -> None:
+        if (self.column is None) == (self.expression is None):
+            message = "index term requires exactly one column or expression"
+            raise SchemaValidationError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class Index:
+    name: Identifier
+    terms: tuple[IndexTerm, ...]
+    unique: bool = False
+    predicate: SqlExpression | None = None
+    method: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.terms:
+            message = "index must contain at least one term"
+            raise SchemaValidationError(message)
+        _validate_optional_text(self.method, "index method")
+
+
+@dataclass(frozen=True, slots=True)
+class CheckConstraint:
+    expression: SqlExpression
+    name: Identifier | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Table:
+    name: Identifier
+    columns: tuple[Column, ...]
+    keys: tuple[Key, ...] = ()
+    relations: tuple[Relation, ...] = ()
+    indexes: tuple[Index, ...] = ()
+    checks: tuple[CheckConstraint, ...] = ()
+    comment: str | None = None
+    metadata: tuple[MetadataEntry, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.columns:
+            message = "table must contain at least one column"
+            raise SchemaValidationError(message)
+        column_names = tuple(column.name for column in self.columns)
+        _require_unique(column_names, "table column names")
+        _validate_table_keys(self.keys, column_names)
+        _validate_table_relations(self.relations, column_names)
+        _validate_table_indexes(self.indexes, column_names)
+        _validate_primary_key_count(self.keys)
+        _validate_named_items(self.keys, "key names")
+        _validate_named_items(self.relations, "relation names")
+        _validate_named_items(self.indexes, "index names")
+        _validate_named_items(self.checks, "check names")
+        _validate_optional_text(self.comment, "table comment")
+        object.__setattr__(self, "metadata", _canonical_metadata(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class View:
+    name: Identifier
+    columns: tuple[Column, ...]
+    definition: SqlExpression | None = None
+    materialized: bool = False
+    comment: str | None = None
+    metadata: tuple[MetadataEntry, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.columns:
+            message = "view must contain at least one column"
+            raise SchemaValidationError(message)
+        _require_unique(tuple(column.name for column in self.columns), "view columns")
+        _validate_optional_text(self.comment, "view comment")
+        object.__setattr__(self, "metadata", _canonical_metadata(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class EnumType:
+    name: Identifier
+    values: tuple[str, ...]
+    comment: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.values:
+            message = "enum must contain at least one value"
+            raise SchemaValidationError(message)
+        for value in self.values:
+            _require_text(value, "enum value")
+        _require_unique(self.values, "enum values")
+        _validate_optional_text(self.comment, "enum comment")
+
+
+@dataclass(frozen=True, slots=True)
+class Domain:
+    """A named type written over another, with rules of its own.
+
+    Two domains over the same base are different types, so the name is what
+    identifies one. Its checks and default belong to the domain rather than
+    to any column of it, which is why they are kept here.
+    """
+
+    name: Identifier
+    data_type: SqlType
+    nullable: bool = True
+    default: SqlExpression | None = None
+    checks: tuple[CheckConstraint, ...] = ()
+    comment: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.data_type.kind is TypeKind.DOMAIN:
+            message = "a domain is written over a type, not over another domain"
+            raise SchemaValidationError(message)
+        _require_unique(tuple(check.name for check in self.checks), "domain checks")
+        _validate_optional_text(self.comment, "domain comment")
+
+
+class RoutineKind(StrEnum):
+    """Whether a routine answers with a value or is run for what it does."""
+
+    FUNCTION = "function"
+    PROCEDURE = "procedure"
+
+
+class ParameterMode(StrEnum):
+    """Which way a value travels through a routine parameter."""
+
+    IN = "in"
+    OUT = "out"
+    INOUT = "inout"
+
+
+@dataclass(frozen=True, slots=True)
+class RoutineParameter:
+    """One parameter of a routine, as the catalog declares it.
+
+    No catalog states a parameter's nullability on the parameter. It comes
+    from the parameter's own type, which a domain can declare forbids null,
+    so that is the only way ``nullable`` is ever false.
+    """
+
+    name: Identifier | None
+    data_type: SqlType
+    mode: ParameterMode = ParameterMode.IN
+    has_default: bool = False
+    nullable: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class Routine:
+    """A procedure or function the database keeps.
+
+    ``overload`` separates routines that share a name, which several databases
+    allow. Without it a generated name could stand for more than one routine
+    and a call could reach the wrong one.
+    """
+
+    name: Identifier
+    kind: RoutineKind
+    parameters: tuple[RoutineParameter, ...] = ()
+    returns: SqlType | None = None
+    overload: str | None = None
+    comment: str | None = None
+
+    def __post_init__(self) -> None:
+        if (self.kind is RoutineKind.FUNCTION) != (self.returns is not None):
+            message = "a function answers with a type and a procedure does not"
+            raise SchemaValidationError(message)
+        named = tuple(
+            parameter.name
+            for parameter in self.parameters
+            if parameter.name is not None
+        )
+        _require_unique(named, "routine parameter names")
+        _validate_optional_text(self.comment, "routine comment")
+
+
+@dataclass(frozen=True, slots=True)
+class Schema:
+    name: Identifier | None
+    tables: tuple[Table, ...] = ()
+    views: tuple[View, ...] = ()
+    enums: tuple[EnumType, ...] = ()
+    domains: tuple[Domain, ...] = ()
+    routines: tuple[Routine, ...] = ()
+    comment: str | None = None
+
+    def __post_init__(self) -> None:
+        table_names = tuple(table.name for table in self.tables)
+        view_names = tuple(view.name for view in self.views)
+        _require_unique(table_names + view_names, "schema relation names")
+        _require_unique(tuple(enum.name for enum in self.enums), "schema enum names")
+        _require_unique(
+            tuple(domain.name for domain in self.domains), "schema domain names"
+        )
+        _require_unique(
+            tuple((routine.name.value, routine.overload) for routine in self.routines),
+            "schema routine names",
+        )
+        _validate_optional_text(self.comment, "schema comment")
+
+
+@dataclass(frozen=True, slots=True)
+class Catalog:
+    name: Identifier | None
+    schemas: tuple[Schema, ...]
+    comment: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.schemas:
+            message = "catalog must contain at least one schema"
+            raise SchemaValidationError(message)
+        _require_unique(tuple(schema.name for schema in self.schemas), "schema names")
+        _validate_optional_text(self.comment, "catalog comment")
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilitySet:
+    values: frozenset[Capability] = frozenset()
+
+    def supports(self, capability: Capability) -> bool:
+        return capability in self.values
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaSnapshot:
+    dialect: DatabaseDialect
+    catalogs: tuple[Catalog, ...]
+    capabilities: CapabilitySet = CapabilitySet()
+    format_version: int = SCHEMA_FORMAT_VERSION
+
+    def __post_init__(self) -> None:
+        if self.format_version != SCHEMA_FORMAT_VERSION:
+            message = f"unsupported schema format version: {self.format_version}"
+            raise SchemaValidationError(message)
+        if not self.catalogs:
+            message = "schema snapshot must contain at least one catalog"
+            raise SchemaValidationError(message)
+        _require_unique(
+            tuple(catalog.name for catalog in self.catalogs),
+            "catalog names",
+        )
+
+    def to_json(self) -> str:
+        from pyoq.schema.codec import encode_snapshot
+
+        return encode_snapshot(self)
+
+    @staticmethod
+    def from_json(value: str) -> SchemaSnapshot:
+        from pyoq.schema.codec import decode_snapshot
+
+        return decode_snapshot(value)
+
+
+def _require_text(value: str, label: str) -> None:
+    if not value:
+        message = f"{label} cannot be empty"
+        raise SchemaValidationError(message)
+
+
+def _validate_optional_text(value: str | None, label: str) -> None:
+    if value is not None:
+        _require_text(value, label)
+
+
+def _require_positive(value: int | None, label: str) -> None:
+    if value is not None and value <= 0:
+        message = f"{label} must be positive"
+        raise SchemaValidationError(message)
+
+
+def _validate_scale(precision: int | None, scale: int | None) -> None:
+    if scale is None:
+        return
+    if scale < 0 or precision is None or scale > precision:
+        message = "type scale requires precision and must be within its range"
+        raise SchemaValidationError(message)
+
+
+_NESTING_KINDS = frozenset({TypeKind.ARRAY, TypeKind.DOMAIN})
+"""The kinds that are written around another type."""
+
+_NAMED_KINDS = frozenset({TypeKind.ENUM, TypeKind.DOMAIN})
+"""The kinds a database knows by a name of their own."""
+
+
+def _validate_nested_type(
+    kind: TypeKind,
+    element_type: SqlType | None,
+    named_type: ObjectReference | None,
+) -> None:
+    if (kind in _NESTING_KINDS) != (element_type is not None):
+        message = (
+            "array and domain types require the type inside them, and other "
+            "types forbid one"
+        )
+        raise SchemaValidationError(message)
+    if (kind in _NAMED_KINDS) != (named_type is not None):
+        message = (
+            "enum and domain types require a named type and other types forbid one"
+        )
+        raise SchemaValidationError(message)
+
+
+def _canonical_metadata(
+    metadata: tuple[MetadataEntry, ...],
+) -> tuple[MetadataEntry, ...]:
+    ordered = tuple(sorted(metadata))
+    _require_unique(tuple(entry.key for entry in ordered), "metadata keys")
+    return ordered
+
+
+def _require_identifiers(values: tuple[Identifier, ...], label: str) -> None:
+    if not values:
+        message = f"{label} cannot be empty"
+        raise SchemaValidationError(message)
+    _require_unique(values, label)
+
+
+def _require_unique(values: tuple[UniqueValue, ...], label: str) -> None:
+    if len(set(values)) != len(values):
+        message = f"{label} must be unique"
+        raise SchemaValidationError(message)
+
+
+def _validate_primary_key_count(keys: tuple[Key, ...]) -> None:
+    count = sum(key.kind is KeyKind.PRIMARY for key in keys)
+    if count > 1:
+        message = "table cannot contain more than one primary key"
+        raise SchemaValidationError(message)
+
+
+def _validate_table_keys(
+    keys: tuple[Key, ...],
+    columns: tuple[Identifier, ...],
+) -> None:
+    for key in keys:
+        _require_local_columns(key.columns, columns, "key")
+
+
+def _validate_table_relations(
+    relations: tuple[Relation, ...],
+    columns: tuple[Identifier, ...],
+) -> None:
+    for relation in relations:
+        _require_local_columns(relation.columns, columns, "relation")
+
+
+def _validate_table_indexes(
+    indexes: tuple[Index, ...],
+    columns: tuple[Identifier, ...],
+) -> None:
+    for index in indexes:
+        for term in index.terms:
+            if term.column is not None:
+                _require_local_columns((term.column,), columns, "index")
+
+
+def _require_local_columns(
+    selected: tuple[Identifier, ...],
+    available: tuple[Identifier, ...],
+    label: str,
+) -> None:
+    missing = tuple(column for column in selected if column not in available)
+    if missing:
+        names = ", ".join(column.value for column in missing)
+        message = f"{label} references unknown local columns: {names}"
+        raise SchemaValidationError(message)
+
+
+def _validate_named_items(items: tuple[NamedSchemaItem, ...], label: str) -> None:
+    names = tuple(item.name for item in items if item.name is not None)
+    _require_unique(names, label)
+
+
+__all__ = (
+    "SCHEMA_FORMAT_VERSION",
+    "Capability",
+    "CapabilitySet",
+    "Catalog",
+    "CheckConstraint",
+    "Column",
+    "EnumType",
+    "GeneratedKind",
+    "GeneratedValue",
+    "Identifier",
+    "Index",
+    "IndexTerm",
+    "Key",
+    "KeyKind",
+    "MetadataEntry",
+    "ObjectReference",
+    "ReferentialAction",
+    "Relation",
+    "Schema",
+    "SchemaSnapshot",
+    "SqlExpression",
+    "SqlType",
+    "Table",
+    "TypeKind",
+    "View",
+)

pyoq/schema/mysql/__init__.py

@@ -0,0 +1,16 @@
+"""MySQL schema support."""
+
+from pyoq.schema.mysql.connection import MySQLConnectionProvider
+from pyoq.schema.mysql.dsn import MySQLConnectionSettings, parse_data_source_name
+from pyoq.schema.mysql.reflection import MySQLSchemaInspector
+from pyoq.schema.mysql.source import MySQLSchemaSource
+from pyoq.schema.mysql.types import mysql_type
+
+__all__ = (
+    "MySQLConnectionProvider",
+    "MySQLConnectionSettings",
+    "MySQLSchemaInspector",
+    "MySQLSchemaSource",
+    "mysql_type",
+    "parse_data_source_name",
+)

pyoq/schema/mysql/connection.py

@@ -0,0 +1,73 @@
+"""Read-only MySQL connection ownership."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import AbstractContextManager, contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from pyoq.config import Configuration
+from pyoq.errors import (
+    ConfigurationValidationError,
+    OperationUnavailableError,
+    SchemaInspectionError,
+)
+from pyoq.schema.mysql.dsn import MySQLConnectionSettings, parse_data_source_name
+
+if TYPE_CHECKING:
+    from pymysql.connections import Connection
+    from pymysql.cursors import Cursor
+
+_MISSING_DRIVER = "MySQL support requires the PyMySQL driver; install pyoq-sql[mysql]"
+_READ_ONLY_SESSION = "SET SESSION TRANSACTION READ ONLY"
+_CHARSET = "utf8mb4"
+
+
+@dataclass(frozen=True, slots=True)
+class MySQLConnectionProvider:
+    def open(
+        self,
+        configuration: Configuration,
+    ) -> AbstractContextManager[Connection[Cursor]]:
+        return self._connect(parse_data_source_name(_data_source_name(configuration)))
+
+    @contextmanager
+    def _connect(
+        self,
+        settings: MySQLConnectionSettings,
+    ) -> Generator[Connection[Cursor]]:
+        try:
+            import pymysql
+        except ImportError as error:
+            raise OperationUnavailableError(_MISSING_DRIVER) from error
+        try:
+            connection = pymysql.connect(
+                host=settings.host,
+                port=settings.port,
+                user=settings.user,
+                password=settings.password,
+                database=settings.database,
+                charset=_CHARSET,
+                autocommit=True,
+                init_command=_READ_ONLY_SESSION,
+            )
+        except pymysql.Error as error:
+            message = f"unable to open MySQL connection: {error}"
+            raise SchemaInspectionError(message) from error
+        try:
+            yield connection
+        finally:
+            connection.close()
+
+
+def _data_source_name(configuration: Configuration) -> str:
+    profile = configuration.active_profile
+    resolved = profile.resolve_dsn()
+    if resolved is None:
+        message = "MySQL profiles require a dsn setting"
+        raise ConfigurationValidationError(message)
+    return resolved.reveal()
+
+
+__all__ = ("MySQLConnectionProvider",)