pytest-pglite 0.1.0__py3-none-any.whl

pytest_pglite/__init__.py

@@ -0,0 +1,36 @@
+"""Native PGlite (PostgreSQL in WebAssembly) for Python test suites."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .config import IsolationMode, PGliteConfig
+from .errors import (
+    PGliteArtifactError,
+    PGliteConfigurationError,
+    PGliteError,
+    PGliteProtocolError,
+    PGliteQueueTimeoutError,
+    PGliteTrapError,
+    PGliteUnrecoverableError,
+)
+from .server import PGliteServer
+
+try:
+    __version__ = version("pytest-pglite")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "IsolationMode",
+    "PGliteArtifactError",
+    "PGliteConfig",
+    "PGliteConfigurationError",
+    "PGliteError",
+    "PGliteProtocolError",
+    "PGliteQueueTimeoutError",
+    "PGliteServer",
+    "PGliteTrapError",
+    "PGliteUnrecoverableError",
+    "__version__",
+]

pytest_pglite/_wasm/PROVENANCE.md

@@ -0,0 +1,65 @@
+# Vendored WASM artifact provenance
+
+`pytest-pglite` redistributes a prebuilt PostgreSQL 17.5 WebAssembly module so
+that users never need a WebAssembly toolchain. This file records exactly what
+is bundled and how to rebuild it.
+
+## Bundled file
+
+| File | Size | SHA-256 |
+| --- | --- | --- |
+| `pglite-17.5.20261006.tar.xz` | 5,145,000 | `cea663a6ca74ee8183f223e4a7c2255fe5a86cb4c491545669f95cc9e9370488` |
+
+The hash is also recorded in `SHA256SUMS` next to the artifact and is verified
+on every first use.
+
+## How it was built
+
+The module is produced by this repository's build pipeline
+(`build/scripts/build-wasi.sh`), which is a fork of
+[electric-sql/pglite-build](https://github.com/electric-sql/pglite-build)
+`portable` branch at commit
+`c195113dbaf09488f8d5eeb2db91dacd123b74d0`, plus
+`build/patches/0001-vector-static.patch`:
+
+- statically links pgvector 0.8.0 and installs `vector.control` /
+  `vector--0.8.0.sql`
+- registers the 104 SQL-visible pgvector symbols (including the 16 explicit
+  `AS 'MODULE_PATHNAME', 'symbol'` aliases) in the WASI dlopen/dlsym shim
+- calls pgvector's `_PG_init` (renamed to avoid a duplicate symbol with
+  plpgsql) so `hnsw.ef_search` and the other GUCs exist
+- fixes the shim's one-element `dltab` array and off-by-one, which corrupted
+  memory on the second `dlopen`
+- clears `ActivePortal` during trap recovery so a simple-query error no longer
+  wedges the only backend
+- ships a `lib/postgresql/vector.so` placeholder (PostgreSQL checks that the
+  library path exists before calling `dlopen`)
+- bounds compiler parallelism through `PGLITE_JOBS` (upstream defaults to
+  `nproc`)
+
+Build: 2026-10-06, Linux x86_64, wasi-sdk 25.0, PostgreSQL 17.5
+(`REL_17_5_WASM`), pgvector 0.8.0.
+
+## Contents
+
+~~~text
+tmp/pglite/bin/pglite.wasi          PostgreSQL 17.5 + pgvector (wasm32-wasip1), 23 MB
+tmp/pglite/password                 superuser password ("password")
+tmp/pglite/lib/postgresql/*.so      library placeholders (plpgsql, snowball, vector)
+tmp/pglite/share/postgresql/...     initdb inputs and extension SQL
+~~~
+
+## Rebuilding
+
+See `build/README.md` in the repository root. After a successful build:
+
+1. Boot the new module and run `pytest tests/test_vector.py` against it (point
+   the tests at it with `--pglite-wasm /path/to/tmp/pglite`).
+2. Copy the tarball here under a dated filename, update `SHA256SUMS` and this
+   file, and bump `ARTIFACT_FILENAME` in `src/pytest_pglite/artifacts.py`.
+
+## Licences
+
+PGlite is dual-licensed Apache-2.0 / PostgreSQL License. The postgres-pglite
+changes and pgvector are PostgreSQL License. libpglite is MIT. See
+`THIRD_PARTY_NOTICES.md`.

pytest_pglite/_wasm/SHA256SUMS

@@ -0,0 +1 @@
+cea663a6ca74ee8183f223e4a7c2255fe5a86cb4c491545669f95cc9e9370488  pglite-17.5.20261006.tar.xz

pytest_pglite/aot.py

@@ -0,0 +1,69 @@
+"""On-disk cache for ahead-of-time compiled WASM modules.
+
+Compiling the 23 MB pglite module takes about a second with Cranelift.
+Wasmtime can serialise the compiled module and deserialise it in tens of
+milliseconds, which makes per-worker startup much faster. Serialised modules
+are only valid for the exact engine build that produced them, so the cache
+key includes the wasmtime version and the platform.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+import wasmtime
+
+from .errors import PGliteArtifactError
+
+
+def _wasmtime_version() -> str:
+    try:
+        return version("wasmtime")
+    except PackageNotFoundError:  # pragma: no cover - vendored wasmtime
+        return "unknown"
+
+
+def cache_key(wasm_path: Path, artifact_digest: str | None = None) -> str:
+    if artifact_digest is None:
+        digest = hashlib.sha256(wasm_path.read_bytes()).hexdigest()
+    else:
+        digest = artifact_digest
+    machine = platform.machine() or "unknown"
+    return (
+        f"wasmtime{_wasmtime_version()}-py{sys.version_info[0]}{sys.version_info[1]}-"
+        f"{sys.platform}-{machine}-{digest[:16]}"
+    )
+
+
+def load_module(
+    engine: wasmtime.Engine,
+    wasm_path: Path,
+    cache_dir: Path,
+    key: str,
+    use_cache: bool = True,
+) -> wasmtime.Module:
+    """Load a module, using the AOT cache when available."""
+    cached = cache_dir / f"{key}.cwasm"
+    if use_cache and cached.is_file():
+        try:
+            return wasmtime.Module.deserialize(engine, cached.read_bytes())
+        except wasmtime.WasmtimeError:
+            cached.unlink(missing_ok=True)
+    try:
+        module = wasmtime.Module.from_file(engine, str(wasm_path))
+    except wasmtime.WasmtimeError as exc:  # pragma: no cover - corrupt artifact
+        raise PGliteArtifactError(f"failed to compile {wasm_path}: {exc}") from exc
+    if use_cache:
+        try:
+            cache_dir.mkdir(parents=True, exist_ok=True)
+            temporary = cached.with_suffix(".cwasm.tmp")
+            temporary.write_bytes(module.serialize())
+            temporary.replace(cached)
+        except OSError:
+            # A read-only or full cache must never break the run.
+            pass
+    return module

