Wal Fetch Command: Complete WAL-G Reference Guide

The wal-g wal-fetch command is responsible for retrieving individual Write-Ahead Log (WAL) files from configured remote storage during PostgreSQL recovery. It is designed to be called automatically by PostgreSQL's restore_command, making it an invisible but essential part of database recovery automation.

Basic syntax: /usr/local/bin/wal-g wal-fetch "%f" "%p" --config /path/to/config.yaml. The first argument is the WAL filename (%f), the second is the destination path (%p) where PostgreSQL expects the file. A config file can be specified to override environment variables.

Exit code behavior is critical for PostgreSQL integration. Wal-fetch returns 0 on success, exit code 74 (EX_IOERR) when the requested WAL file does not exist in storage (signaling end of WAL), and non-zero for other errors. PostgreSQL interprets exit code 74 as a clean end-of-archive signal rather than an error.

Environment variables controlling wal-fetch behavior: WALG_DOWNLOAD_CONCURRENCY (parallel goroutines), WALG_DOWNLOAD_FILE_RETRIES (retry count on failure, default 15), WALG_PGP_KEY or WALG_PGP_KEY_PATH (GPG decryption), WALG_S3_PREFIX or WALG_GS_PREFIX or WALG_AZ_PREFIX (storage location).

Prefetch behavior: WAL-G automatically prefetches upcoming WAL files in the background and stores them in /.wal-g/prefetch/. When wal-fetch is called for a file already prefetched, it instantly moves the file to the destination, dramatically reducing recovery latency.

Config file format (YAML) allows nested failover storage configuration—impossible to express via environment variables alone. Use a config file when configuring multiple failover storage backends for high-availability backup setups.

“Understanding wal-fetch exit codes—especially code 74—is essential for PostgreSQL recovery to complete cleanly without false error alerts.”