muscles-data-sql 2.0.0__py3-none-any.whl

muscles/data/sql/native.py

@@ -0,0 +1,131 @@
+"""Small DB-API based SQL access without an ORM or query builder."""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+from threading import Lock, get_ident
+from typing import Any, ContextManager, Iterator
+
+
+class SqlTransaction:
+    def __init__(self, connection: Any):
+        self._connection = connection
+        self._active = True
+        self._owner = get_ident()
+
+    def execute(self, sql: str, parameters: Any = None) -> int:
+        with self._cursor() as cursor:
+            self._execute(cursor, sql, parameters)
+            return cursor.rowcount
+
+    def fetch_all(self, sql: str, parameters: Any = None) -> list[dict[str, Any]]:
+        with self._cursor() as cursor:
+            self._execute(cursor, sql, parameters)
+            names = self._column_names(cursor)
+            return [dict(zip(names, row)) for row in cursor.fetchall()]
+
+    def fetch_one(self, sql: str, parameters: Any = None) -> dict[str, Any] | None:
+        with self._cursor() as cursor:
+            self._execute(cursor, sql, parameters)
+            row = cursor.fetchone()
+            names = self._column_names(cursor)
+            return None if row is None else dict(zip(names, row))
+
+    @staticmethod
+    def _execute(cursor, sql, parameters):
+        if parameters is None:
+            cursor.execute(sql)
+        else:
+            cursor.execute(sql, parameters)
+
+    @staticmethod
+    def _column_names(cursor):
+        names = [column[0] for column in cursor.description]
+        if len(names) != len(set(names)):
+            raise ValueError("SQL result contains duplicate column names; use aliases")
+        return names
+
+    @contextmanager
+    def _cursor(self):
+        if not self._active:
+            raise RuntimeError("SQL transaction is no longer active")
+        if self._owner != get_ident():
+            raise RuntimeError("SQL transaction belongs to a different thread")
+        cursor = self._connection.cursor()
+        try:
+            yield cursor
+        finally:
+            cursor.close()
+
+
+class SqlDatabase:
+    """Own one connection; transactions commit on success and roll back on error."""
+
+    def __init__(self, connection: Any, *, begin_sql: str | None = None, health_query: str = "SELECT 1 AS value"):
+        self._connection = connection
+        self._begin_sql = begin_sql
+        self._health_query = health_query
+        self._lock = Lock()
+        self._transaction_owner: int | None = None
+        self._closed = False
+
+    @classmethod
+    def sqlite(cls, path: str | Path) -> SqlDatabase:
+        import sqlite3
+
+        return cls(sqlite3.connect(str(path), check_same_thread=False), begin_sql="BEGIN")
+
+    @classmethod
+    def postgres(cls, dsn: str) -> SqlDatabase:
+        try:
+            import psycopg
+        except ImportError as exc:
+            raise ImportError("PostgreSQL requires muscles-data-sql[postgres]") from exc
+        normalized_dsn = dsn.replace("postgresql+psycopg2://", "postgresql://", 1).replace(
+            "postgresql+psycopg://", "postgresql://", 1
+        )
+        return cls(psycopg.connect(normalized_dsn))
+
+    def transaction(self) -> ContextManager[SqlTransaction]:
+        return self._transaction(self._begin_sql)
+
+    @contextmanager
+    def _transaction(self, begin_sql: str | None) -> Iterator[SqlTransaction]:
+        owner = get_ident()
+        if self._transaction_owner == owner:
+            raise RuntimeError("Nested SQL transactions are not supported")
+        self._lock.acquire()
+        self._transaction_owner = owner
+        try:
+            if self._closed:
+                raise RuntimeError("SQL database is closed")
+            transaction = SqlTransaction(self._connection)
+            try:
+                if begin_sql is not None:
+                    with transaction._cursor() as cursor:
+                        cursor.execute(begin_sql)
+                yield transaction
+                self._connection.commit()
+            except BaseException:
+                self._connection.rollback()
+                raise
+            finally:
+                transaction._active = False
+        finally:
+            self._transaction_owner = None
+            self._lock.release()
+
+    def close(self) -> None:
+        if self._transaction_owner == get_ident():
+            raise RuntimeError("Cannot close a database during a transaction")
+        self._lock.acquire()
+        try:
+            if not self._closed:
+                self._connection.close()
+                self._closed = True
+        finally:
+            self._lock.release()
+
+    def check_health(self) -> None:
+        with self.transaction() as transaction:
+            transaction.fetch_one(self._health_query)

muscles/data/sql/native_migrations.py

