pyoq-sql 1.0.2__py3-none-any.whl

pyoq/schema/postgres/sql.py

@@ -0,0 +1,246 @@
+"""PostgreSQL system catalog queries."""
+
+from __future__ import annotations
+
+SCHEMA_OBJECTS = """
+SELECT
+    n.nspname,
+    c.relname,
+    c.relkind,
+    obj_description(c.oid, 'pg_class'),
+    CASE
+        WHEN c.relkind IN ('v', 'm') THEN pg_get_viewdef(c.oid, true)
+    END
+FROM pg_class AS c
+JOIN pg_namespace AS n ON n.oid = c.relnamespace
+WHERE c.relkind IN ('r', 'p', 'v', 'm')
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+    AND n.nspname NOT LIKE 'pg\\_toast%'
+    AND n.nspname NOT LIKE 'pg\\_temp%'
+ORDER BY n.nspname, c.relname
+"""
+
+COLUMNS = """
+SELECT
+    n.nspname,
+    c.relname,
+    a.attname,
+    format_type(a.atttypid, a.atttypmod),
+    NOT a.attnotnull AND NOT t.typnotnull,
+    t.typtype,
+    tn.nspname,
+    t.typname,
+    CASE
+        WHEN t.typtype = 'd'
+        THEN format_type(t.typbasetype, t.typtypmod)
+    END,
+    pg_get_expr(d.adbin, d.adrelid),
+    a.attidentity,
+    a.attgenerated,
+    col_description(c.oid, a.attnum)
+FROM pg_attribute AS a
+JOIN pg_class AS c ON c.oid = a.attrelid
+JOIN pg_namespace AS n ON n.oid = c.relnamespace
+JOIN pg_type AS t ON t.oid = a.atttypid
+JOIN pg_namespace AS tn ON tn.oid = t.typnamespace
+LEFT JOIN pg_attrdef AS d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+WHERE a.attnum > 0
+    AND NOT a.attisdropped
+    AND c.relkind IN ('r', 'p', 'v', 'm')
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+    AND n.nspname NOT LIKE 'pg\\_toast%'
+    AND n.nspname NOT LIKE 'pg\\_temp%'
+ORDER BY n.nspname, c.relname, a.attnum
+"""
+
+CONSTRAINTS = """
+SELECT
+    n.nspname,
+    c.relname,
+    con.conname,
+    con.contype,
+    pg_get_constraintdef(con.oid, true),
+    ARRAY(
+        SELECT a.attname
+        FROM unnest(con.conkey) WITH ORDINALITY AS k(attnum, position)
+        JOIN pg_attribute AS a
+            ON a.attrelid = con.conrelid AND a.attnum = k.attnum
+        ORDER BY k.position
+    ),
+    tn.nspname,
+    tc.relname,
+    ARRAY(
+        SELECT a.attname
+        FROM unnest(con.confkey) WITH ORDINALITY AS k(attnum, position)
+        JOIN pg_attribute AS a
+            ON a.attrelid = con.confrelid AND a.attnum = k.attnum
+        ORDER BY k.position
+    ),
+    con.confupdtype,
+    con.confdeltype
+FROM pg_constraint AS con
+JOIN pg_class AS c ON c.oid = con.conrelid
+JOIN pg_namespace AS n ON n.oid = c.relnamespace
+LEFT JOIN pg_class AS tc ON tc.oid = con.confrelid
+LEFT JOIN pg_namespace AS tn ON tn.oid = tc.relnamespace
+WHERE con.contype IN ('p', 'u', 'f', 'c')
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+    AND n.nspname NOT LIKE 'pg\\_toast%'
+    AND n.nspname NOT LIKE 'pg\\_temp%'
+ORDER BY n.nspname, c.relname, con.contype, con.conname
+"""
+
+INDEXES = """
+SELECT
+    n.nspname,
+    c.relname,
+    ic.relname,
+    i.indisunique,
+    am.amname,
+    pg_get_expr(i.indpred, i.indrelid, true),
+    ARRAY(
+        SELECT k.attnum
+        FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, position)
+        ORDER BY k.position
+    ),
+    ARRAY(
+        SELECT a.attname
+        FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, position)
+        LEFT JOIN pg_attribute AS a
+            ON a.attrelid = i.indrelid AND a.attnum = k.attnum
+        ORDER BY k.position
+    ),
+    ARRAY(
+        SELECT pg_get_indexdef(i.indexrelid, k.position::int, true)
+        FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, position)
+        ORDER BY k.position
+    ),
+    ARRAY(
+        SELECT o.option
+        FROM unnest(i.indoption) WITH ORDINALITY AS o(option, position)
+        ORDER BY o.position
+    )
+FROM pg_index AS i
+JOIN pg_class AS c ON c.oid = i.indrelid
+JOIN pg_class AS ic ON ic.oid = i.indexrelid
+JOIN pg_namespace AS n ON n.oid = c.relnamespace
+JOIN pg_am AS am ON am.oid = ic.relam
+WHERE NOT i.indisprimary
+    AND c.relkind IN ('r', 'p')
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+    AND n.nspname NOT LIKE 'pg\\_toast%'
+    AND n.nspname NOT LIKE 'pg\\_temp%'
+ORDER BY n.nspname, c.relname, ic.relname
+"""
+
+ENUMS = """
+SELECT
+    n.nspname,
+    t.typname,
+    e.enumlabel,
+    obj_description(t.oid)
+FROM pg_type AS t
+JOIN pg_namespace AS n ON n.oid = t.typnamespace
+JOIN pg_enum AS e ON e.enumtypid = t.oid
+WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+    AND n.nspname NOT LIKE 'pg\\_toast%'
+    AND n.nspname NOT LIKE 'pg\\_temp%'
+ORDER BY n.nspname, t.typname, e.enumsortorder
+"""
+"""Every enum type and its labels, in the order the database keeps them.
+
+The order is the type's own, not alphabetical, because an enum compares and
+sorts by it and a schema that reordered them would describe a different type.
+"""
+
+
+DOMAINS = """
+SELECT
+    n.nspname,
+    t.typname,
+    format_type(t.typbasetype, t.typtypmod),
+    t.typnotnull,
+    t.typdefault,
+    obj_description(t.oid)
+FROM pg_type AS t
+JOIN pg_namespace AS n ON n.oid = t.typnamespace
+WHERE t.typtype = 'd'
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+    AND n.nspname NOT LIKE 'pg\\_toast%'
+    AND n.nspname NOT LIKE 'pg\\_temp%'
+ORDER BY n.nspname, t.typname
+"""
+
+DOMAIN_CHECKS = """
+SELECT
+    n.nspname,
+    t.typname,
+    c.conname,
+    pg_get_constraintdef(c.oid)
+FROM pg_constraint AS c
+JOIN pg_type AS t ON t.oid = c.contypid
+JOIN pg_namespace AS n ON n.oid = t.typnamespace
+WHERE c.contype = 'c'
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+ORDER BY n.nspname, t.typname, c.conname
+"""
+
+ROUTINES = """
+SELECT
+    n.nspname,
+    p.proname,
+    p.prokind,
+    p.oid,
+    CASE WHEN p.prokind = 'f' THEN format_type(p.prorettype, NULL) END,
+    a.ordinality,
+    p.proargnames[a.ordinality],
+    COALESCE(p.proargmodes[a.ordinality], 'i'),
+    format_type(a.argument_type, NULL),
+    rn.nspname,
+    rt.typname,
+    rt.typtype,
+    format_type(rt.typbasetype, NULL),
+    COALESCE(rd.typelem <> 0, FALSE),
+    an.nspname,
+    at.typname,
+    at.typtype,
+    format_type(at.typbasetype, NULL),
+    COALESCE(ad.typelem <> 0, FALSE),
+    COALESCE(at.typnotnull, FALSE),
+    p.pronargdefaults
+FROM pg_proc AS p
+JOIN pg_namespace AS n ON n.oid = p.pronamespace
+LEFT JOIN pg_type AS rd ON rd.oid = p.prorettype
+LEFT JOIN pg_type AS rt ON rt.oid = COALESCE(NULLIF(rd.typelem, 0), rd.oid)
+LEFT JOIN pg_namespace AS rn ON rn.oid = rt.typnamespace
+LEFT JOIN LATERAL unnest(
+    COALESCE(p.proallargtypes, p.proargtypes::oid[])
+) WITH ORDINALITY AS a(argument_type, ordinality) ON TRUE
+LEFT JOIN pg_type AS ad ON ad.oid = a.argument_type
+LEFT JOIN pg_type AS at ON at.oid = COALESCE(NULLIF(ad.typelem, 0), ad.oid)
+LEFT JOIN pg_namespace AS an ON an.oid = at.typnamespace
+WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+    AND p.prokind IN ('f', 'p')
+ORDER BY n.nspname, p.proname, p.oid, a.ordinality
+"""
+"""One row per parameter, so a routine of no parameters is still one row.
+
+The routine's own identifier separates two that share a name, which is what
+keeps an overload from being mistaken for the other.
+
+PostgreSQL states no nullability for a parameter itself. A parameter typed as
+a domain that forbids null cannot be given one, and ``typnotnull`` is where
+the catalog says so, so that is what is read here.
+"""
+
+
+__all__ = (
+    "COLUMNS",
+    "CONSTRAINTS",
+    "DOMAINS",
+    "DOMAIN_CHECKS",
+    "ENUMS",
+    "INDEXES",
+    "ROUTINES",
+    "SCHEMA_OBJECTS",
+)

