simplebroker-pg 1.0.0__tar.gz

simplebroker_pg-1.0.0/.gitignore

@@ -0,0 +1,87 @@
+# Accidental database files created by str(BrokerCore) coercion
+<simplebroker.*>
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.code
+.claude
+.codex
+docs/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.coverage
+.coverage.*
+coverage.xml
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.ruff/
+.pytest_cache/
+
+# SimpleBroker specific
+*.db
+*.db-shm
+*.db-wal
+.broker.db*
+test.db
+benchmark_pragma.py
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.bak
+*.log
+
+# Multi-agent
+.claude
+.mcp.json
+agent_history/
+.broker.db
+.broker.db-shm
+.broker.db-wal
+weft/
+.aider*
+.codex*
+.code*
+.coder*

simplebroker_pg-1.0.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: simplebroker-pg
+Version: 1.0.0
+Summary: Postgres backend plugin for SimpleBroker
+Author-email: Van Lindberg <van.lindberg@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: psycopg-pool<4,>=3.1
+Requires-Dist: psycopg[binary]<4,>=3
+Requires-Dist: simplebroker>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# simplebroker-pg
+
+Postgres backend plugin for SimpleBroker.
+
+This package is intentionally separate from `simplebroker` itself. SimpleBroker
+remains SQLite-first. This package adds a Postgres backend through the public
+backend plugin hook.
+
+## Requirements
+
+- PostgreSQL
+- A dedicated schema for SimpleBroker tables
+
+`public` is intentionally rejected.
+
+## Installation
+
+```bash
+# Add to an existing pipx-installed simplebroker (recommended)
+pipx inject simplebroker simplebroker-pg
+
+# Or install with uv to use as a library
+uv add simplebroker-pg
+
+# Or with pip
+pip install simplebroker-pg
+```
+
+## Python Usage
+
+```python
+from simplebroker import Queue
+from simplebroker_pg import PostgresRunner
+
+runner = PostgresRunner(
+    "postgresql://postgres@127.0.0.1:54329/simplebroker_test",
+    schema="simplebroker_app",
+)
+
+queue = Queue("jobs", runner=runner, persistent=True)
+queue.write("hello")
+print(queue.read())
+```
+
+## CLI Usage
+
+Create `.simplebroker.toml` in the project root:
+
+```toml
+version = 1
+backend = "postgres"
+target = "postgresql://postgres@127.0.0.1:54329/simplebroker_test"
+
+[backend_options]
+schema = "simplebroker_app"
+```
+
+Then use the normal CLI from any child directory with project scope enabled:
+
+```bash
+broker init
+broker write jobs hello
+broker read jobs
+```
+
+You can also run entirely from environment variables without a project config:
+
+```bash
+BROKER_BACKEND=postgres \
+BROKER_BACKEND_TARGET='postgresql://postgres@127.0.0.1:54329/simplebroker_test' \
+BROKER_BACKEND_SCHEMA='simplebroker_app' \
+BROKER_BACKEND_PASSWORD='postgres' \
+broker init
+```
+
+Notes:
+
+- `BROKER_BACKEND_TARGET` overrides the whole target string.
+- `BROKER_BACKEND_HOST`, `BROKER_BACKEND_PORT`, `BROKER_BACKEND_USER`,
+  `BROKER_BACKEND_PASSWORD`, and `BROKER_BACKEND_DATABASE` are only used when there is no
+  target from env or toml.
+- `BROKER_BACKEND_PASSWORD` is never written to `.simplebroker.toml`.
+- The Postgres database must already exist. `broker init` creates the managed schema/tables
+  inside that database; it does not create the database itself.
+- Missing backend/plugin errors are distinct from target/auth errors. Invalid schema names,
+  bad passwords, malformed targets, and missing databases are reported as validation or
+  connection failures, not as "backend not available" errors.

simplebroker_pg-1.0.0/README.md