@@ -0,0 +1,200 @@
+"""Transactional, explicitly registered SQLite and PostgreSQL migrations."""
+from __future__ import annotations
+
+import hashlib
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Callable
+from urllib.parse import unquote
+
+from .native import SqlDatabase, SqlTransaction
+
+
+@dataclass(frozen=True)
+class NativeSqlMigration:
+    revision: str
+    checksum: str
+    upgrade: Callable[[SqlTransaction], None]
+    downgrade: Callable[[SqlTransaction], None] | None = None
+    dialects: tuple[str, ...] = ()
+    source_path: str | None = None
+
+    @classmethod
+    def from_module(cls, module: ModuleType) -> NativeSqlMigration:
+        path = getattr(module, "__file__", None)
+        if not path or not str(path).endswith(".py"):
+            raise ValueError("Migration must be backed by a Python source file")
+        checksum = hashlib.sha256(Path(path).read_bytes()).hexdigest()
+        loaded_checksum = getattr(module, "__muscles_migration_checksum__", checksum)
+        if loaded_checksum != checksum:
+            raise ValueError("Migration file changed after module discovery")
+        return cls(module.revision, checksum,
+                   module.upgrade, getattr(module, "downgrade", None), getattr(module, "dialects", ()), str(path))
+
+
+class NativeSqlMigrationBackend:
+    """Run a source atomically; only SQLite and PostgreSQL transactional SQL are supported."""
+
+    def __init__(self, db: SqlDatabase, source: str, migrations: list[NativeSqlMigration], *, dialect: str):
+        if dialect not in {"sqlite", "postgres"}:
+            raise ValueError("Native migrations support only sqlite and postgres")
+        if not isinstance(source, str) or not source:
+            raise ValueError("Migration source is required")
+        if any(not isinstance(item, NativeSqlMigration) or not isinstance(item.revision, str)
+                or not item.revision or not isinstance(item.checksum, str) or not item.checksum
+                or not callable(item.upgrade) or (item.downgrade is not None and not callable(item.downgrade))
+                for item in migrations):
+            raise ValueError("Migrations must have unique ordered revisions, checksums and callable operations")
+        revisions = [item.revision for item in migrations]
+        if revisions != sorted(set(revisions)):
+            raise ValueError("Migrations must have unique ordered revisions, checksums and callable operations")
+        if any(not isinstance(item.dialects, tuple) or dialect not in item.dialects for item in migrations):
+            raise ValueError("Every migration must explicitly support the selected SQL dialect")
+        self.db, self.source, self.migrations, self.dialect = db, source, tuple(migrations), dialect
+        self._param = "?" if dialect == "sqlite" else "%s"
+
+    @contextmanager
+    def _write_transaction(self):
+        begin = "BEGIN IMMEDIATE" if self.dialect == "sqlite" else self.db._begin_sql
+        with self.db._transaction(begin) as tx:
+            if self.dialect == "postgres":
+                row = tx.fetch_one("SELECT pg_try_advisory_xact_lock(%s) AS locked", (778212473,))
+                if not row or not row["locked"]:
+                    raise RuntimeError("SQL migrations are locked by another process")
+            yield tx
+
+    def _state(self, tx: SqlTransaction) -> list[str]:
+        for migration in self.migrations:
+            if migration.source_path is not None:
+                try:
+                    checksum = hashlib.sha256(Path(migration.source_path).read_bytes()).hexdigest()
+                except OSError as exc:
+                    raise ValueError("A migration file is missing or unreadable") from exc
+                if checksum != migration.checksum:
+                    raise ValueError("A migration file changed after discovery")
+        if self.dialect == "sqlite":
+            found = tx.fetch_one("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?",
+                                 ("muscles_data_migrations",))
+        else:
+            found = tx.fetch_one("SELECT to_regclass(%s) AS name", ("muscles_data_migrations",))
+        if not found or not found["name"]:
+            return []
+        rows = tx.fetch_all(f"SELECT revision, checksum FROM muscles_data_migrations WHERE source = {self._param} ORDER BY revision",
+                            (self.source,))
+        expected = self.migrations[:len(rows)]
+        if len(rows) > len(self.migrations) or [row["revision"] for row in rows] != [item.revision for item in expected]:
+            raise ValueError("Migration history is missing, unknown or out of order")
+        if any(row["checksum"] != item.checksum for row, item in zip(rows, expected)):
+            raise ValueError("An applied migration has changed")
+        return [row["revision"] for row in rows]
+
+    def status(self) -> dict:
+        with self.db.transaction() as tx:
+            current = self._state(tx)
+        return {"current": current[-1:] if current else [], "applied": current,
+                "pending": [item.revision for item in self.migrations[len(current):]],
+                "verification": "checksums"}
+
+    def plan(self) -> list[str]:
+        return self.status()["pending"]
+
+    def upgrade(self, target: str = "head") -> None:
+        revisions = [item.revision for item in self.migrations]
+        if target != "head" and target not in revisions:
+            raise ValueError("Unknown migration target")
+        end = len(revisions) if target == "head" else revisions.index(target) + 1
+        with self._write_transaction() as tx:
+            current = self._state(tx)
+            if end < len(current):
+                raise ValueError("Upgrade target is older than current revision")
+            if end == len(current):
+                return
+            tx.execute("CREATE TABLE IF NOT EXISTS muscles_data_migrations ("
+                       "source TEXT NOT NULL, revision TEXT NOT NULL, checksum TEXT NOT NULL, "
+                       "applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (source, revision))")
+            for item in self.migrations[len(current):end]:
+                item.upgrade(tx)
+                tx.execute(f"INSERT INTO muscles_data_migrations (source, revision, checksum) VALUES ({self._param}, {self._param}, {self._param})",
+                           (self.source, item.revision, item.checksum))
+
+    def downgrade(self, target: str) -> None:
+        revisions = [item.revision for item in self.migrations]
+        if target != "base" and target not in revisions:
+            raise ValueError("Unknown migration target")
+        end = 0 if target == "base" else revisions.index(target) + 1
+        with self._write_transaction() as tx:
+            current = self._state(tx)
+            if end > len(current):
+                raise ValueError("Downgrade target is not applied")
+            to_revert = tuple(reversed(self.migrations[end:len(current)]))
+            if any(item.downgrade is None for item in to_revert):
+                raise ValueError("A migration has no downgrade")
+            for item in to_revert:
+                item.downgrade(tx)
+                tx.execute(f"DELETE FROM muscles_data_migrations WHERE source = {self._param} AND revision = {self._param}",
+                           (self.source, item.revision))
+
+
+class NativeSqlMigrationSourceBackend:
+    """MigrationRegistry backend that owns a short-lived native SQL connection per command."""
+
+    def __init__(
+        self,
+        url: str,
+        source: str,
+        migrations: list[NativeSqlMigration],
+    ) -> None:
+        if not isinstance(url, str) or not url.strip():
+            raise ValueError("A database URL is required for native SQL migrations")
+        self.url = url
+        self.source = source
+        self.migrations = list(migrations)
+
+    def _open_database(self) -> tuple[SqlDatabase, str]:
+        if self.url.startswith("sqlite:///"):
+            path = unquote(self.url[len("sqlite:///"):])
+            if not path:
+                raise ValueError("SQLite migration URL must include a database path")
+            return SqlDatabase.sqlite(path), "sqlite"
+        if self.url.startswith(("postgresql://", "postgresql+psycopg://", "postgresql+psycopg2://")):
+            return SqlDatabase.postgres(self.url), "postgres"
+        raise ValueError("Native SQL migrations require a PostgreSQL or SQLite URL")
+
+    def _backend(self, database: SqlDatabase, dialect: str) -> NativeSqlMigrationBackend:
+        return NativeSqlMigrationBackend(database, self.source, self.migrations, dialect=dialect)
+
+    def _run(self, operation: str, *args):
+        database, dialect = self._open_database()
+        try:
+            backend = self._backend(database, dialect)
+            return getattr(backend, operation)(*args)
+        finally:
+            database.close()
+
+    def upgrade(self, target: str = "head") -> None:
+        self._run("upgrade", target)
+
+    def downgrade(self, target: str) -> None:
+        self._run("downgrade", target)
+
+    def plan(self) -> list[str]:
+        return self.status()["pending"]
+
+    def status(self) -> dict:
+        database, dialect = self._open_database()
+        try:
+            backend = self._backend(database, dialect)
+            with database.transaction() as transaction:
+                applied = backend._state(transaction)
+                revisions = [item.revision for item in self.migrations]
+            return {
+                "current": applied[-1:] if applied else [],
+                "heads": revisions[-1:] if revisions else [],
+                "applied": applied,
+                "pending": revisions[len(applied):],
+                "verification": "checksums",
+            }
+        finally:
+            database.close()

