xataio/pgstream

Add phase visibility for `snapshot_and_replication` mode

Closed

#984 opened on Jul 9, 2026

View on GitHubContributor guide
 (1 comment) (1 reaction) (0 assignees)Go (66 forks)auto 404
good first issuereplicationsnapshot

Repository metrics

Stars
 (1,151 stars)
PR merge metrics
 (PR metrics pending)

Description

Problem

In snapshot_and_replication mode, there's no queryable way to tell whether the process is doing the initial snapshot or logical replication. The only signal is the ordered log sequence: initial snapshot enabled → snapshot generation completed → logical replication started.

pgstream status doesn't help: it's a static config/init check against Postgres (not the running process), and its Status struct has no phase field.

Proposal

Expose the current phase (snapshot | replication) as a queryable signal. Preferred: a /status endpoint on the existing health server (cmd/health_cmd.go:32), and OTel phase gauge, or enriching pgstream status to read slot active/confirmed_flush_lsn.

Requirements

  • Operator can tell snapshot vs streaming phase without reading logs.
  • Signal flips at logical replication started.
  • Works for all pgstream modes, not just snapshot_and_replication

Contributor guide

Research direction
Explore the existing health server at cmd/health cmd.go and the pgstream status command. Determine how to expose the current phase (snapshot or replication) via a /status endpoint or OTel phase gauge. Ensure the signal flips at logical replication started.
Tech stack
go
Domain
backenddatabase
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GoPostgreSQL
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
50