@@ -0,0 +1,87 @@
+# simplebroker-pg
+
+Postgres backend plugin for SimpleBroker.
+
+This package is intentionally separate from `simplebroker` itself. SimpleBroker
+remains SQLite-first. This package adds a Postgres backend through the public
+backend plugin hook.
+
+## Requirements
+
+- PostgreSQL
+- A dedicated schema for SimpleBroker tables
+
+`public` is intentionally rejected.
+
+## Installation
+
+```bash
+# Add to an existing pipx-installed simplebroker (recommended)
+pipx inject simplebroker simplebroker-pg
+
+# Or install with uv to use as a library
+uv add simplebroker-pg
+
+# Or with pip
+pip install simplebroker-pg
+```
+
+## Python Usage
+
+```python
+from simplebroker import Queue
+from simplebroker_pg import PostgresRunner
+
+runner = PostgresRunner(
+    "postgresql://postgres@127.0.0.1:54329/simplebroker_test",
+    schema="simplebroker_app",
+)
+
+queue = Queue("jobs", runner=runner, persistent=True)
+queue.write("hello")
+print(queue.read())
+```
+
+## CLI Usage
+
+Create `.simplebroker.toml` in the project root:
+
+```toml
+version = 1
+backend = "postgres"
+target = "postgresql://postgres@127.0.0.1:54329/simplebroker_test"
+
+[backend_options]
+schema = "simplebroker_app"
+```
+
+Then use the normal CLI from any child directory with project scope enabled:
+
+```bash
+broker init
+broker write jobs hello
+broker read jobs
+```
+
+You can also run entirely from environment variables without a project config:
+
+```bash
+BROKER_BACKEND=postgres \
+BROKER_BACKEND_TARGET='postgresql://postgres@127.0.0.1:54329/simplebroker_test' \
+BROKER_BACKEND_SCHEMA='simplebroker_app' \
+BROKER_BACKEND_PASSWORD='postgres' \
+broker init
+```
+
+Notes:
+
+- `BROKER_BACKEND_TARGET` overrides the whole target string.
+- `BROKER_BACKEND_HOST`, `BROKER_BACKEND_PORT`, `BROKER_BACKEND_USER`,
+  `BROKER_BACKEND_PASSWORD`, and `BROKER_BACKEND_DATABASE` are only used when there is no
+  target from env or toml.
+- `BROKER_BACKEND_PASSWORD` is never written to `.simplebroker.toml`.
+- The Postgres database must already exist. `broker init` creates the managed schema/tables
+  inside that database; it does not create the database itself.
+- Missing backend/plugin errors are distinct from target/auth errors. Invalid schema names,
+  bad passwords, malformed targets, and missing databases are reported as validation or
+  connection failures, not as "backend not available" errors.

simplebroker_pg-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "simplebroker-pg"
+version = "1.0.0"
+description = "Postgres backend plugin for SimpleBroker"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Van Lindberg", email = "van.lindberg@gmail.com"},
+]
+dependencies = [
+    "simplebroker>=3.0.0",
+    "psycopg[binary]>=3,<4",
+    "psycopg-pool>=3.1,<4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-timeout>=2.4.0",
+]
+
+[project.entry-points."simplebroker.backends"]
+postgres = "simplebroker_pg.plugin:get_backend_plugin"
+
+[tool.hatch.build]
+include = [
+    "simplebroker_pg/**/*.py",
+    "README.md",
+]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+addopts = "-ra -q"
+markers = [
+    "pg_only: tests that validate the Postgres extension package",
+]

simplebroker_pg-1.0.0/simplebroker_pg/__init__.py

@@ -0,0 +1,6 @@
+"""Postgres backend extension for SimpleBroker."""
+
+from .plugin import get_backend_plugin
+from .runner import PostgresRunner
+
+__all__ = ["PostgresRunner", "get_backend_plugin"]

simplebroker_pg-1.0.0/simplebroker_pg/_constants.py

@@ -0,0 +1,3 @@
+"""Constants for the Postgres SimpleBroker backend."""
+
+POSTGRES_SCHEMA_VERSION = 5

simplebroker_pg-1.0.0/simplebroker_pg/_identifiers.py