pyoq/schema/postgres/types.py

@@ -0,0 +1,98 @@
+"""PostgreSQL declared-type normalization."""
+
+from __future__ import annotations
+
+import re
+
+from pyoq.schema.models import SqlType, TypeKind
+
+_TYPE_ARGUMENTS = re.compile(r"^\s*([^()\[\]]*?)\s*(?:\(([^()]*)\))?\s*((?:\[\])*)\s*$")
+
+_EXACT_KINDS = {
+    "BOOL": TypeKind.BOOLEAN,
+    "BOOLEAN": TypeKind.BOOLEAN,
+    "SMALLINT": TypeKind.SMALL_INTEGER,
+    "INT2": TypeKind.SMALL_INTEGER,
+    "SMALLSERIAL": TypeKind.SMALL_INTEGER,
+    "SERIAL2": TypeKind.SMALL_INTEGER,
+    "INTEGER": TypeKind.INTEGER,
+    "INT": TypeKind.INTEGER,
+    "INT4": TypeKind.INTEGER,
+    "SERIAL": TypeKind.INTEGER,
+    "SERIAL4": TypeKind.INTEGER,
+    "BIGINT": TypeKind.BIG_INTEGER,
+    "INT8": TypeKind.BIG_INTEGER,
+    "BIGSERIAL": TypeKind.BIG_INTEGER,
+    "SERIAL8": TypeKind.BIG_INTEGER,
+    "NUMERIC": TypeKind.DECIMAL,
+    "DECIMAL": TypeKind.DECIMAL,
+    "MONEY": TypeKind.DECIMAL,
+    "REAL": TypeKind.REAL,
+    "FLOAT4": TypeKind.REAL,
+    "DOUBLE PRECISION": TypeKind.DOUBLE,
+    "FLOAT8": TypeKind.DOUBLE,
+    "TEXT": TypeKind.STRING,
+    "VARCHAR": TypeKind.STRING,
+    "CHARACTER VARYING": TypeKind.STRING,
+    "CHAR": TypeKind.STRING,
+    "CHARACTER": TypeKind.STRING,
+    "BPCHAR": TypeKind.STRING,
+    "NAME": TypeKind.STRING,
+    "CITEXT": TypeKind.STRING,
+    "BYTEA": TypeKind.BINARY,
+    "DATE": TypeKind.DATE,
+    "TIME": TypeKind.TIME,
+    "TIME WITHOUT TIME ZONE": TypeKind.TIME,
+    "TIME WITH TIME ZONE": TypeKind.TIME,
+    "TIMETZ": TypeKind.TIME,
+    "TIMESTAMP": TypeKind.DATETIME,
+    "TIMESTAMP WITHOUT TIME ZONE": TypeKind.DATETIME,
+    "TIMESTAMP WITH TIME ZONE": TypeKind.DATETIME,
+    "TIMESTAMPTZ": TypeKind.DATETIME,
+    "INTERVAL": TypeKind.INTERVAL,
+    "UUID": TypeKind.UUID,
+    "JSON": TypeKind.JSON,
+    "JSONB": TypeKind.JSON,
+}
+
+_SIZED_KINDS = frozenset({TypeKind.STRING})
+_PRECISION_KINDS = frozenset({TypeKind.DECIMAL})
+
+
+def postgres_type(declared_type: str) -> SqlType:
+    source_name = declared_type.strip() or "text"
+    match = _TYPE_ARGUMENTS.fullmatch(source_name)
+    if match is None:
+        return SqlType(TypeKind.OTHER, source_name)
+    base_name, argument_text, array_suffix = match.groups()
+    if array_suffix:
+        element_source = source_name[: source_name.rindex("[]")].rstrip()
+        return SqlType(
+            TypeKind.ARRAY,
+            source_name,
+            element_type=postgres_type(element_source),
+        )
+    kind = _EXACT_KINDS.get(_normalized(base_name), TypeKind.OTHER)
+    arguments = _numeric_arguments(argument_text)
+    if kind in _SIZED_KINDS and len(arguments) == 1:
+        return SqlType(kind, source_name, length=arguments[0])
+    if kind in _PRECISION_KINDS and arguments:
+        scale = arguments[1] if len(arguments) == 2 else None
+        return SqlType(kind, source_name, precision=arguments[0], scale=scale)
+    return SqlType(kind, source_name)
+
+
+def _normalized(value: str) -> str:
+    return " ".join(value.upper().split())
+
+
+def _numeric_arguments(value: str | None) -> tuple[int, ...]:
+    if value is None:
+        return ()
+    parts = tuple(part.strip() for part in value.split(","))
+    if not 1 <= len(parts) <= 2 or any(not part.isdecimal() for part in parts):
+        return ()
+    return tuple(int(part) for part in parts)
+
+
+__all__ = ("postgres_type",)

