With WAL-G on PostgreSQL, what do backup-push and wal-push each upload, how is each triggered, and why do you need both?
answer
- a snapshot and a stream
- archive_command calls one of them
- cron or a sidecar calls the other
- pg_backup_stop waits for the archive
- the sentinel file comes last
basics
~20 sbackup-push uploads a base backup of the data directory on a schedule; wal-push uploads each finished WAL segment, called by archive_command. A base backup is only consistent with the WAL written during it, and PITR needs the WAL after it.
solid answer
~50 s`wal-g backup-push $PGDATA`, run from cron or a sidecar, calls `pg_backup_start`, streams the data directory as compressed tar parts, uploads `pg_control`, calls `pg_backup_stop`, uploads `backup_label` and `tablespace_map`, and writes a `_backup_stop_sentinel.json` last; `backup-list` only shows backups that have that sentinel. `wal-g wal-push %p` is the `archive_command` (with `archive_mode = on`, which needs a restart), so PostgreSQL ships every completed segment, and with `WALG_UPLOAD_CONCURRENCY` above 1 it also uploads other `.ready` segments in the background. You need both: the tar files were copied while the server kept writing, so they are only consistent once the WAL from backup start to stop is replayed, and any point after the backup needs the WAL after it. That is also why `backup-push` hangs at the end when `wal-push` is broken: `pg_backup_stop()` waits for the last segment to be archived.
code
ini · 4 lines# postgresql.conf
wal_level = replica
archive_mode = on # restart required
archive_command = 'wal-g wal-push %p' # reload is enoughgo deeper
Remember the split: backup-push is the scheduled snapshot of the data directory, wal-push is the archive_command PostgreSQL calls for every finished segment.
Explain why a base backup taken from a running server is only consistent with the WAL written during it, and walk through what backup-push does from pg_backup_start to the sentinel.
Diagnose a backup-push stuck at pg_backup_stop, explain wal-push's background upload of .ready files, and say how you monitor both streams in a container.
Decide between per-segment wal-push, the WAL-G 3 daemon and archive_library, weighing process cost per segment against operational simplicity.
## Two streams, one recovery A WAL-G setup for PostgreSQL ships two kinds of objects to the same prefix: | | `backup-push` | `wal-push` | |---|---|---| | Uploads | a **base backup**: the data directory as tar parts | one **WAL segment** (16 MB by default) or `.history` file | | Triggered by | you: cron, a sidecar, a scheduled job | PostgreSQL, through `archive_command` | | Frequency | daily or weekly | every time a segment fills or is switched | | Folder | `basebackups_005/` | `wal_005/` | | Alone it gives you | nothing consistent | nothing to start replay from | A base backup taken from a running server is **fuzzy**: pages change while they are read. It becomes consistent only when the WAL generated between backup start and backup stop is replayed on top of it. Every later recovery point needs the WAL after that. So the base backup is the starting snapshot and the archived WAL is the film that runs forward from it. ## wal-push: the continuous stream In `postgresql.conf`: - `archive_mode = on` (a postmaster setting, so it needs a restart) - `archive_command = 'wal-g wal-push %p'` (reloadable) - `wal_level` at its default `replica` or higher WAL-G-specific behaviour worth knowing: - With `WALG_UPLOAD_CONCURRENCY` at its default of 16, each `wal-push` also starts background uploads of other segments it finds marked `.ready` in `pg_wal/archive_status`, up to 15 at once and by default at most 32 files per run (`TOTAL_BG_UPLOADED_LIMIT`). When PostgreSQL later asks for one of those segments, `wal-push` sees it was already shipped and returns at once. - `.history` files are never overwritten; set `WALG_PREVENT_WAL_OVERWRITE` to apply the same check to segments, so a different file under an existing name fails the push instead of replacing it. What PostgreSQL does when the command fails (retries, keeps the segment in `pg_wal`) is the core archiving contract, not WAL-G's. ## backup-push: the periodic base backup `wal-g backup-push $PGDATA` runs as the postgres OS user on the database host (or in a sidecar that mounts the same data volume). It checks that the argument, `PGDATA` and the config all agree. The steps: 1. Calls `pg_backup_start(label, true)`: a non-exclusive backup that requests an immediate checkpoint. 2. Walks the data directory and streams it as compressed tar parts of about 1 GB (`WALG_TAR_SIZE_THRESHOLD`). The contents of `pg_wal`, `pg_replslot`, `pg_stat_tmp` and similar directories are left out, as are `postmaster.pid` and `standby.signal`. 3. Uploads `pg_control` separately. 4. Calls `pg_backup_stop()`, which by default **waits until the last WAL segment of the backup is archived**, then uploads the returned `backup_label` and `tablespace_map`. 5. Writes `<name>_backup_stop_sentinel.json`. A backup without its sentinel is not listed by `backup-list` and cannot be fetched by name or as `LATEST`. The backup name is `base_` plus the WAL file name of the start position, for example `base_000000010000000000000004`. Leaving out the data directory (`wal-g backup-push --pghost db1`) streams over the replication protocol instead: WAL-G can run on another host and as another user, but needs a replication connection, gets no parallel reads and cannot take delta backups. ## Running it in a container For a small startup's containerised PostgreSQL the usual shape is: 1. The PostgreSQL image includes the `wal-g` binary, and the server's environment or config file carries the `WALG_*` settings. 2. A scheduler (a cron sidecar or the orchestrator's job) runs `backup-push` against the shared data volume. 3. Monitoring checks both streams: the age of the newest backup in `backup-list`, and that WAL keeps arriving. Taking the base backup from a streaming standby instead of the primary keeps the read load off production. WAL-G then watches the standby's timeline: if the standby is promoted or its timeline changes while the backup runs, the data is uploaded but the backup is not finalised and `backup-push` exits with an error, logging what would be needed to finalise it by hand. Treat that as a failed backup and run a new one; finalising it manually is only for someone who understands exactly what the timeline switch did. Note also that on a standby, `pg_backup_stop()` waits for archiving only when `archive_mode = always`. ## Daemon mode in WAL-G 3 Forking the full `wal-g` binary once per segment means re-reading config and reconnecting to storage every time. WAL-G 3 adds `wal-g daemon /var/run/wal-g.sock`, a long-running process that does the pushes and fetches. `archive_command` then calls the small `walg-daemon-client` instead, and on PostgreSQL 15 and later the `walg_archive` extension can replace the shell command through `archive_library`. Each push through the daemon is limited by `WALG_DAEMON_WAL_UPLOAD_TIMEOUT` (default `60s`).
- wal-g backup-push uploads all its tar parts and then hangs. What is the likely cause?It is inside `pg_backup_stop()`, which by default waits until the backup's last WAL segment is archived. If `wal-push` is failing (credentials, environment, bucket policy) that never happens. Fix archiving first; `WALG_STOP_BACKUP_TIMEOUT` (no timeout by default) only turns the hang into an error, and a backup without its WAL is useless anyway.
- What does WAL-G's daemon mode change for archiving?`wal-g daemon <socket>` stays running, so config loading and the storage connection happen once instead of per segment. `archive_command` and `restore_command` call `walg-daemon-client <socket> wal-push %f` or `wal-fetch %f %p`; on PostgreSQL 15+ the `walg_archive` extension uses `archive_library` instead of a shell command. `WALG_DAEMON_WAL_UPLOAD_TIMEOUT` (60s) bounds each push.
- Why does WAL-G refuse to overwrite a .history file in storage?A `.history` file records where a timeline branched. Overwriting it with another cluster's file under the same name would corrupt recovery across timelines, so `wal-push` always checks first for `.history` files. `WALG_PREVENT_WAL_OVERWRITE` extends the same check to ordinary segments.
- Nightly backup-push alone lets you restore to any time of day
- wal-push should be scheduled from cron every few minutes
- A backup appears in backup-list as soon as its first tar part uploads
- The base backup tars already contain the WAL needed to make them consistent
- Setting archive_command needs a full PostgreSQL restart
Assumes WAL-G 3.0.9 on PostgreSQL 18; the daemon mode and walg-daemon-client belong to the WAL-G 3 line, and older 2.x setups only have per-segment wal-push.