@@ -0,0 +1,18 @@
+"""Stable identifiers for Postgres advisory locks and notification channels."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def stable_lock_key(*parts: str) -> int:
+    """Return a stable signed 64-bit advisory lock key."""
+    payload = "\x1f".join(parts).encode("utf-8")
+    digest = hashlib.blake2b(payload, digest_size=8).digest()
+    return int.from_bytes(digest, byteorder="big", signed=True)
+
+
+def activity_channel_name(schema: str) -> str:
+    """Return a stable, identifier-safe LISTEN/NOTIFY channel name."""
+    digest = hashlib.md5(schema.encode("utf-8"), usedforsecurity=False).hexdigest()
+    return f"simplebroker_{digest[:24]}"

simplebroker_pg-1.0.0/simplebroker_pg/_sql.py

@@ -0,0 +1,269 @@
+"""Postgres SQL namespace for SimpleBroker."""
+
+from __future__ import annotations
+
+from simplebroker._sql import RetrieveOperation, RetrieveQuerySpec
+
+CHECK_PENDING_MESSAGES = """
+SELECT EXISTS(
+    SELECT 1
+    FROM messages
+    WHERE queue = ? AND claimed = FALSE
+    LIMIT 1
+)
+"""
+
+CHECK_PENDING_MESSAGES_SINCE = """
+SELECT EXISTS(
+    SELECT 1
+    FROM messages
+    WHERE queue = ? AND claimed = FALSE AND ts > ?
+    LIMIT 1
+)
+"""
+
+CHECK_QUEUE_EXISTS = """
+SELECT EXISTS(
+    SELECT 1
+    FROM messages
+    WHERE queue = ?
+    LIMIT 1
+)
+"""
+
+COUNT_CLAIMED_MESSAGES = "SELECT COUNT(*) FROM messages WHERE claimed = TRUE"
+DELETE_ALIAS = "DELETE FROM aliases WHERE alias = ?"
+DELETE_ALL_MESSAGES_COUNT = """
+WITH deleted AS (
+    DELETE FROM messages
+    RETURNING 1
+)
+SELECT COUNT(*) FROM deleted
+"""
+DELETE_QUEUE_MESSAGES_COUNT = """
+WITH deleted AS (
+    DELETE FROM messages
+    WHERE queue = ?
+    RETURNING 1
+)
+SELECT COUNT(*) FROM deleted
+"""
+GET_ALIAS_VERSION = "SELECT alias_version FROM meta WHERE singleton = TRUE"
+GET_DISTINCT_QUEUES = "SELECT DISTINCT queue FROM messages ORDER BY queue"
+GET_LAST_TS = "SELECT last_ts FROM meta WHERE singleton = TRUE"
+GET_MAX_MESSAGE_TS = "SELECT COALESCE(MAX(ts), 0) FROM messages"
+GET_OVERALL_STATS = """
+SELECT
+    COALESCE(SUM(CASE WHEN claimed THEN 1 ELSE 0 END), 0),
+    COUNT(*)
+FROM messages
+"""
+GET_QUEUE_STATS = """
+SELECT
+    queue,
+    SUM(CASE WHEN NOT claimed THEN 1 ELSE 0 END) AS unclaimed_count,
+    COUNT(*) AS total_count
+FROM messages
+GROUP BY queue
+ORDER BY queue
+"""
+GET_TOTAL_MESSAGE_COUNT = "SELECT COUNT(*) FROM messages"
+GET_VACUUM_STATS = """
+SELECT
+    COALESCE(SUM(CASE WHEN claimed THEN 1 ELSE 0 END), 0),
+    COUNT(*)
+FROM messages
+"""
+INSERT_ALIAS = "INSERT INTO aliases (alias, target) VALUES (?, ?)"
+INSERT_MESSAGE = """
+WITH inserted AS (
+    INSERT INTO messages (queue, body, ts)
+    VALUES (?, ?, ?)
+    RETURNING queue
+)
+SELECT pg_notify(
+    'simplebroker_' || substr(md5(current_schema()), 1, 24),
+    queue
+)
+FROM inserted
+"""
+LIST_QUEUES_UNCLAIMED = """
+SELECT queue, COUNT(*)
+FROM messages
+WHERE claimed = FALSE
+GROUP BY queue
+ORDER BY queue
+"""
+SELECT_ALIASES = "SELECT alias, target FROM aliases ORDER BY alias"
+SELECT_ALIASES_FOR_TARGET = """
+SELECT alias
+FROM aliases
+WHERE target = ?
+ORDER BY alias
+"""
+SELECT_META_ALL = """
+SELECT key, value
+FROM (
+    SELECT 'alias_version'::TEXT AS key, alias_version::TEXT AS value
+    FROM meta
+    WHERE singleton = TRUE
+    UNION ALL
+    SELECT 'last_ts'::TEXT AS key, last_ts::TEXT AS value
+    FROM meta
+    WHERE singleton = TRUE
+    UNION ALL
+    SELECT 'magic'::TEXT AS key, magic AS value
+    FROM meta
+    WHERE singleton = TRUE
+    UNION ALL
+    SELECT 'schema_version'::TEXT AS key, schema_version::TEXT AS value
+    FROM meta
+    WHERE singleton = TRUE
+) AS meta_items
+ORDER BY key
+"""
+UPDATE_ALIAS_VERSION = """
+UPDATE meta
+SET alias_version = ?
+WHERE singleton = TRUE
+"""
+UPDATE_LAST_TS = "UPDATE meta SET last_ts = ? WHERE singleton = TRUE"
+
+DELETE_CLAIMED_BATCH_COUNT = """
+WITH deleted AS (
+    DELETE FROM messages
+    WHERE order_id IN (
+        SELECT order_id
+        FROM messages
+        WHERE claimed = TRUE
+        ORDER BY order_id
+        LIMIT ?
+    )
+    RETURNING 1
+)
+SELECT COUNT(*) FROM deleted
+"""
+
+DATABASE_SIZE_BYTES = """
+SELECT COALESCE(SUM(pg_total_relation_size(c.oid)), 0)
+FROM pg_class AS c
+JOIN pg_namespace AS n
+  ON n.oid = c.relnamespace
+WHERE n.nspname = ?
+  AND c.relname IN ('messages', 'meta', 'aliases')
+"""
+
+LOCK_BROADCAST_SCOPE = "LOCK TABLE messages IN SHARE ROW EXCLUSIVE MODE"
+
+COMPACT_TABLE_MESSAGES = "VACUUM (ANALYZE) messages"
+COMPACT_TABLE_META = "VACUUM (ANALYZE) meta"
+COMPACT_TABLE_ALIASES = "VACUUM (ANALYZE) aliases"
+
+
+def _build_where_clause(spec: RetrieveQuerySpec) -> tuple[list[str], list[object]]:
+    """Build Postgres WHERE conditions and parameters for retrieve operations."""
+    if spec.exact_timestamp is not None:
+        where_conditions = ["ts = ?", "queue = ?"]
+        params: list[object] = [spec.exact_timestamp, spec.queue]
+        if spec.require_unclaimed:
+            where_conditions.append("claimed = FALSE")
+        return where_conditions, params
+
+    where_conditions = ["queue = ?"]
+    params = [spec.queue]
+    if spec.require_unclaimed:
+        where_conditions.append("claimed = FALSE")
+    if spec.since_timestamp is not None:
+        where_conditions.append("ts > ?")
+        params.append(spec.since_timestamp)
+    return where_conditions, params
+
+
+def build_retrieve_query(
+    operation: RetrieveOperation,
+    spec: RetrieveQuerySpec,
+) -> tuple[str, tuple[object, ...]]:
+    """Build a Postgres retrieve query and its parameter tuple."""
+    where_conditions, params = _build_where_clause(spec)
+    where_clause = " AND ".join(where_conditions)
+
+    if operation == "peek":
+        return (
+            f"""
+            SELECT body, ts
+            FROM messages
+            WHERE {where_clause}
+            ORDER BY order_id
+            LIMIT ?
+            OFFSET ?
+            """,
+            tuple(params + [spec.limit, spec.offset]),
+        )
+
+    if operation == "claim":
+        return (
+            f"""
+            WITH selected AS (
+                SELECT order_id
+                FROM messages
+                WHERE {where_clause}
+                ORDER BY order_id
+                LIMIT ?
+            ),
+            updated AS (
+                UPDATE messages
+                SET claimed = TRUE
+                WHERE order_id IN (SELECT order_id FROM selected)
+                RETURNING order_id, body, ts
+            )
+            SELECT updated.body, updated.ts
+            FROM updated
+            JOIN selected
+              ON selected.order_id = updated.order_id
+            ORDER BY selected.order_id
+            """,
+            tuple(params + [spec.limit]),
+        )
+
+    if operation == "move":
+        if spec.target_queue is None:
+            raise ValueError("Move retrieve query requires target_queue")
+        return (
+            f"""
+            WITH target_queue AS (
+                SELECT ? AS queue_name
+            ),
+            selected AS (
+                SELECT order_id
+                FROM messages
+                WHERE {where_clause}
+                ORDER BY order_id
+                LIMIT ?
+            ),
+            updated AS (
+                UPDATE messages
+                SET queue = (SELECT queue_name FROM target_queue),
+                    claimed = FALSE
+                WHERE order_id IN (SELECT order_id FROM selected)
+                RETURNING order_id, body, ts
+            ),
+            notified AS (
+                SELECT pg_notify(
+                    'simplebroker_' || substr(md5(current_schema()), 1, 24),
+                    (SELECT queue_name FROM target_queue)
+                )
+                FROM updated
+                LIMIT 1
+            )
+            SELECT updated.body, updated.ts
+            FROM updated
+            JOIN selected
+              ON selected.order_id = updated.order_id
+            LEFT JOIN notified
+              ON TRUE
+            ORDER BY selected.order_id
+            """,
+            tuple([spec.target_queue] + params + [spec.limit]),
+        )
+
+    raise ValueError(f"Unsupported retrieve operation: {operation}")