pyxle-db 0.2.0__py3-none-any.whl

pyxle_db/__init__.py

@@ -0,0 +1,95 @@
+"""pyxle-db — the official database plugin for Pyxle.
+
+One explicit-SQL API over SQLite, PostgreSQL, and MySQL:
+
+* :class:`Database` — async facade over a driver backend. Accepts a bare
+  SQLite path (0.1-compatible) or any supported database URL. Queries are
+  written once in canonical qmark style (``?`` placeholders) and translated
+  per backend with a literal-aware rewriter.
+* :class:`Migrator` — discovery + atomic application of ordered SQL
+  migrations from a filesystem directory. Keeps a ``schema_migrations``
+  table with applied-hash tracking so edits to committed migrations are
+  detected and rejected.
+* :func:`connect` — convenience entry point that opens a :class:`Database`
+  and applies a migrations directory in one call.
+
+Design constraints:
+
+* Zero third-party dependencies for SQLite; PostgreSQL and MySQL drivers
+  install via extras (``pyxle-db[postgres]``, ``pyxle-db[mysql]``).
+* Parameterised queries only — no string interpolation in SQL.
+* Every write goes through a transaction (implicit or explicit).
+* Driver exceptions never leak: every failure crosses the boundary as a
+  :class:`DatabaseError` subclass, so application code never imports
+  ``sqlite3``/``asyncpg``/``asyncmy`` just to handle an error.
+* Fail loudly: bad URLs, missing drivers, unknown migrations, and checksum
+  drift all raise specific, actionable error types.
+"""
+
+from __future__ import annotations
+
+from pyxle_db.backends import Dialect
+from pyxle_db.contract import DatabaseLike, TransactionLike
+from pyxle_db.database import Database, Transaction, connect
+from pyxle_db.errors import (
+    ConfigurationError,
+    DatabaseError,
+    IntegrityError,
+    MigrationChecksumMismatch,
+    MigrationError,
+    NotFoundError,
+    OperationalError,
+    UnsupportedOperationError,
+)
+from pyxle_db.migrator import Migration, Migrator
+from pyxle_db.rows import Row
+from pyxle_db.url import DatabaseConfig, parse_database_url
+
+
+def get_database() -> Database:
+    """Return the :class:`Database` the active ``pyxle-db`` plugin opened.
+
+    Short form for app code that wants the database without reaching
+    through ``request.app.state.pyxle_plugins``::
+
+        from pyxle_db import get_database
+
+        @server
+        async def load(request):
+            db = get_database()
+            row = await db.fetchone("SELECT ... FROM ...")
+
+    Requires ``pyxle-db`` to be listed in ``pyxle.config.json::plugins``
+    — otherwise raises :class:`pyxle.plugins.PluginServiceError`.
+    """
+    from pyxle.plugins import plugin as _plugin  # local import to
+    # avoid pyxle-db depending on pyxle at module-load time; the plugin
+    # system is only needed at *call* time.
+
+    return _plugin("db.database")
+
+
+__all__ = [
+    "Database",
+    "DatabaseLike",
+    "Transaction",
+    "TransactionLike",
+    "Row",
+    "connect",
+    "Migration",
+    "Migrator",
+    "Dialect",
+    "DatabaseConfig",
+    "parse_database_url",
+    "DatabaseError",
+    "IntegrityError",
+    "OperationalError",
+    "ConfigurationError",
+    "UnsupportedOperationError",
+    "NotFoundError",
+    "MigrationError",
+    "MigrationChecksumMismatch",
+    "get_database",
+]
+
+__version__ = "0.2.0"

pyxle_db/backends/__init__.py