pyoq/schema/registry.py

@@ -0,0 +1,45 @@
+"""Dialect to schema source resolution."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from pyoq.config import Configuration, DatabaseDialect
+from pyoq.schema.models import SchemaSnapshot
+from pyoq.schema.mysql.source import MySQLSchemaSource
+from pyoq.schema.postgres.source import PostgresSchemaSource
+from pyoq.schema.source import SchemaSource
+from pyoq.schema.sqlite.source import SQLiteSchemaSource
+
+SchemaSourceFactory: TypeAlias = Callable[[], SchemaSource]
+
+_SCHEMA_SOURCES: Mapping[DatabaseDialect, SchemaSourceFactory] = {
+    DatabaseDialect.MYSQL: MySQLSchemaSource,
+    DatabaseDialect.POSTGRES: PostgresSchemaSource,
+    DatabaseDialect.SQLITE: SQLiteSchemaSource,
+}
+
+
+def supported_dialects() -> tuple[DatabaseDialect, ...]:
+    return tuple(_SCHEMA_SOURCES)
+
+
+def schema_source_for(dialect: DatabaseDialect, /) -> SchemaSource:
+    return _SCHEMA_SOURCES[dialect]()
+
+
+@dataclass(frozen=True, slots=True)
+class DialectRoutingSchemaSource:
+    def load(self, configuration: Configuration) -> SchemaSnapshot:
+        dialect = configuration.active_profile.dialect
+        return schema_source_for(dialect).load(configuration)
+
+
+__all__ = (
+    "DialectRoutingSchemaSource",
+    "SchemaSourceFactory",
+    "schema_source_for",
+    "supported_dialects",
+)

pyoq/schema/source.py

@@ -0,0 +1,15 @@
+"""Dialect-neutral schema source contract."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from pyoq.config import Configuration
+from pyoq.schema.models import SchemaSnapshot
+
+
+class SchemaSource(Protocol):
+    def load(self, configuration: Configuration) -> SchemaSnapshot: ...
+
+
+__all__ = ("SchemaSource",)

