pgdispatch 0.1.0__py3-none-any.whl

pgdispatch/errors.py

@@ -0,0 +1,43 @@
+"""Exceptions raised by pgdispatch.
+
+Every exception derives from :class:`PgDispatchError`, so callers can catch the
+whole family with a single ``except`` clause.
+"""
+
+from __future__ import annotations
+
+
+class PgDispatchError(Exception):
+    """Base class for all pgdispatch errors."""
+
+
+class ConfigurationError(PgDispatchError):
+    """The library is configured inconsistently or an optional dependency is missing."""
+
+
+class ValidationError(PgDispatchError, ValueError):
+    """An argument passed to the public API is invalid."""
+
+
+class PayloadTooLargeError(ValidationError):
+    """The serialized event payload exceeds ``max_payload_bytes``."""
+
+
+class UnsafeURLError(ValidationError):
+    """An endpoint URL is not allowed, e.g. it points to a private network."""
+
+
+class NotFoundError(PgDispatchError, LookupError):
+    """The requested endpoint, event or delivery does not exist (or is not visible to the owner)."""
+
+
+class ConflictError(PgDispatchError):
+    """The operation cannot be applied in the object's current state."""
+
+
+class InvalidSignatureError(PgDispatchError):
+    """A webhook signature could not be verified."""
+
+
+class MigrationError(PgDispatchError):
+    """The database schema could not be migrated."""

pgdispatch/fastapi/__init__.py

@@ -0,0 +1,23 @@
+"""FastAPI integration: a ready-made API for your customers to manage their endpoints.
+
+::
+
+    from fastapi import Depends, FastAPI
+    from pgdispatch.fastapi import router
+
+    async def current_merchant(user: User = Depends(current_user)) -> str:
+        return user.merchant_id  # every request is scoped to this owner
+
+    app = FastAPI(lifespan=webhooks.lifespan())
+    app.include_router(router(webhooks, owner=current_merchant), prefix="/webhooks")
+
+The ``owner`` dependency is mandatory: it authenticates the caller and returns
+the owner id that every operation is restricted to, so one customer can never
+see or touch another customer's endpoints.
+"""
+
+from __future__ import annotations
+
+from pgdispatch.fastapi.router import router
+
+__all__ = ["router"]

pgdispatch/fastapi/router.py