@@ -0,0 +1,57 @@
+"""Backend registry — maps a parsed config to a driver adapter.
+
+Driver imports happen lazily so the base install stays dependency-free:
+SQLite always works; PostgreSQL needs ``pyxle-db[postgres]``; MySQL needs
+``pyxle-db[mysql]``. A missing driver surfaces as a clear
+:class:`pyxle_db.errors.ConfigurationError`, not an ImportError five
+frames deep.
+"""
+
+from __future__ import annotations
+
+from pyxle_db.backends.base import (
+    MYSQL_DIALECT,
+    POSTGRESQL_DIALECT,
+    SQLITE_DIALECT,
+    Backend,
+    BackendTransaction,
+    Dialect,
+)
+from pyxle_db.errors import ConfigurationError
+from pyxle_db.url import DatabaseConfig
+
+__all__ = [
+    "Backend",
+    "BackendTransaction",
+    "Dialect",
+    "SQLITE_DIALECT",
+    "POSTGRESQL_DIALECT",
+    "MYSQL_DIALECT",
+    "create_backend",
+]
+
+
+def create_backend(config: DatabaseConfig) -> Backend:
+    if config.backend == "sqlite":
+        from pyxle_db.backends.sqlite import SqliteBackend
+
+        return SqliteBackend(config)
+    if config.backend == "postgresql":
+        try:
+            from pyxle_db.backends.postgresql import PostgresBackend
+        except ImportError as exc:  # asyncpg not installed
+            raise ConfigurationError(
+                "PostgreSQL support requires the asyncpg driver — "
+                "install with: pip install 'pyxle-db[postgres]'"
+            ) from exc
+        return PostgresBackend(config)
+    if config.backend == "mysql":
+        try:
+            from pyxle_db.backends.mysql import MysqlBackend
+        except ImportError as exc:  # asyncmy not installed
+            raise ConfigurationError(
+                "MySQL support requires the asyncmy driver — "
+                "install with: pip install 'pyxle-db[mysql]'"
+            ) from exc
+        return MysqlBackend(config)
+    raise ConfigurationError(f"Unknown backend: {config.backend!r}")

pyxle_db/backends/base.py