pyoq/schema/sqlite/__init__.py

@@ -0,0 +1,6 @@
+"""SQLite schema inspection."""
+
+from pyoq.schema.sqlite.reflection import SQLiteSchemaInspector
+from pyoq.schema.sqlite.source import SQLiteSchemaSource
+
+__all__ = ("SQLiteSchemaInspector", "SQLiteSchemaSource")

pyoq/schema/sqlite/connection.py

@@ -0,0 +1,54 @@
+"""Read-only SQLite connection ownership."""
+
+from __future__ import annotations
+
+import sqlite3
+from contextlib import AbstractContextManager, closing
+from dataclasses import dataclass
+from pathlib import Path
+
+from pyoq.config import Configuration
+from pyoq.errors import ConfigurationValidationError, SchemaInspectionError
+
+
+@dataclass(frozen=True, slots=True)
+class SQLiteConnectionProvider:
+    def open(
+        self,
+        configuration: Configuration,
+    ) -> AbstractContextManager[sqlite3.Connection]:
+        path = _database_path(configuration)
+        _require_regular_database(path)
+        try:
+            connection = sqlite3.connect(
+                f"{path.as_uri()}?mode=ro",
+                uri=True,
+                check_same_thread=True,
+            )
+        except sqlite3.Error as error:
+            message = f"unable to open SQLite database: {error}"
+            raise SchemaInspectionError(message) from error
+        return closing(connection)
+
+
+def _database_path(configuration: Configuration) -> Path:
+    configured = configuration.active_database_path
+    if configured is not None:
+        return configured
+    resolved = configuration.active_profile.resolve_dsn()
+    if resolved is None:
+        message = "SQLite profile requires database-path or a dsn setting"
+        raise ConfigurationValidationError(message)
+    return Path(resolved.reveal()).expanduser().resolve()
+
+
+def _require_regular_database(path: Path) -> None:
+    if not path.exists():
+        message = f"SQLite database does not exist: {path}"
+        raise SchemaInspectionError(message)
+    if not path.is_file():
+        message = f"SQLite database is not a regular file: {path}"
+        raise SchemaInspectionError(message)
+
+
+__all__ = ("SQLiteConnectionProvider",)