@@ -0,0 +1,243 @@
+"""The endpoint-management router. See :mod:`pgdispatch.fastapi`."""
+
+# FastAPI inspects annotations at runtime, and the route handlers below are
+# closures over the ``owner`` dependency, so annotations must stay eager here.
+
+import uuid
+from collections.abc import Awaitable, Callable, Iterator, Sequence
+from contextlib import contextmanager
+from datetime import datetime, timedelta
+from typing import Any
+
+try:
+    from fastapi import APIRouter, Depends, HTTPException, Query, status
+except ImportError as exc:  # pragma: no cover - depends on the environment
+    msg = 'pgdispatch.fastapi requires FastAPI: pip install "pgdispatch[fastapi]"'
+    raise ImportError(msg) from exc
+from pydantic import BaseModel, ConfigDict, Field
+
+from pgdispatch.client import Webhooks
+from pgdispatch.errors import ConflictError, NotFoundError, ValidationError
+from pgdispatch.models import CircuitState, DeliveryStatus
+
+__all__ = ["router"]
+
+# Starlette renamed the 422 constant; the number is stable across versions.
+_UNPROCESSABLE = 422
+
+OwnerDependency = Callable[..., Awaitable[str | None] | str | None]
+
+
+class EndpointCreate(BaseModel):
+    url: str = Field(examples=["https://shop.example.com/webhooks"])
+    event_types: list[str] = Field(default=["*"], examples=[["order.*", "payment.paid"]])
+    description: str | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+    rate_limit_rps: float | None = Field(default=None, gt=0)
+
+
+class EndpointUpdate(BaseModel):
+    """Only the fields present in the request are changed."""
+
+    url: str | None = None
+    event_types: list[str] | None = None
+    description: str | None = None
+    headers: dict[str, str] | None = None
+    rate_limit_rps: float | None = Field(default=None, gt=0)
+
+
+class EndpointOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    url: str
+    description: str | None
+    event_types: list[str]
+    headers: dict[str, str]
+    rate_limit_rps: float | None
+    is_enabled: bool
+    disabled_reason: str | None
+    circuit_state: CircuitState
+    created_at: datetime
+    updated_at: datetime
+
+
+class EndpointWithSecret(EndpointOut):
+    secret: str = Field(description="The signing secret. Store it now; it is shown only once.")
+
+
+class SecretOut(BaseModel):
+    secret: str
+
+
+class RotateSecret(BaseModel):
+    grace_period_seconds: int = Field(default=24 * 3600, ge=0, le=7 * 24 * 3600)
+
+
+class TestEventOut(BaseModel):
+    event_id: uuid.UUID
+
+
+class AttemptOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    attempt_number: int
+    response_status: int | None
+    response_body: str | None
+    duration_ms: int | None
+    error: str | None
+    created_at: datetime
+
+
+class DeliveryOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    event_id: uuid.UUID
+    endpoint_id: uuid.UUID
+    event_type: str
+    status: DeliveryStatus
+    attempt_count: int
+    next_attempt_at: datetime
+    last_status_code: int | None
+    last_error: str | None
+    created_at: datetime
+    finished_at: datetime | None
+
+
+class DeliveryDetail(DeliveryOut):
+    attempts: list[AttemptOut]
+
+
+def router(
+    webhooks: Webhooks,
+    *,
+    owner: OwnerDependency,
+    tags: Sequence[str] = ("webhooks",),
+) -> APIRouter:
+    """Build an :class:`~fastapi.APIRouter` for managing endpoints and deliveries.
+
+    :param owner: A FastAPI dependency that authenticates the request and
+        returns the owner id (tenant) to scope every operation to.
+    """
+    api = APIRouter(tags=list(tags))
+    owner_id = Depends(owner)
+
+    @api.get("/endpoints", response_model=list[EndpointOut])
+    async def list_endpoints(
+        after: uuid.UUID | None = None,
+        limit: int = Query(default=100, ge=1, le=1000),
+        owner_id: str | None = owner_id,
+    ) -> Any:
+        return await webhooks.endpoints.list(owner_id=owner_id, after=after, limit=limit)
+
+    @api.post("/endpoints", response_model=EndpointWithSecret, status_code=status.HTTP_201_CREATED)
+    async def create_endpoint(body: EndpointCreate, owner_id: str | None = owner_id) -> Any:
+        with _errors():
+            return await webhooks.endpoints.create(
+                body.url,
+                event_types=body.event_types,
+                owner_id=owner_id,
+                description=body.description,
+                headers=body.headers,
+                rate_limit_rps=body.rate_limit_rps,
+            )
+
+    @api.get("/endpoints/{endpoint_id}", response_model=EndpointOut)
+    async def get_endpoint(endpoint_id: uuid.UUID, owner_id: str | None = owner_id) -> Any:
+        with _errors():
+            return await webhooks.endpoints.get(endpoint_id, owner_id=owner_id)
+
+    @api.patch("/endpoints/{endpoint_id}", response_model=EndpointOut)
+    async def update_endpoint(
+        endpoint_id: uuid.UUID, body: EndpointUpdate, owner_id: str | None = owner_id
+    ) -> Any:
+        changes = body.model_dump(exclude_unset=True)
+        if changes.get("url", "") is None or changes.get("event_types", []) is None:
+            raise HTTPException(_UNPROCESSABLE, "url and event_types cannot be null")
+        if "headers" in changes and changes["headers"] is None:
+            changes["headers"] = {}
+        with _errors():
+            return await webhooks.endpoints.update(endpoint_id, owner_id=owner_id, **changes)
+
+    @api.delete("/endpoints/{endpoint_id}", status_code=status.HTTP_204_NO_CONTENT)
+    async def delete_endpoint(endpoint_id: uuid.UUID, owner_id: str | None = owner_id) -> None:
+        with _errors():
+            await webhooks.endpoints.delete(endpoint_id, owner_id=owner_id)
+
+    @api.post("/endpoints/{endpoint_id}/enable", response_model=EndpointOut)
+    async def enable_endpoint(endpoint_id: uuid.UUID, owner_id: str | None = owner_id) -> Any:
+        with _errors():
+            return await webhooks.endpoints.enable(endpoint_id, owner_id=owner_id)
+
+    @api.post("/endpoints/{endpoint_id}/disable", response_model=EndpointOut)
+    async def disable_endpoint(endpoint_id: uuid.UUID, owner_id: str | None = owner_id) -> Any:
+        with _errors():
+            return await webhooks.endpoints.disable(
+                endpoint_id, reason="disabled by the owner", owner_id=owner_id
+            )
+
+    @api.get("/endpoints/{endpoint_id}/secret", response_model=SecretOut)
+    async def get_secret(endpoint_id: uuid.UUID, owner_id: str | None = owner_id) -> Any:
+        with _errors():
+            return {"secret": await webhooks.endpoints.get_secret(endpoint_id, owner_id=owner_id)}
+
+    @api.post("/endpoints/{endpoint_id}/rotate-secret", response_model=EndpointWithSecret)
+    async def rotate_secret(
+        endpoint_id: uuid.UUID, body: RotateSecret | None = None, owner_id: str | None = owner_id
+    ) -> Any:
+        grace = timedelta(seconds=(body or RotateSecret()).grace_period_seconds)
+        with _errors():
+            return await webhooks.endpoints.rotate_secret(
+                endpoint_id, grace_period=grace, owner_id=owner_id
+            )
+
+    @api.post("/endpoints/{endpoint_id}/test", response_model=TestEventOut, status_code=202)
+    async def send_test(endpoint_id: uuid.UUID, owner_id: str | None = owner_id) -> Any:
+        with _errors():
+            result = await webhooks.endpoints.send_test(endpoint_id, owner_id=owner_id)
+        return {"event_id": result.event_id}
+
+    @api.get("/deliveries", response_model=list[DeliveryOut])
+    async def list_deliveries(
+        endpoint_id: uuid.UUID | None = None,
+        status_filter: DeliveryStatus | None = Query(default=None, alias="status"),
+        before: int | None = None,
+        limit: int = Query(default=50, ge=1, le=1000),
+        owner_id: str | None = owner_id,
+    ) -> Any:
+        return await webhooks.deliveries.list(
+            endpoint_id=endpoint_id,
+            status=status_filter,
+            before=before,
+            limit=limit,
+            owner_id=owner_id,
+        )
+
+    @api.get("/deliveries/{delivery_id}", response_model=DeliveryDetail)
+    async def get_delivery(delivery_id: int, owner_id: str | None = owner_id) -> Any:
+        with _errors():
+            delivery = await webhooks.deliveries.get(delivery_id, owner_id=owner_id)
+            attempts = await webhooks.deliveries.attempts(delivery_id, owner_id=owner_id)
+        detail = DeliveryOut.model_validate(delivery).model_dump()
+        return {**detail, "attempts": [AttemptOut.model_validate(a) for a in attempts]}
+
+    @api.post("/deliveries/{delivery_id}/retry", response_model=DeliveryOut)
+    async def retry_delivery(delivery_id: int, owner_id: str | None = owner_id) -> Any:
+        with _errors():
+            return await webhooks.deliveries.retry(delivery_id, owner_id=owner_id)
+
+    return api
+
+
+@contextmanager
+def _errors() -> Iterator[None]:
+    """Translate library errors into HTTP responses."""
+    try:
+        yield
+    except NotFoundError as exc:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, str(exc)) from exc
+    except ConflictError as exc:
+        raise HTTPException(status.HTTP_409_CONFLICT, str(exc)) from exc
+    except ValidationError as exc:
+        raise HTTPException(_UNPROCESSABLE, str(exc)) from exc