@@ -0,0 +1,172 @@
+"""Backend protocol — the contract every database driver adapter implements.
+
+A backend owns connections/pools for exactly one database and speaks that
+database's native parameter style. Everything above the backend (the
+:class:`pyxle_db.Database` facade, the migrator, application code) speaks
+canonical qmark SQL; the facade translates via :mod:`pyxle_db.sql` before
+calling the backend, so every backend receives SQL already in its native
+parameter style (for SQLite that native style happens to be qmark).
+
+Implementations:
+
+* :mod:`pyxle_db.backends.sqlite` — stdlib ``sqlite3``, thread-local
+  connections bridged with ``asyncio.to_thread``. Zero dependencies.
+* :mod:`pyxle_db.backends.postgresql` — ``asyncpg`` pool
+  (install extra: ``pyxle-db[postgres]``).
+* :mod:`pyxle_db.backends.mysql` — ``asyncmy`` pool
+  (install extra: ``pyxle-db[mysql]``).
+
+Contract rules (enforced by the shared conformance tests):
+
+1. Every error raised crosses the boundary as a :mod:`pyxle_db.errors`
+   type — driver exceptions never leak.
+2. Constraint violations (unique, FK, NOT NULL, CHECK) raise
+   :class:`pyxle_db.errors.IntegrityError`.
+3. Fetch methods return :class:`pyxle_db.rows.Row`.
+4. Timestamp/datetime columns come back timezone-aware UTC; naive values
+   read from the database are assumed UTC and tagged as such. The
+   guarantee covers top-level column values (not datetimes nested inside
+   driver-specific composite/array types).
+5. ``connect()`` is idempotent; ``aclose()`` is idempotent and the backend
+   must be reusable after a subsequent ``connect()``. Backends MAY also
+   reopen lazily after close (SQLite does, preserving 0.1 semantics).
+6. A transaction is exclusive to its caller; concurrent ``transaction()``
+   calls must not interleave statements on the same underlying connection.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, AsyncContextManager, Iterable, Sequence
+
+from pyxle_db.rows import Row
+
+Params = Sequence[Any]
+
+
+def utc_naive_params(params: Params) -> tuple[Any, ...]:
+    """Normalise top-level datetime parameters to naive UTC for binding.
+
+    The package-wide datetime contract is symmetric: columns store UTC wall
+    time, reads come back as aware-UTC datetimes, and callers may bind either
+    naive (assumed UTC) or aware (converted to UTC) datetimes. The SQLite
+    backend gets this from its registered adapter; PostgreSQL and MySQL
+    drivers do not — asyncpg rejects aware datetimes for ``TIMESTAMP``
+    columns outright, and asyncmy would silently serialise an aware
+    datetime's *foreign wall clock*, corrupting the stored instant. Both
+    backends therefore run every parameter sequence through this before
+    handing it to the driver. Only top-level values are touched, matching
+    the read-side rule (containers are passed through untouched).
+    """
+    return tuple(
+        value.astimezone(timezone.utc).replace(tzinfo=None)
+        if isinstance(value, datetime) and value.tzinfo is not None
+        else value
+        for value in params
+    )
+
+
+@dataclass(frozen=True)
+class Dialect:
+    """What the SQL layer needs to know about a backend's flavour."""
+
+    name: str
+    """``"sqlite"`` | ``"postgresql"`` | ``"mysql"``."""
+
+    paramstyle: str
+    """``"qmark"`` | ``"numeric_dollar"`` | ``"format"`` (see pyxle_db.sql)."""
+
+    migrations_table_ddl: str
+    """``CREATE TABLE IF NOT EXISTS schema_migrations`` for this dialect."""
+
+    supports_sync: bool = False
+    """True only for SQLite — powers ``Database.sync_transaction()``."""
+
+
+SQLITE_DIALECT = Dialect(
+    name="sqlite",
+    paramstyle="qmark",
+    migrations_table_ddl=(
+        "CREATE TABLE IF NOT EXISTS schema_migrations (\n"
+        "    id TEXT PRIMARY KEY,\n"
+        "    checksum TEXT NOT NULL,\n"
+        "    applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP\n"
+        ")"
+    ),
+    supports_sync=True,
+)
+
+POSTGRESQL_DIALECT = Dialect(
+    name="postgresql",
+    paramstyle="numeric_dollar",
+    migrations_table_ddl=(
+        "CREATE TABLE IF NOT EXISTS schema_migrations (\n"
+        "    id TEXT PRIMARY KEY,\n"
+        "    checksum TEXT NOT NULL,\n"
+        "    applied_at TIMESTAMPTZ NOT NULL DEFAULT now()\n"
+        ")"
+    ),
+)
+
+MYSQL_DIALECT = Dialect(
+    name="mysql",
+    paramstyle="format",
+    migrations_table_ddl=(
+        "CREATE TABLE IF NOT EXISTS schema_migrations (\n"
+        "    id VARCHAR(255) PRIMARY KEY,\n"
+        "    checksum VARCHAR(64) NOT NULL,\n"
+        "    applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP\n"
+        ")"
+    ),
+)
+
+
+class BackendTransaction(ABC):
+    """One open transaction. All methods receive backend-native SQL."""
+
+    @abstractmethod
+    async def execute(self, sql: str, params: Params = ()) -> int:
+        """Run one statement; return affected rowcount (-1 if unknown)."""
+
+    @abstractmethod
+    async def executemany(self, sql: str, seq_params: Iterable[Params]) -> None: ...
+
+    @abstractmethod
+    async def fetchone(self, sql: str, params: Params = ()) -> Row | None: ...
+
+    @abstractmethod
+    async def fetchall(self, sql: str, params: Params = ()) -> list[Row]: ...
+
+
+class Backend(ABC):
+    """Connection owner for one configured database."""
+
+    dialect: Dialect
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """Create pools / verify connectivity. Idempotent."""
+
+    @abstractmethod
+    async def aclose(self) -> None:
+        """Release every connection. Idempotent."""
+
+    @abstractmethod
+    async def execute(self, sql: str, params: Params = ()) -> int:
+        """One-shot autocommitted statement; returns affected rowcount."""
+
+    @abstractmethod
+    async def executemany(self, sql: str, seq_params: Iterable[Params]) -> None:
+        """One-shot bulk statement, atomically (single transaction)."""
+
+    @abstractmethod
+    async def fetchone(self, sql: str, params: Params = ()) -> Row | None: ...
+
+    @abstractmethod
+    async def fetchall(self, sql: str, params: Params = ()) -> list[Row]: ...
+
+    @abstractmethod
+    def transaction(self) -> AsyncContextManager[BackendTransaction]:
+        """Open a transaction scope; commit on exit, roll back on exception."""

