feat: create pgbackrest stanza during WAL archiving when missing - #121
Merged
Agalin merged 3 commits intoAug 12, 2026
Merged
Conversation
melancholictheory
force-pushed
the
feat/wal-stanza-bootstrap
branch
from
July 30, 2026 06:26
019a5b7 to
fb5437a
Compare
Stanza creation previously ran only inside the Backup RPC, so on a fresh cluster (or after a major upgrade changes the repository path) WAL archiving stayed broken until the first backup happened to run: archive-push kept failing with "has a stanza-create been performed?", and a rejoining replica could hang on archive recovery. The WAL archive path now inspects the "pgbackrest info" status and, when the stanza is missing (status code 1), runs the existing idempotent CreatePgbackrestStanza before archive-push. This executes on the primary as soon as its sidecar is up and relies on PostgreSQL's own archive_command retry, so archiving comes up without waiting for a backup. Creation is best-effort and only triggers when the stanza is genuinely absent, so it does not contend with a running backup for the stanza lock. The stanza check lives entirely in the WAL archive path and does not touch CheckWalArchiveDestination, which the restore path uses for a read-only check. Refs operasoftware#60, operasoftware#18, operasoftware#42. Signed-off-by: Vasiliy Fakunin <61789920+melancholictheory@users.noreply.github.com>
melancholictheory
force-pushed
the
feat/wal-stanza-bootstrap
branch
from
July 30, 2026 06:26
fb5437a to
daac990
Compare
melancholictheory
pushed a commit
to melancholictheory/cnpg-plugin-pgbackrest
that referenced
this pull request
Aug 3, 2026
Covers lazy stanza creation on first WAL archive, successful archiving before any backup, then backup and restore. Log assertion matches operasoftware#121. Co-authored-by: Cursor <cursoragent@cursor.com>
Covers lazy stanza creation on first WAL archive, successful archiving before any backup, then backup and restore. Log assertion matches operasoftware#121. Co-authored-by: Cursor <cursoragent@cursor.com> Signed-off-by: Vasiliy Fakunin <61789920+melancholictheory@users.noreply.github.com>
melancholictheory
force-pushed
the
feat/wal-stanza-bootstrap
branch
2 times, most recently
from
August 3, 2026 21:13
da130a7 to
1e9ede0
Compare
Agalin
requested changes
Aug 5, 2026
Agalin
left a comment
Agalin
left a comment
Collaborator
There was a problem hiding this comment.
I'm fine with the default change although we'll need to mark it as a breaking change.
Add a createStanza policy to the Archive configuration that controls when the pgBackRest stanza is created: - OnFirstArchive (default): create it on the first WAL archive if missing, so archiving works without a prior backup. - OnBackup: create it only when a backup runs (the previous behavior). - Disabled: never create it automatically; the stanza is managed out of band. The WAL archive path creates the stanza only under OnFirstArchive; the backup path creates it unless Disabled. This keeps archiving working out of the box while giving a backward-compatible opt-out, as discussed in operasoftware#60. The WAL archive handler relies on CheckWalArchiveDestination returning a typed ErrStanzaMissing rather than inspecting the info catalog itself, which keeps the restore path's intent clear. The e2e coverage exercises both the default and the OnBackup policy. BREAKING CHANGE: WAL archiving now creates the pgBackRest stanza on the first WAL archive by default (createStanza=OnFirstArchive) instead of only during the first backup. Set createStanza=OnBackup to keep the previous behavior. Refs operasoftware#60. Signed-off-by: Vasiliy Fakunin <61789920+melancholictheory@users.noreply.github.com>
melancholictheory
force-pushed
the
feat/wal-stanza-bootstrap
branch
from
August 5, 2026 17:35
1e9ede0 to
090af96
Compare
Contributor
Author
|
Addressed all four in
|
Agalin
approved these changes
Aug 5, 2026
Agalin
left a comment
Agalin
left a comment
Collaborator
There was a problem hiding this comment.
Looks good to me. If CI passes the only thing left wikk be marking as ready. 🙂
melancholictheory
marked this pull request as ready for review
August 5, 2026 19:37
Agalin
pushed a commit
that referenced
this pull request
Aug 12, 2026
Covers lazy stanza creation on first WAL archive, successful archiving before any backup, then backup and restore. Log assertion matches #121. Co-authored-by: Cursor <cursoragent@cursor.com> Signed-off-by: Vasiliy Fakunin <61789920+melancholictheory@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Create the pgBackRest stanza from the WAL archive path when it does not exist yet, so continuous WAL archiving can start without waiting for the first backup.
Why
Today
pgbackrest stanza-createruns only inside the Backup RPC (internal/cnpgi/instance/backup.go). The WAL archive path only checks whether the stanza exists (pgbackrest info) and never creates it. So on a fresh cluster, or after a major upgrade changes the repository path,archive-pushkeeps failing withHINT: has a stanza-create been performed?until a backup happens to run. Until then continuous archiving stays down, and a rejoining replica can hang on archive recovery.This is the known limitation discussed in #60, and it is also what #18 runs into when an immediate backup races the plugin becoming ready on the primary.
How
CheckWalArchiveDestinationnow returns the parsedpgbackrest infocatalog instead of only an error, so callers can inspect the stanza status. The singleinfocall still doubles as the repository reachability check.status.code, with aStanzaMissing()helper (code1= "missing stanza path").Archivehandler, when the stanza is missing, it runs the existing idempotentCreatePgbackrestStanzabeforearchive-push.Why this placement:
archive_commanduntil it succeeds, so no extra retry loop is added.Testing
go build ./...andgo vet ./...are clean.StanzaMissing()(status codes 0 and 1); existing catalog and archiver tests pass.Refs #60, #18, #42.