watchd will help services maintain recoverable, verifiably fresh projections of selected PostgreSQL state.
It is deliberately not a task queue or a general-purpose event log. Its intended contract is that a client either knows its projection is complete through a source cursor, or it is explicitly stale and resynchronizes from the source of truth.
watchd is intended to work well in cloud-native environments. Pod restarts, rolling deployments, horizontal scaling, node maintenance, and short network interruptions are normal in Kubernetes; each can make a LISTEN/NOTIFY-based cache miss an update while it is disconnected.
Applications running in pods can use the Go SDK to maintain a local projection of selected PostgreSQL state. When a pod starts or reconnects, it resumes from its last cursor when possible, or receives an explicit resync instruction and rebuilds from PostgreSQL. A pod should serve data as fresh only after it has received a progress statement for its watched scope.
The initial version will run as a normal service deployed alongside applications. Kubernetes-specific packaging, dashboards, and an optional operator are follow-on work, not prerequisites for the core correctness model.
watchd is pre-alpha. The v0 contract, local PostgreSQL logical-replication environment, resilient transaction reader, and gap-free bootstrap handoff are in place. Bootstrap creates a new persistent slot with an exported PostgreSQL snapshot, reads a validated projection scope at that snapshot, and returns the matching cursor; the reader then emits only committed transaction batches, acknowledges only locally accepted batches, and reconnects after transient connection loss without recreating a missing slot. The watch runtime, network API, SDK, and production release are not implemented. APIs and configuration may change without compatibility guarantees.
Start the local PostgreSQL source with:
make postgres-upIt listens on 127.0.0.1:54329 and is configured for logical replication. See the local source guide for credentials and reset instructions.
api/— versioned public API contractscmd/— service and CLI entry pointsinternal/— implementation packagessdk/go/— public Go clientdocs/— product and correctness documentationdeploy/— deployment assetstests/— integration and fault-test suitesexamples/— runnable reference setups
See the roadmap and the v0 semantics contract.
Contributions are welcome. Start with the architecture tour, read CONTRIBUTING.md, and choose a scoped GitHub issue. Every commit must be signed off under the DCO and reference an issue.
The project is licensed under Apache-2.0. See SECURITY.md for private vulnerability reporting and SUPPORT.md for current support expectations.