pyxle_db/backends/mysql.py

@@ -0,0 +1,299 @@
+"""MySQL/MariaDB backend on an :mod:`asyncmy` connection pool.
+
+Install with ``pip install 'pyxle-db[mysql]'``. The pool is created lazily on
+first :meth:`MysqlBackend.connect` with ``charset=utf8mb4`` (always) and
+``autocommit=False`` — every one-shot helper therefore commits explicitly,
+including the fetch helpers: with autocommit off even a ``SELECT`` opens an
+InnoDB read view, and the connection must not return to the pool holding one.
+
+Pool sizing is configurable through URL options::
+
+    mysql://app:secret@db.internal:3306/appdb?pool_min=2&pool_max=20
+
+SQL arrives already translated to ``%s`` style by the facade
+(:func:`pyxle_db.sql.translate`), which also doubles literal percent signs
+outside string literals. asyncmy only collapses those ``%%`` back to ``%``
+when ``args`` is not ``None``, so every cursor call here passes a parameter
+tuple — an empty one when the statement takes no parameters.
+
+Contract compliance (see :mod:`pyxle_db.backends.base`):
+
+* asyncmy exceptions are translated via :func:`_translate` and never leak.
+* Fetches return :class:`pyxle_db.rows.Row` with datetimes normalised to
+  timezone-aware UTC (asyncmy returns naive values; they are assumed UTC).
+* ``connect()`` / ``aclose()`` are idempotent; the backend is reusable after
+  ``aclose()`` followed by another ``connect()``.
+* Each transaction holds its own pooled connection for its whole scope, so
+  concurrent transactions can never interleave statements.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from typing import Any, AsyncIterator, Awaitable, Callable, Iterable, Mapping, Sequence, TypeVar
+
+import asyncmy
+import asyncmy.errors
+
+from pyxle_db.backends.base import (
+    MYSQL_DIALECT,
+    Backend,
+    BackendTransaction,
+    Params,
+    utc_naive_params,
+)
+from pyxle_db.errors import (
+    ConfigurationError,
+    DatabaseError,
+    IntegrityError,
+    OperationalError,
+)
+from pyxle_db.rows import Row
+from pyxle_db.url import DatabaseConfig
+
+__all__ = ["MysqlBackend"]
+
+T = TypeVar("T")
+
+_DEFAULT_POOL_MIN = 1
+_DEFAULT_POOL_MAX = 10
+
+
+def _translate(exc: Exception) -> DatabaseError:
+    """Map an asyncmy exception onto the :mod:`pyxle_db.errors` hierarchy.
+
+    * ``asyncmy.errors.IntegrityError`` → :class:`IntegrityError`
+      (duplicate key, FK violation, NOT NULL, …).
+    * ``asyncmy.errors.OperationalError`` / ``InterfaceError`` →
+      :class:`OperationalError` — the retryable family, covering the
+      connection errnos (2002/2003 can't connect, 2006 server has gone away,
+      2013 lost connection) and 1205 lock-wait timeout.
+    * Any other ``asyncmy.errors.MySQLError`` → :class:`DatabaseError`.
+
+    Callers chain the original with ``raise _translate(exc) from exc``.
+    """
+    if isinstance(exc, asyncmy.errors.IntegrityError):
+        return IntegrityError(str(exc))
+    if isinstance(exc, (asyncmy.errors.OperationalError, asyncmy.errors.InterfaceError)):
+        return OperationalError(str(exc))
+    return DatabaseError(str(exc))
+
+
+def _as_utc(value: Any) -> Any:
+    """Tag naive datetimes as UTC; convert aware ones to UTC (contract rule 4)."""
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+    return value
+
+
+def _build_row(description: Sequence[Sequence[Any]], values: Sequence[Any]) -> Row:
+    """Build a :class:`Row` from a DB-API cursor description and one tuple."""
+    return Row([column[0] for column in description], [_as_utc(v) for v in values])
+
+
+def _pool_bounds(options: Mapping[str, str]) -> tuple[int, int]:
+    """Read ``pool_min`` / ``pool_max`` URL options into asyncmy pool sizes."""
+    minsize = _int_option(options, "pool_min", _DEFAULT_POOL_MIN)
+    maxsize = _int_option(options, "pool_max", _DEFAULT_POOL_MAX)
+    if minsize < 0:
+        raise ConfigurationError(f"pool_min must be >= 0, got {minsize}")
+    if maxsize < 1:
+        raise ConfigurationError(f"pool_max must be >= 1, got {maxsize}")
+    if maxsize < minsize:
+        raise ConfigurationError(
+            f"pool_max ({maxsize}) must be >= pool_min ({minsize})"
+        )
+    return minsize, maxsize
+
+
+def _int_option(options: Mapping[str, str], key: str, default: int) -> int:
+    raw = options.get(key)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        raise ConfigurationError(
+            f"Database URL option {key!r} must be an integer, got {raw!r}"
+        ) from None
+
+
+async def _rollback_quietly(conn: asyncmy.Connection) -> None:
+    """Best-effort rollback while another exception is already in flight.
+
+    If the rollback itself fails (typically because the connection died) the
+    original error is the one worth reporting, so driver errors are dropped.
+    """
+    try:
+        await conn.rollback()
+    except asyncmy.errors.MySQLError:
+        pass
+
+
+class _MysqlTransaction(BackendTransaction):
+    """Statements on one pooled connection; commit/rollback is the scope's job."""
+
+    __slots__ = ("_conn",)
+
+    def __init__(self, conn: asyncmy.Connection) -> None:
+        self._conn = conn
+
+    async def execute(self, sql: str, params: Params = ()) -> int:
+        try:
+            async with self._conn.cursor() as cursor:
+                await cursor.execute(sql, utc_naive_params(params))
+                return int(cursor.rowcount)
+        except asyncmy.errors.MySQLError as exc:
+            raise _translate(exc) from exc
+
+    async def executemany(self, sql: str, seq_params: Iterable[Params]) -> None:
+        rows = [utc_naive_params(p) for p in seq_params]
+        if not rows:
+            return
+        try:
+            async with self._conn.cursor() as cursor:
+                await cursor.executemany(sql, rows)
+        except asyncmy.errors.MySQLError as exc:
+            raise _translate(exc) from exc
+
+    async def fetchone(self, sql: str, params: Params = ()) -> Row | None:
+        try:
+            async with self._conn.cursor() as cursor:
+                await cursor.execute(sql, utc_naive_params(params))
+                values = await cursor.fetchone()
+                if values is None:
+                    return None
+                return _build_row(cursor.description, values)
+        except asyncmy.errors.MySQLError as exc:
+            raise _translate(exc) from exc
+
+    async def fetchall(self, sql: str, params: Params = ()) -> list[Row]:
+        try:
+            async with self._conn.cursor() as cursor:
+                await cursor.execute(sql, utc_naive_params(params))
+                values = await cursor.fetchall()
+                return [_build_row(cursor.description, row) for row in values]
+        except asyncmy.errors.MySQLError as exc:
+            raise _translate(exc) from exc
+
+
+class MysqlBackend(Backend):
+    """MySQL adapter. SQL must already be in ``%s`` (format) parameter style."""
+
+    dialect = MYSQL_DIALECT
+
+    def __init__(self, config: DatabaseConfig) -> None:
+        self._config = config
+        self._pool_min, self._pool_max = _pool_bounds(config.options)
+        self._pool: asyncmy.Pool | None = None
+        self._connect_lock = asyncio.Lock()
+
+    # -- lifecycle ------------------------------------------------------------
+
+    async def connect(self) -> None:
+        await self._ensure_pool()
+
+    async def aclose(self) -> None:
+        pool, self._pool = self._pool, None
+        if pool is None:
+            return
+        pool.close()
+        await pool.wait_closed()
+
+    async def _ensure_pool(self) -> asyncmy.Pool:
+        pool = self._pool
+        if pool is not None:
+            return pool
+        async with self._connect_lock:
+            if self._pool is None:
+                try:
+                    self._pool = await asyncmy.create_pool(
+                        host=self._config.host,
+                        port=self._config.port,
+                        user=self._config.user,
+                        password=self._config.password,
+                        database=self._config.database,
+                        charset="utf8mb4",
+                        autocommit=False,
+                        minsize=self._pool_min,
+                        maxsize=self._pool_max,
+                        # Pin the session to UTC. MySQL converts TIMESTAMP
+                        # columns to the session time_zone on read (default:
+                        # the server's SYSTEM zone), which would shift values
+                        # that the row layer then mis-tags as UTC. With the
+                        # session pinned, TIMESTAMP and NOW() speak UTC and
+                        # the naive-equals-UTC contract holds everywhere.
+                        init_command="SET time_zone = '+00:00'",
+                    )
+                except asyncmy.errors.MySQLError as exc:
+                    raise _translate(exc) from exc
+            return self._pool
+
+    # -- one-shot helpers -------------------------------------------------------
+
+    async def _autocommit(self, op: Callable[[_MysqlTransaction], Awaitable[T]]) -> T:
+        """Run ``op`` on a pooled connection, commit, and always release.
+
+        Rolls back on any failure so the connection re-enters the pool clean.
+        ``op`` raises already-translated errors; the outer handler translates
+        what the commit itself may raise.
+        """
+        pool = await self._ensure_pool()
+        conn = await pool.acquire()
+        try:
+            try:
+                result = await op(_MysqlTransaction(conn))
+                await conn.commit()
+                return result
+            except BaseException:
+                await _rollback_quietly(conn)
+                raise
+        except asyncmy.errors.MySQLError as exc:
+            raise _translate(exc) from exc
+        finally:
+            pool.release(conn)
+
+    async def execute(self, sql: str, params: Params = ()) -> int:
+        return await self._autocommit(lambda tx: tx.execute(sql, params))
+
+    async def executemany(self, sql: str, seq_params: Iterable[Params]) -> None:
+        rows = [utc_naive_params(p) for p in seq_params]
+        if not rows:
+            return
+        await self._autocommit(lambda tx: tx.executemany(sql, rows))
+
+    async def fetchone(self, sql: str, params: Params = ()) -> Row | None:
+        return await self._autocommit(lambda tx: tx.fetchone(sql, params))
+
+    async def fetchall(self, sql: str, params: Params = ()) -> list[Row]:
+        return await self._autocommit(lambda tx: tx.fetchall(sql, params))
+
+    # -- transactions ------------------------------------------------------------
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[BackendTransaction]:
+        """One ``BEGIN``-scoped connection: commit on exit, roll back on error.
+
+        The connection is acquired for the whole scope and released in all
+        cases, so concurrent transactions never share a connection
+        (contract rule 6).
+        """
+        pool = await self._ensure_pool()
+        conn = await pool.acquire()
+        try:
+            try:
+                await conn.begin()
+                yield _MysqlTransaction(conn)
+            except BaseException:
+                await _rollback_quietly(conn)
+                raise
+            else:
+                await conn.commit()
+        except asyncmy.errors.MySQLError as exc:
+            raise _translate(exc) from exc
+        finally:
+            pool.release(conn)