muscles/data/sql/providers.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class SqlGenerationRequest:
+    generator_type: str
+    name: str
+    force: bool = False
+    with_tests: bool = False
+
+
+class SqlResourceGeneratorProvider:
+    name = "muscles-data-sql.resource"
+
+    def supports(self, generator_type: str) -> bool:
+        return generator_type in {"sql-resource", "resource-sql"}
+
+    def generate(self, project_root: Path, request: SqlGenerationRequest) -> list[str]:
+        root = project_root / "generated"
+        root.mkdir(exist_ok=True)
+        target = root / f"{request.name}.py"
+        content = (
+            f"class {request.name.title().replace('_', '')}Resource:\n"
+            f"    sql_enabled = True\n"
+        )
+        target.write_text(content, encoding="utf-8")
+        return [str(target)]

muscles/data/sql/query.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class FilterClause:
+    field: str
+    op: str
+    value: Any = None
+
+
+@dataclass(frozen=True)
+class JoinClause:
+    table: Any
+    on: Any
+    is_outer: bool = False
+
+
+@dataclass(frozen=True)
+class QuerySpec:
+    filters: list[FilterClause] = field(default_factory=list)
+    or_filters: list[FilterClause] = field(default_factory=list)
+    joins: list[JoinClause] = field(default_factory=list)
+    select_columns: list[Any] = field(default_factory=list)
+    order_by: list[Any] = field(default_factory=list)
+    group_by: list[Any] = field(default_factory=list)
+    having: list[Any] = field(default_factory=list)
+    limit: int | None = 100
+    offset: int = 0
+    distinct: bool = False
+