pgdispatch/hooks.py

@@ -0,0 +1,80 @@
+"""Callbacks that let the application react to delivery problems.
+
+Register them with decorators::
+
+    @webhooks.hooks.on_endpoint_disabled
+    async def notify_customer(endpoint: Endpoint, reason: str) -> None:
+        await mailer.send(endpoint.owner_id, f"Your webhook endpoint was disabled: {reason}")
+
+Callbacks may be plain functions or coroutines. They run in the worker after
+the state change is committed; an exception in a callback is logged and never
+affects delivery.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+from pgdispatch.models import Delivery, Endpoint
+
+__all__ = ["Hooks"]
+
+logger = logging.getLogger("pgdispatch.hooks")
+
+DeliveryFailedHook = Callable[[Delivery], Awaitable[None] | None]
+EndpointDisabledHook = Callable[[Endpoint, str], Awaitable[None] | None]
+CircuitOpenedHook = Callable[[Endpoint], Awaitable[None] | None]
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class Hooks:
+    """Registry of application callbacks."""
+
+    def __init__(self) -> None:
+        self._delivery_failed: list[DeliveryFailedHook] = []
+        self._endpoint_disabled: list[EndpointDisabledHook] = []
+        self._circuit_opened: list[CircuitOpenedHook] = []
+
+    def on_delivery_failed(self, callback: F) -> F:
+        """Called with the :class:`Delivery` when its last attempt fails."""
+        self._delivery_failed.append(callback)
+        return callback
+
+    def on_endpoint_disabled(self, callback: F) -> F:
+        """Called with the :class:`Endpoint` and the reason when the worker disables it."""
+        self._endpoint_disabled.append(callback)
+        return callback
+
+    def on_circuit_opened(self, callback: F) -> F:
+        """Called with the :class:`Endpoint` when its circuit breaker opens."""
+        self._circuit_opened.append(callback)
+        return callback
+
+    async def delivery_failed(self, delivery: Delivery) -> None:
+        for callback in self._delivery_failed:
+            await _call(callback, delivery)
+
+    async def endpoint_disabled(self, endpoint: Endpoint, reason: str) -> None:
+        for callback in self._endpoint_disabled:
+            await _call(callback, endpoint, reason)
+
+    async def circuit_opened(self, endpoint: Endpoint) -> None:
+        for callback in self._circuit_opened:
+            await _call(callback, endpoint)
+
+
+async def _call(callback: Callable[..., Any], *args: Any) -> None:
+    try:
+        result = callback(*args)
+        if inspect.isawaitable(result):
+            await result
+    except Exception:
+        logger.exception("pgdispatch hook %s raised an exception", _name(callback))
+
+
+def _name(callback: Callable[..., Any]) -> str:
+    return getattr(callback, "__qualname__", repr(callback))

pgdispatch/metrics.py

@@ -0,0 +1,80 @@
+"""Prometheus metrics.
+
+Metrics are registered in ``prometheus_client``'s default registry, so they
+appear on your application's existing ``/metrics`` endpoint; the standalone
+worker can expose them with ``--metrics-port``. Endpoint ids are deliberately
+not used as labels: thousands of endpoints would explode cardinality. Use the
+CLI or the tables for per-endpoint details.
+"""
+
+from __future__ import annotations
+
+from prometheus_client import REGISTRY, CollectorRegistry, Counter, Gauge, Histogram
+
+__all__ = ["Metrics", "get_metrics"]
+
+_DURATION_BUCKETS = (0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 15.0, 30.0)
+_BATCH_BUCKETS = (1, 2, 5, 10, 25, 50, 100, 250, 500, 1000)
+
+
+class Metrics:
+    """The metric objects of one registry."""
+
+    def __init__(self, registry: CollectorRegistry) -> None:
+        self.events_published = Counter(
+            "pgdispatch_events_published",
+            "Events published, by event type.",
+            ["event_type"],
+            registry=registry,
+        )
+        self.delivery_attempts = Counter(
+            "pgdispatch_delivery_attempts",
+            "HTTP delivery attempts, by result (success, http_error, timeout, network).",
+            ["result"],
+            registry=registry,
+        )
+        self.delivery_duration = Histogram(
+            "pgdispatch_delivery_duration_seconds",
+            "Duration of HTTP delivery attempts.",
+            ["result"],
+            buckets=_DURATION_BUCKETS,
+            registry=registry,
+        )
+        self.deliveries_failed = Counter(
+            "pgdispatch_deliveries_failed",
+            "Deliveries that exhausted all their attempts.",
+            registry=registry,
+        )
+        self.deliveries_pending = Gauge(
+            "pgdispatch_deliveries_pending",
+            "Deliveries waiting for an attempt on enabled endpoints.",
+            registry=registry,
+        )
+        self.oldest_pending_age = Gauge(
+            "pgdispatch_oldest_pending_age_seconds",
+            "How long the most overdue delivery has been waiting (delivery lag).",
+            registry=registry,
+        )
+        self.endpoints_circuit_open = Gauge(
+            "pgdispatch_endpoints_circuit_open",
+            "Enabled endpoints whose circuit breaker is open or half-open.",
+            registry=registry,
+        )
+        self.worker_batch_size = Histogram(
+            "pgdispatch_worker_batch_size",
+            "Deliveries claimed per database round-trip.",
+            buckets=_BATCH_BUCKETS,
+            registry=registry,
+        )
+
+
+_instances: dict[int, Metrics] = {}
+
+
+def get_metrics(registry: CollectorRegistry | None = None) -> Metrics:
+    """Return the metrics bound to ``registry``, creating them on first use."""
+    registry = registry or REGISTRY
+    key = id(registry)
+    if key not in _instances:
+        _instances[key] = Metrics(registry)
+    return _instances[key]

pgdispatch/migrations/0001_initial.sql

@@ -0,0 +1,104 @@
+-- pgdispatch schema, version 1.
+--
+-- Statements end with a semicolon at the end of a line; the migrator splits on
+-- that, so keep function bodies and dollar quoting out of migrations.
+
+CREATE TABLE {schema}.endpoints (
+    id                   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    owner_id             text,
+    url                  text NOT NULL,
+    description          text,
+    event_types          text[] NOT NULL DEFAULT '{*}',
+    secrets              jsonb NOT NULL,
+    headers              jsonb NOT NULL DEFAULT '{}',
+    rate_limit_rps       double precision CHECK (rate_limit_rps > 0),
+    is_enabled           boolean NOT NULL DEFAULT true,
+    disabled_reason      text,
+    circuit_state        text NOT NULL DEFAULT 'closed'
+                         CHECK (circuit_state IN ('closed', 'open', 'half_open')),
+    consecutive_failures integer NOT NULL DEFAULT 0,
+    failing_since        timestamptz,
+    circuit_opened_at    timestamptz,
+    circuit_retry_at     timestamptz,
+    circuit_trips        integer NOT NULL DEFAULT 0,
+    created_at           timestamptz NOT NULL DEFAULT now(),
+    updated_at           timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX endpoints_owner_idx ON {schema}.endpoints (owner_id) WHERE is_enabled;
+
+CREATE INDEX endpoints_event_types_idx ON {schema}.endpoints USING gin (event_types) WHERE is_enabled;
+
+-- Workers look for tripped breakers whose cooldown has elapsed on every poll.
+CREATE INDEX endpoints_circuit_idx ON {schema}.endpoints (circuit_retry_at)
+    WHERE is_enabled AND circuit_state <> 'closed';
+
+CREATE TABLE {schema}.events (
+    id              uuid PRIMARY KEY,
+    event_type      text NOT NULL,
+    owner_id        text,
+    payload         jsonb NOT NULL,
+    idempotency_key text,
+    created_at      timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX events_idempotency_key_idx ON {schema}.events (idempotency_key)
+    WHERE idempotency_key IS NOT NULL;
+
+CREATE INDEX events_created_at_idx ON {schema}.events (created_at);
+
+CREATE TABLE {schema}.deliveries (
+    id               bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    event_id         uuid NOT NULL REFERENCES {schema}.events (id) ON DELETE CASCADE,
+    endpoint_id      uuid NOT NULL REFERENCES {schema}.endpoints (id) ON DELETE CASCADE,
+    ordering_key     text,
+    status           text NOT NULL DEFAULT 'pending'
+                     CHECK (status IN ('pending', 'in_flight', 'succeeded', 'failed', 'cancelled')),
+    attempt_count    integer NOT NULL DEFAULT 0,
+    -- attempt_count when the current retry round began; a manual retry starts
+    -- a new round with the full schedule while attempt numbers keep growing.
+    schedule_offset  integer NOT NULL DEFAULT 0,
+    next_attempt_at  timestamptz NOT NULL DEFAULT now(),
+    locked_until     timestamptz,
+    last_status_code integer,
+    last_error       text,
+    created_at       timestamptz NOT NULL DEFAULT now(),
+    updated_at       timestamptz NOT NULL DEFAULT now(),
+    finished_at      timestamptz
+);
+
+-- The hot path: workers claim due deliveries in next_attempt_at order.
+CREATE INDEX deliveries_due_idx ON {schema}.deliveries (next_attempt_at)
+    WHERE status IN ('pending', 'in_flight');
+
+-- Ordered delivery: "is there an earlier unfinished delivery with this key?"
+CREATE INDEX deliveries_ordering_idx ON {schema}.deliveries (endpoint_id, ordering_key, id)
+    WHERE status IN ('pending', 'in_flight') AND ordering_key IS NOT NULL;
+
+CREATE INDEX deliveries_endpoint_idx ON {schema}.deliveries (endpoint_id, id);
+
+CREATE INDEX deliveries_event_idx ON {schema}.deliveries (event_id);
+
+CREATE TABLE {schema}.attempts (
+    id              bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    delivery_id     bigint NOT NULL REFERENCES {schema}.deliveries (id) ON DELETE CASCADE,
+    attempt_number  integer NOT NULL,
+    request_headers jsonb,
+    response_status integer,
+    response_body   text,
+    duration_ms     integer,
+    error           text,
+    created_at      timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX attempts_delivery_idx ON {schema}.attempts (delivery_id);
+
+CREATE TABLE {schema}.workers (
+    id           uuid PRIMARY KEY,
+    hostname     text NOT NULL,
+    pid          integer NOT NULL,
+    version      text NOT NULL,
+    concurrency  integer NOT NULL,
+    started_at   timestamptz NOT NULL DEFAULT now(),
+    heartbeat_at timestamptz NOT NULL DEFAULT now()
+);

pgdispatch/migrations/__init__.py

@@ -0,0 +1,93 @@
+"""Versioned SQL migrations for the pgdispatch schema.
+
+Migrations are plain SQL files named ``NNNN_description.sql``. They are applied
+in order, each in the caller's transaction, and recorded in
+``{schema}.schema_migrations``. A transaction-scoped advisory lock makes
+concurrent ``migrate`` calls (several pods starting at once) safe.
+
+The same migrator powers ``pgdispatch migrate``, ``Webhooks.migrate()``, the
+Django app and the Alembic helper.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import cache
+from importlib import resources
+
+from pgdispatch.backends.base import Operation, Query
+
+__all__ = ["Migration", "drop_schema", "load_migrations", "migrate"]
+
+_FILE_NAME = re.compile(r"^(\d{4})_(\w+)\.sql$")
+_STATEMENT_END = re.compile(r";[ \t]*$", re.MULTILINE)
+
+
+@dataclass(frozen=True, slots=True)
+class Migration:
+    version: int
+    name: str
+    statements: tuple[str, ...]
+
+
+@cache
+def load_migrations() -> tuple[Migration, ...]:
+    """All migrations shipped with the package, oldest first."""
+    migrations = []
+    for entry in resources.files(__package__).iterdir():
+        match = _FILE_NAME.match(entry.name)
+        if match is None:
+            continue
+        migrations.append(
+            Migration(
+                version=int(match.group(1)),
+                name=match.group(2),
+                statements=_split_statements(entry.read_text(encoding="utf-8")),
+            )
+        )
+    return tuple(sorted(migrations, key=lambda migration: migration.version))
+
+
+def migrate(*, target: int | None = None) -> Operation[list[int]]:
+    """Apply pending migrations up to ``target`` (all by default); return the applied versions."""
+    yield Query("SELECT pg_advisory_xact_lock(hashtext('{schema}.migrate'))")
+    yield Query("CREATE SCHEMA IF NOT EXISTS {schema}")
+    yield Query(
+        """
+        CREATE TABLE IF NOT EXISTS {schema}.schema_migrations (
+            version    integer PRIMARY KEY,
+            name       text NOT NULL,
+            applied_at timestamptz NOT NULL DEFAULT now()
+        )
+        """
+    )
+    rows = yield Query("SELECT version FROM {schema}.schema_migrations")
+    applied = {row["version"] for row in rows}
+
+    newly_applied = []
+    for migration in load_migrations():
+        if migration.version in applied or (target is not None and migration.version > target):
+            continue
+        for statement in migration.statements:
+            yield Query(statement)
+        yield Query(
+            "INSERT INTO {schema}.schema_migrations (version, name) "
+            "VALUES (CAST(:version AS integer), CAST(:name AS text))",
+            {"version": migration.version, "name": migration.name},
+        )
+        newly_applied.append(migration.version)
+    return newly_applied
+
+
+def drop_schema() -> Operation[None]:
+    """Remove the schema with all data. Used by ``migrate zero`` in Django and by tests."""
+    yield Query("DROP SCHEMA IF EXISTS {schema} CASCADE")
+
+
+def _split_statements(sql: str) -> tuple[str, ...]:
+    without_comments = "\n".join(
+        line for line in sql.splitlines() if not line.lstrip().startswith("--")
+    )
+    parts = _STATEMENT_END.split(without_comments)
+    return tuple(part.strip() for part in parts if part.strip())