PG Change Feed — Python SDK

Official Python client library for PG Change Feed, a durable change feed system for PostgreSQL built on logical replication.

This package (pgchangefeed) lets a Python application consume PG Change Feed's delivery paths (HTTP API, gRPC stream, SSE stream, NATS full-content stream) without implementing the wire protocol itself — see LH-FA-SST-009 for the requirement this SDK fulfills.

Status

This package is at an early, pre-1.0 stage (0.x.y, ADR-0107, extended by ADR-0110). The current release provides the shared connection configuration (ClientOptions: server address and bearer token), a full HTTP API client surface (PgChangeFeedHttpClient): consumer registration/acknowledgement/position/removal, table enable/disable, status, table listing, retention, and reading changes — the nine SPEC-018 capabilities plus GET /changes (SPEC-022; each change carries origin, wal or backfill, read as wal when the response has none or carries JSON null, any other value passed through unchanged) —, the gRPC live-change-stream surface (PgChangeFeedGrpcClient): a server-streaming read of every committed change from connection time onward, fire-and-forget with no in-stream replay (SPEC-020, LH-FA-SST-008 boundary), the SSE live-change-stream surface (PgChangeFeedSseClient): the same fire-and-forget, no-replay stream over Server-Sent-Events instead of gRPC (SPEC-021, LH-FA-SST-008 boundary), and the NATS full-content stream surface (PgChangeFeedNatsStreamClient): the same message schema and fire-and-forget, no-replay boundary, delivered over a NATS subject namespace instead of HTTP, with connection-level (not per-call) token authentication (SPEC-024, LH-FA-SST-008 boundary) — the full four-way matrix beside C# (PgChangeFeed.Client) and Kotlin (pgchangefeed-kotlin).

If a surface you need isn't covered yet, the direct wire protocol remains fully usable on its own — no examples/python/ reference client exists yet (ADR-0107 §Kontext); see the examples reference clients for other languages in the main repository.

Installation

pip install pgchangefeed

Documentation

This README intentionally does not duplicate the wire protocol documentation. For the full picture — server setup, HTTP/gRPC/SSE/NATS delivery paths, and operational guidance — see the project README and the technical specification (spec/pflichtenheft.md, SPEC-018) in the main repository.

License

MIT — see LICENSE.