pytest_pglite/artifacts.py

@@ -0,0 +1,147 @@
+"""Locating, verifying and unpacking the bundled PGlite WASM artifact."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import tarfile
+from pathlib import Path
+
+from platformdirs import user_cache_dir
+
+from .errors import PGliteArtifactError
+
+ARTIFACT_FILENAME = "pglite-17.5.20261006.tar.xz"
+WASM_DIR = Path(__file__).resolve().parent / "_wasm"
+PREFIX_RELATIVE = Path("tmp") / "pglite"
+WASM_RELATIVE = Path("bin") / "pglite.wasi"
+
+
+def artifact_path() -> Path:
+    """Return the path of the main vendored artifact tarball."""
+    return WASM_DIR / ARTIFACT_FILENAME
+
+
+def artifact_paths() -> tuple[Path, ...]:
+    """All vendored tarballs, in extraction order."""
+    return (artifact_path(),)
+
+
+def sha256_file(path: Path, chunk_size: int = 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(chunk_size), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def expected_digest(filename: str = ARTIFACT_FILENAME) -> str:
+    sums = WASM_DIR / "SHA256SUMS"
+    if not sums.is_file():
+        raise PGliteArtifactError(f"missing checksum file: {sums}")
+    for line in sums.read_text(encoding="utf-8").splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1] == filename:
+            return parts[0]
+    raise PGliteArtifactError(f"no checksum recorded for {filename}")
+
+
+def verify_artifact(path: Path | None = None) -> str:
+    """Verify a vendored tarball and return its sha256 digest."""
+    path = path or artifact_path()
+    if not path.is_file():
+        raise PGliteArtifactError(
+            f"bundled PGlite artifact not found at {path}; "
+            "install the package from a wheel/sdist that includes it"
+        )
+    digest = sha256_file(path)
+    expected = expected_digest(path.name)
+    if digest != expected:
+        raise PGliteArtifactError(
+            f"PGlite artifact checksum mismatch for {path}: "
+            f"expected {expected}, got {digest}"
+        )
+    return digest
+
+
+def _extract_tar(path: Path, destination: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(path, "r:xz") as archive:
+        for member in archive.getmembers():
+            member_path = Path(member.name)
+            if member_path.is_absolute() or ".." in member_path.parts:
+                raise PGliteArtifactError(
+                    f"refusing to extract unsafe path {member.name!r} from {path}"
+                )
+        archive.extractall(destination, filter="data")
+
+
+def ensure_prefix(
+    wasm_path: Path | None = None, use_cache: bool = True
+) -> tuple[Path, str]:
+    """Return (prefix_root, cache_key).
+
+    ``prefix_root`` contains ``bin/pglite.wasi`` plus the ``share`` and ``lib``
+    trees the WASM module needs. For the bundled artifact the tarball is
+    verified and extracted once into the user cache directory.
+    """
+    if wasm_path is not None:
+        candidate = wasm_path.expanduser()
+        if candidate.is_file():
+            candidate = candidate.parent.parent
+        if not (candidate / WASM_RELATIVE).is_file():
+            raise PGliteArtifactError(
+                f"custom wasm path {wasm_path} does not contain bin/pglite.wasi"
+            )
+        digest = sha256_file(candidate / WASM_RELATIVE)
+        return candidate, digest
+
+    path = artifact_path()
+    digest = verify_artifact(path)
+    cache_root = Path(user_cache_dir("pytest-pglite")) / "artifacts" / digest[:16]
+    marker = cache_root / ".complete"
+    prefix = cache_root / PREFIX_RELATIVE
+    if not (use_cache and marker.is_file() and (prefix / WASM_RELATIVE).is_file()):
+        if cache_root.exists():
+            shutil.rmtree(cache_root, ignore_errors=True)
+        for tarball in artifact_paths():
+            if tarball.is_file():
+                verify_artifact(tarball)
+                _extract_tar(tarball, cache_root)
+        marker.write_text(digest, encoding="utf-8")
+    return prefix, digest
+
+
+def _link_or_copy(source: str, destination: str) -> str:
+    try:
+        os.link(source, destination)
+        return destination
+    except OSError:
+        return shutil.copy2(source, destination)
+
+
+def prepare_work_dir(prefix: Path, work_dir: Path) -> Path:
+    """Copy the prefix into a fresh work directory and return the work dir.
+
+    Hard links are used when possible so that starting a worker is cheap; the
+    WASM file is large but read-only.
+    """
+    target = work_dir / PREFIX_RELATIVE
+    if target.exists():
+        raise PGliteArtifactError(f"work directory already populated: {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(prefix, target, copy_function=_link_or_copy, symlinks=False)
+    dev = work_dir / "dev"
+    dev.mkdir(parents=True, exist_ok=True)
+    urandom = dev / "urandom"
+    if not urandom.exists():
+        urandom.write_bytes(os.urandom(256))
+    return work_dir
+
+
+def wasm_file(prefix: Path) -> Path:
+    wasm = prefix / WASM_RELATIVE
+    if not wasm.is_file():
+        raise PGliteArtifactError(f"missing WASM module: {wasm}")
+    return wasm

pytest_pglite/cli.py

@@ -0,0 +1,82 @@
+"""Standalone server entry point: ``pytest-pglite``."""
+
+from __future__ import annotations
+
+import argparse
+import signal
+import sys
+import time
+from pathlib import Path
+
+from .config import PGliteConfig
+from .server import PGliteServer
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="pytest-pglite",
+        description="Run a PGlite server (PostgreSQL 17.5 in WebAssembly).",
+    )
+    parser.add_argument("--work-dir", default=None, help="Database directory.")
+    parser.add_argument(
+        "--extensions",
+        default="",
+        help="Comma separated extensions to create at startup.",
+    )
+    parser.add_argument(
+        "--tcp-address",
+        default=None,
+        metavar="HOST:PORT",
+        help="Listen on TCP as well (port 0 = OS-assigned).",
+    )
+    parser.add_argument("--wasm", default=None, help="Custom bin/pglite.wasi build.")
+    parser.add_argument("--keep-tmp", action="store_true", help="Keep files.")
+    parser.add_argument("--log-level", default="INFO")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+    host = "127.0.0.1"
+    port = 0
+    if args.tcp_address:
+        parsed_host, _, parsed_port = args.tcp_address.rpartition(":")
+        host = parsed_host or "127.0.0.1"
+        if parsed_port.isdigit():
+            port = int(parsed_port)
+    extensions = tuple(
+        part.strip() for part in args.extensions.split(",") if part.strip()
+    )
+    server = PGliteServer(
+        PGliteConfig(
+            work_dir=Path(args.work_dir) if args.work_dir else None,
+            extensions=extensions,
+            tcp=bool(args.tcp_address),
+            tcp_host=host,
+            tcp_port=port,
+            wasm_path=Path(args.wasm) if args.wasm else None,
+            keep_tmp=bool(args.keep_tmp),
+            log_level=args.log_level or "INFO",
+        )
+    )
+    server.start()
+    print(f"PGlite ready: {server.dsn}")
+    print(f"work dir: {server.work_dir}")
+    stopped = False
+
+    def _handle_signal(signum: int, frame: object) -> None:
+        nonlocal stopped
+        stopped = True
+
+    signal.signal(signal.SIGINT, _handle_signal)
+    signal.signal(signal.SIGTERM, _handle_signal)
+    try:
+        while not stopped:
+            time.sleep(0.2)
+    finally:
+        server.stop()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

pytest_pglite/config.py

@@ -0,0 +1,146 @@
+"""Configuration models for pytest-pglite.
+
+All settings can be provided through environment variables using the
+``PGLITE_`` prefix, for example ``PGLITE_ISOLATION=transaction``, or through
+the pytest command line options documented in :mod:`pytest_pglite.plugin`.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+_EXTENSION_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
+class IsolationMode(StrEnum):
+    """How per-test isolation is achieved."""
+
+    NONE = "none"
+    """No automatic isolation; the database keeps its state between tests."""
+
+    SCHEMA = "schema"
+    """Drop and recreate the ``public`` schema around each test (default)."""
+
+    TRANSACTION = "transaction"
+    """Roll back the fixture connection at the end of each test."""
+
+    DATABASE = "database"
+    """Reserved; not supported by the single-user PGlite backend."""
+
+
+class PGliteConfig(BaseSettings):
+    """Validated runtime configuration for a PGlite server."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="PGLITE_",
+        extra="ignore",
+        env_file=None,
+        enable_decoding=False,
+    )
+
+    pg_version: str = Field(
+        default="17.5",
+        description="PostgreSQL major.minor version of the bundled WASM build.",
+    )
+    extensions: tuple[str, ...] = Field(
+        default=(),
+        description="Extensions created in the database at startup.",
+    )
+    isolation: IsolationMode = Field(
+        default=IsolationMode.SCHEMA,
+        description="Per-test isolation strategy.",
+    )
+    work_dir: Path | None = Field(
+        default=None,
+        description="Directory for database files. Defaults to a temp directory.",
+    )
+    wasm_path: Path | None = Field(
+        default=None,
+        description="Directory containing a custom bin/pglite.wasi build.",
+    )
+    unix_socket: bool = Field(
+        default=True,
+        description="Listen on a Unix domain socket.",
+    )
+    tcp: bool = Field(
+        default=False,
+        description="Also listen on TCP.",
+    )
+    tcp_host: str = Field(default="127.0.0.1")
+    tcp_port: int = Field(
+        default=0,
+        ge=0,
+        le=65535,
+        description="TCP port; 0 lets the operating system assign a free port.",
+    )
+    max_connections: int = Field(default=32, ge=1, le=1024)
+    queue_timeout: float = Field(
+        default=60.0,
+        gt=0,
+        description="Seconds a connection waits for the shared backend.",
+    )
+    startup_timeout: float = Field(default=120.0, gt=0)
+    holder_timeout: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "Seconds a connection may hold the backend while idle. "
+            "None waits forever (clients normally Sync promptly)."
+        ),
+    )
+    aot_cache: bool = Field(
+        default=True,
+        description="Cache the compiled WebAssembly module on disk.",
+    )
+    template_cache: bool = Field(
+        default=True,
+        description=("Cache an initialised database directory so workers skip initdb."),
+    )
+    keep_tmp: bool = Field(default=False)
+    log_level: str = Field(default="INFO")
+    user: str = Field(default="postgres")
+    database: str = Field(default="template1")
+    password: str = Field(default="password")
+
+    @field_validator("extensions", mode="before")
+    @classmethod
+    def _split_extensions(cls, value: object) -> object:
+        if isinstance(value, str):
+            return tuple(part.strip() for part in value.split(",") if part.strip())
+        return value
+
+    @field_validator("extensions")
+    @classmethod
+    def _check_extensions(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        seen: list[str] = []
+        for name in value:
+            normalised = name.strip().lower()
+            if not normalised:
+                continue
+            if not _EXTENSION_RE.match(normalised):
+                raise ValueError(
+                    f"invalid extension name {name!r}; expected [a-z][a-z0-9_]*"
+                )
+            if normalised not in seen:
+                seen.append(normalised)
+        return tuple(seen)
+
+    @field_validator("work_dir", "wasm_path", mode="before")
+    @classmethod
+    def _expand(cls, value: object) -> object:
+        if isinstance(value, str) and value:
+            return Path(value).expanduser()
+        return value
+
+    @field_validator("log_level")
+    @classmethod
+    def _check_log_level(cls, value: str) -> str:
+        level = value.upper()
+        if level not in {"DEBUG", "INFO", "WARNING", "ERROR"}:
+            raise ValueError("log_level must be one of DEBUG, INFO, WARNING, ERROR")
+        return level