pyoq/schema/sqlite/records.py

@@ -0,0 +1,167 @@
+"""Typed SQLite metadata records."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypeAlias, cast
+
+from pyoq.errors import SchemaInspectionError
+
+DatabaseRow: TypeAlias = tuple[object, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaObjectRecord:
+    kind: str
+    name: str
+    sql: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ColumnRecord:
+    position: int
+    name: str
+    declared_type: str
+    not_null: bool
+    default: str | None
+    primary_ordinal: int
+    hidden: int
+
+
+@dataclass(frozen=True, slots=True)
+class IndexRecord:
+    position: int
+    name: str
+    unique: bool
+    origin: str
+    partial: bool
+
+
+@dataclass(frozen=True, slots=True)
+class IndexTermRecord:
+    position: int
+    column_position: int
+    column_name: str | None
+    descending: bool
+    key_term: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ForeignKeyRecord:
+    relation_id: int
+    position: int
+    target_table: str
+    source_column: str
+    target_column: str | None
+    on_update: str
+    on_delete: str
+
+
+def schema_object(row: object) -> SchemaObjectRecord:
+    values = _row(row, 3, "schema object")
+    return SchemaObjectRecord(
+        _text(values[0], "schema object kind"),
+        _text(values[1], "schema object name"),
+        _optional_text(values[2], "schema object SQL"),
+    )
+
+
+def column(row: object) -> ColumnRecord:
+    values = _row(row, 7, "column")
+    return ColumnRecord(
+        _integer(values[0], "column position"),
+        _text(values[1], "column name"),
+        _optional_text(values[2], "column type") or "ANY",
+        _flag(values[3], "column not-null flag"),
+        _optional_text(values[4], "column default"),
+        _integer(values[5], "column primary-key position"),
+        _integer(values[6], "column hidden flag"),
+    )
+
+
+def index(row: object) -> IndexRecord:
+    values = _row(row, 5, "index")
+    return IndexRecord(
+        _integer(values[0], "index position"),
+        _text(values[1], "index name"),
+        _flag(values[2], "index unique flag"),
+        _text(values[3], "index origin"),
+        _flag(values[4], "index partial flag"),
+    )
+
+
+def index_term(row: object) -> IndexTermRecord:
+    values = _row(row, 6, "index term")
+    return IndexTermRecord(
+        _integer(values[0], "index term position"),
+        _integer(values[1], "index term column position"),
+        _optional_text(values[2], "index term column name"),
+        _flag(values[3], "index descending flag"),
+        _flag(values[5], "index key-term flag"),
+    )
+
+
+def foreign_key(row: object) -> ForeignKeyRecord:
+    values = _row(row, 8, "foreign key")
+    return ForeignKeyRecord(
+        _integer(values[0], "foreign-key id"),
+        _integer(values[1], "foreign-key position"),
+        _text(values[2], "foreign-key target table"),
+        _text(values[3], "foreign-key source column"),
+        _optional_text(values[4], "foreign-key target column"),
+        _text(values[5], "foreign-key update action"),
+        _text(values[6], "foreign-key delete action"),
+    )
+
+
+def _row(value: object, size: int, label: str) -> DatabaseRow:
+    if not isinstance(value, tuple):
+        message = f"invalid SQLite {label} metadata"
+        raise SchemaInspectionError(message)
+    values = cast(DatabaseRow, value)
+    if len(values) != size:
+        message = f"invalid SQLite {label} metadata"
+        raise SchemaInspectionError(message)
+    return values
+
+
+def _text(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value:
+        message = f"invalid SQLite {label}"
+        raise SchemaInspectionError(message)
+    return value
+
+
+def _optional_text(value: object, label: str) -> str | None:
+    if value is None:
+        return None
+    return _text(value, label)
+
+
+def _integer(value: object, label: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        message = f"invalid SQLite {label}"
+        raise SchemaInspectionError(message)
+    return value
+
+
+def _flag(value: object, label: str) -> bool:
+    flag = _integer(value, label)
+    if flag not in {0, 1}:
+        message = f"invalid SQLite {label}"
+        raise SchemaInspectionError(message)
+    return bool(flag)
+
+
+__all__ = (
+    "ColumnRecord",
+    "ForeignKeyRecord",
+    "IndexRecord",
+    "IndexTermRecord",
+    "SchemaObjectRecord",
+    "column",
+    "foreign_key",
+    "index",
+    "index_term",
+    "schema_object",
+)