Wal · XB Field Notes

Checkpoints establish a recovery starting point

Sun, 17 Oct 2027 00:00:00 +0000

A checkpoint records progress that lets a database recover without treating its entire log history as outstanding work. The exact operation depends on the engine. PostgreSQL synchronizes the data changes required for a checkpoint and establishes a redo starting point. SQLite in WAL mode transfers eligible committed page frames from its WAL into the main database file. Neither operation is simply another name for transaction commit.

When it breaks

Checkpoint requests and complete checkpoints are different observations. SQLite readers can hold snapshots that prevent newer WAL frames from being copied into the database file or prevent the log from being reset. A passive checkpoint can return successfully after doing only the work currently possible. Reading only its success flag hides the remaining frame count and the reader that still prevents completion.

Log size also needs context. Reusing an existing file can preserve its allocated size while useful checkpoint progress advances. PostgreSQL can retain older WAL for archives or replication slots even after a checkpoint. Removing log files manually to make a graph smaller can destroy recovery material. Check the engine’s progress markers and retention obligations before equating filesystem size with unfinished recovery work.

An interval is not a hard recovery-time bound. Replay speed, storage throughput, workload shape, and the actual crash point affect recovery duration. More frequent checkpoints may reduce later replay while increasing normal write traffic. Moving WAL onto another device does not move all the data-page writes there or make the checkpoint’s cost disappear.

Check it quickly

Save the following as checkpoint_lab.py and run python3 checkpoint_lab.py with assertions enabled. It uses Python’s standard sqlite3 module and private temporary files. The recorded run used Python 3.14.4 with SQLite 3.53.0. Check your runtime’s SQLite version when comparing results, since the Python and database engine versions are distinct.

import sqlite3
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory(prefix="xbcatm-checkpoint-") as directory:
 path = Path(directory) / "test.db"
 writer = sqlite3.connect(path, isolation_level=None, timeout=0.1)
 reader = sqlite3.connect(path, isolation_level=None, timeout=0.1)
 try:
 assert writer.execute("PRAGMA journal_mode=WAL").fetchone() == ("wal",)
 writer.execute("PRAGMA synchronous=FULL")
 writer.execute("PRAGMA wal_autocheckpoint=0")
 writer.execute("CREATE TABLE marker (id INTEGER PRIMARY KEY, value INTEGER)")
 writer.execute("INSERT INTO marker VALUES (1,10)")
 assert writer.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone() == (0, 0, 0)
 reader.execute("BEGIN")
 assert reader.execute("SELECT value FROM marker").fetchone() == (10,)
 writer.execute("UPDATE marker SET value=20 WHERE id=1")
 assert writer.execute("SELECT value FROM marker").fetchone() == (20,)
 passive = writer.execute("PRAGMA wal_checkpoint(PASSIVE)").fetchone()
 blocked = writer.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()
 print("passive", passive)
 print("truncate_with_reader", blocked)
 assert passive[0] == 0 and passive[1] > passive[2] >= 0
 assert blocked[0] == 1 and blocked[1] > blocked[2]
 assert Path(str(path) + "-wal").stat().st_size > 0
 assert reader.execute("SELECT value FROM marker").fetchone() == (10,)
 reader.execute("COMMIT")
 completed = writer.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()
 print("truncate_after_reader", completed)
 assert completed == (0, 0, 0)
 assert Path(str(path) + "-wal").stat().st_size == 0
 assert reader.execute("SELECT value FROM marker").fetchone() == (20,)
 print("fresh_reader", 20)
 finally:
 reader.close()
 writer.close()

The initial truncate checkpoint moves value ten into the database file and resets the WAL. A reader then opens an explicit transaction and reads ten. Another connection commits value twenty with automatic checkpointing disabled. The writer can read twenty immediately, while the old reader still needs its original snapshot. This schedule makes the constraint visible without relying on concurrent thread timing.

In the recorded run, passive checkpoint output is (0, 1, 0): no blocking failure is reported, one frame exists, and none is checkpointed. The assertions deliberately check the relationship between frame counts instead of requiring that exact count on every engine build. The meaningful result is that a successful passive call left work behind.

The truncate request next returns (1, 1, 0) after the short busy wait. Its first field signals that the requested completion was blocked. The WAL remains nonempty, and the old reader still sees ten. The Python call returning a tuple is therefore not evidence that truncation succeeded; the tuple’s status must be inspected.

After the reader commits, another truncate checkpoint returns (0, 0, 0). The script checks the actual WAL length is zero and a fresh read sees twenty. The update was already committed before this final checkpoint. Both connections close and the temporary directory is removed even if an assertion fails.

Diagnose the work that remains

For SQLite, inspect long-lived read transactions and unfinished cursors when checkpoints cannot finish. Decide whether passive progress is sufficient or a blocking checkpoint belongs in a controlled maintenance window. Increasing the busy timeout merely waits longer for the same constraint; it does not release an application transaction. Forcing truncation after every write can add contention and defeat the concurrency benefit of WAL mode.

For PostgreSQL, use checkpoint and WAL-retention statistics appropriate to the deployed version. A completed checkpoint can coexist with retained log files and ongoing transactions. Compare foreground latency and a measured restart rehearsal when changing checkpoint frequency. This fixture verifies SQLite’s completion boundary; it does not measure a production recovery-time objective or claim identical checkpoint APIs across database engines.

Sources

SQLite write-ahead logging, reader snapshots, checkpoint progress, and WAL reuse, checked 2026-09-12.
SQLite checkpoint API, passive, restart, and truncate completion behavior, checked 2026-09-12.
SQLite checkpoint pragma, returned busy flag and frame counts, checked 2026-09-12.
PostgreSQL 18 WAL and checkpoints, checkpoint costs and independent WAL retention requirements, checked 2026-09-12.

Postgres WAL archiving reaches point-in-time recovery

Fri, 25 Jun 2027 00:00:00 +0000

Point-in-time recovery starts with a valid physical base backup and replays the WAL required to reach a chosen recovery target. The target must fall within the recoverable history of that backup and its available timelines. Archiving does not create the ability to recover to arbitrary earlier dates, nor does it repair a gap between the backup and the desired endpoint.

When it breaks

A copied data directory is not automatically a valid online backup. Use a supported backup method, preserve the required WAL and timeline history, and verify the backup manifest. pg_verifybackup finds many integrity problems, but its success does not demonstrate that later archived WAL exists or that a business recovery target produces the intended state. That requires starting recovery and checking the result.

Choosing a target also requires precision. Time, transaction, LSN, and named targets express different boundaries. For applicable target types, recovery_target_inclusive controls whether the specified boundary is included. A named restore point avoids clock ambiguity in this drill, but it only exists because an administrator deliberately wrote that marker. Reusing its name can stop recovery at the first matching point instead of the one an operator intended.

Check it quickly

Run this script as a non-root account in a Linux environment with PostgreSQL 18 server and client binaries, cp -a, mktemp, hard links, and sync FILE available. It was executed on PostgreSQL 18.6. Private temporary directories and Unix sockets isolate the clusters; TCP listening is disabled. The local archive exercises recovery mechanics without claiming protection against loss of the host.

#!/bin/sh
set -eu
umask 077
lab=$(mktemp -d /tmp/xbcatm-pitr.XXXXXX)
mkdir "$lab/socket" "$lab/archive"
primary=$lab/primary
restored=$lab/restored
missing=$lab/missing
cleanup() {
 for cluster in "$missing" "$restored" "$primary"; do
 if test -f "$cluster/postmaster.pid"; then
 pg_ctl -D "$cluster" -m fast -w stop >/dev/null
 fi
 done
}
trap cleanup EXIT
initdb -D "$primary" --no-locale --encoding=UTF8 --auth-local=trust --auth-host=reject >/dev/null
cat >> "$primary/postgresql.conf" <<CONF
listen_addresses = ''
unix_socket_directories = '$lab/socket'
port = 56432
wal_level = replica
archive_mode = on
archive_command = '$lab/archive-copy.sh "%p" "%f" "$lab/archive"'
CONF
cat > "$lab/archive-copy.sh" <<'ARCHIVE_HELPER'
#!/bin/sh
set -eu
wal_source=$1
wal_name=$2
archive_directory=$3
archive_target=$archive_directory/$wal_name
if test -e "$archive_target"; then
 cmp -s "$wal_source" "$archive_target"
 sync "$archive_target" "$archive_directory"
 exit 0
fi
archive_temporary=$(mktemp "$archive_directory/.incoming.XXXXXX")
trap 'rm -f "$archive_temporary"' EXIT HUP INT TERM
cp "$wal_source" "$archive_temporary"
sync "$archive_temporary"
ln "$archive_temporary" "$archive_target" || cmp -s "$wal_source" "$archive_target"
sync "$archive_target" "$archive_directory"
ARCHIVE_HELPER
chmod 700 "$lab/archive-copy.sh"
pg_ctl -D "$primary" -l "$lab/primary.log" -w -t 15 start >/dev/null
export PGHOST=$lab/socket PGPORT=56432 PGDATABASE=postgres PGUSER=$(id -un)
export PGCONNECT_TIMEOUT=2
psql -X -v ON_ERROR_STOP=1 -qAt <<'SQL'
CREATE TABLE marker (id integer PRIMARY KEY,value text);
INSERT INTO marker VALUES (1,'base');
SQL
pg_basebackup -D "$lab/base" -X stream -c fast -w
pg_verifybackup -q "$lab/base"
psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT pg_switch_wal()' >/dev/null
psql -X -v ON_ERROR_STOP=1 -qAt <<'SQL'
INSERT INTO marker VALUES (2,'keep');
SELECT pg_create_restore_point('before_bad_change');
UPDATE marker SET value='bad' WHERE id=1;
DELETE FROM marker WHERE id=2;
SQL
segment=$(psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT pg_walfile_name(pg_current_wal_lsn())')
psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT pg_switch_wal()' >/dev/null
attempt=0
while ! test -f "$lab/archive/$segment"; do
 attempt=$((attempt+1))
 test "$attempt" -lt 100 || { echo 'archive segment did not arrive' >&2; exit 1; }
 sleep 0.1
done
printf 'primary_now '
psql -X -v ON_ERROR_STOP=1 -qAt -c "SELECT string_agg(id||':'||value,',' ORDER BY id) FROM marker"
mkdir "$restored"
cp -a "$lab/base/." "$restored/"
cat >> "$restored/postgresql.conf" <<CONF
port = 56433
archive_mode = off
restore_command = 'cp "$lab/archive/%f" "%p"'
recovery_target_name = 'before_bad_change'
recovery_target_action = 'pause'
CONF
touch "$restored/recovery.signal"
pg_ctl -D "$restored" -l "$lab/restored.log" -w -t 15 start >/dev/null
attempt=0
while test "$(PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt -c "SELECT pg_get_wal_replay_pause_state()='paused'")" != t; do
 attempt=$((attempt+1))
 test "$attempt" -lt 100 || { echo 'restore target was not reached' >&2; exit 1; }
 sleep 0.1
done
PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt <<'SQL'
SELECT pg_is_in_recovery(),pg_get_wal_replay_pause_state();
SELECT id,value FROM marker ORDER BY id;
DO $$ BEGIN
 IF (SELECT string_agg(id||':'||value,',' ORDER BY id) FROM marker)
 IS DISTINCT FROM '1:base,2:keep' THEN
 RAISE EXCEPTION 'point-in-time result mismatch';
 END IF;
END $$;
SQL
test ! -e "$lab/base/pg_wal/$segment"
mkdir "$lab/archive-missing" "$missing"
for archived_file in "$lab/archive/"*; do
 if test "${archived_file##*/}" != "$segment"; then
 cp "$archived_file" "$lab/archive-missing/"
 fi
done
cp -a "$lab/base/." "$missing/"
cat >> "$missing/postgresql.conf" <<CONF
port = 56434
archive_mode = off
restore_command = 'cp "$lab/archive-missing/%f" "%p"'
recovery_target_name = 'before_bad_change'
recovery_target_action = 'pause'
CONF
touch "$missing/recovery.signal"
if pg_ctl -D "$missing" -l "$lab/missing.log" -w -t 15 start >/dev/null 2>&1; then
 echo 'missing-segment server was briefly available'
fi
attempt=0
while pg_ctl -D "$missing" status >/dev/null 2>&1; do
 attempt=$((attempt+1))
 test "$attempt" -lt 100 || { echo 'missing-segment server did not stop' >&2; exit 1; }
 sleep 0.1
done
grep -F 'recovery ended before configured recovery target was reached' "$lab/missing.log"
test -f "$lab/archive/$segment"
echo missing_segment_target_unreachable
printf 'lab_directory %s\nrequired_segment %s\n' "$lab" "$segment"

The primary first contains row one with value base. After taking and verifying the base backup, the script switches WAL segments, inserts row two with value keep, and creates before_bad_change. Only afterward does it change row one to bad and delete row two. primary_now 1:bad confirms the unwanted changes really reached the source database.

Recovery starts from a separate copy of the base backup. recovery.signal requests archive recovery; restore_command supplies archived files; the named target and pause action stop replay for inspection. The script waits for pg_get_wal_replay_pause_state() to report paused. Merely receiving true from pg_is_wal_replay_paused() would show that a pause was requested, not necessarily that replay has stopped.

Expected recovered output is t|paused, followed by 1|base and 2|keep. A SQL assertion checks that exact combined result. This demonstrates preservation of the earlier good transaction and exclusion of the later bad changes. It is stronger evidence than a server accepting connections, which can happen while recovery is still progressing.

The negative control makes another archive copy while excluding the required post-backup segment. It preserves the original archive and confirms that the base backup did not already contain that segment. Starting recovery against the incomplete copy must end with the fatal message that recovery ended before the configured target was reached. The script checks the server has stopped and inspects the log, rather than interpreting only the initial pg_ctl return value. missing_segment_target_unreachable records this expected failure.

All experimental clusters stop on exit. Their printed directory retains logs and data for inspection. No recovered copy is promoted or exposed to applications by this drill.

Verify before accepting recovery

A paused target provides an opportunity to compare business invariants before completing recovery. Check more than a row count: transaction boundaries, related records, and the last acceptable operation matter. Resuming a target pause completes recovery; it is not a request to keep applying arbitrary later changes. To pursue a later target, follow the documented shutdown and target-change procedure.

Record the base backup identity, available timeline, chosen target, recovered facts, and elapsed recovery time. Keep configuration and required external software alongside the recovery plan, since WAL does not restore every external dependency. Protect the original backup and archive while experimenting. A tested target establishes one recovery result; recurring drills across the retention interval establish whether the promised recovery window remains usable as backups rotate.

Sources

PostgreSQL 18 continuous archiving, base backups, archive recovery, and timeline requirements, checked 2026-09-10.
PostgreSQL 18 recovery targets, target boundaries, pause behavior, and fatal failure before an unreachable target, checked 2026-09-10.
PostgreSQL 18 administrative functions, named restore points and actual replay-pause state, checked 2026-09-10.
PostgreSQL 18 pg_verifybackup, manifest verification and why restore testing remains necessary, checked 2026-09-10.

UNLOGGED tables skip the write-ahead log

Mon, 24 May 2027 00:00:00 +0000

An unlogged PostgreSQL table keeps normal SQL transaction behavior while giving up crash recovery for its contents. It is useful for reproducible staging data, but a committed row is not guaranteed to survive a server crash. The distinction is between clean operation and recovery after an unclean shutdown, not between ordinary queries and every restart.

What bypasses WAL

The table’s data changes and those of its indexes are not written to the write-ahead log. Catalog changes still need WAL, and the database may produce WAL for other work in the same transaction. Calling an unlogged workload “zero WAL” therefore overstates the feature. Its pages also occupy storage and require normal buffer management; UNLOGGED does not mean an in-memory table.

Transactions, snapshots, constraints, and rollback still apply while the server runs. A rejected statement or a disconnected application does not automatically erase previously committed rows. A crashed backend can, however, cause the server to restart other processes and perform recovery. Avoid classifying incidents solely as “application” or “infrastructure”: determine whether PostgreSQL actually entered crash recovery.

Restart and replication boundaries

A clean shutdown preserves unlogged contents for the next start. PostgreSQL’s fast shutdown rolls back active transactions and shuts down cleanly; its immediate shutdown interrupts processes without that cleanup. The latter requires recovery, during which unlogged relations are reset. Their definitions survive, but previously committed rows do not. Normal maintenance must not be described as inevitably deleting them, nor should one successful clean restart be offered as evidence of crash safety.

Physical standbys do not receive the unlogged contents. While recovery is active, querying such a relation raises an error; it does not successfully return an empty result. After promotion, the relation can be read but has no replicated rows to recover. A failover runbook must repopulate it before consumers rely on it. Sharing a schema definition across nodes is different from replicating the table’s data.

A logged table cannot have a foreign key referencing an unlogged table. PostgreSQL rejects that definition because durable references cannot safely depend on rows that may disappear during recovery. The experiment checks this restriction instead of suggesting that ordinary durable child rows survive with silently broken references.

When it breaks

An ingestion pipeline may acknowledge a file once its rows reach an unlogged staging table, then delete the only source copy. A crash makes the acknowledgment irreversible data loss. Keep the source until the durable destination commits, and make the rebuild process identify exactly which input version it needs. Deduplication and checkpoints must belong to the durable part of that contract.

A reporting service can also fail when routed to a standby or started immediately after promotion. Empty-table detection alone misses the standby error, while blindly retrying cannot manufacture missing contents. Handle rebuilding as an explicit service state with admission checks. Test rebuild duration, upstream availability, and validation of the completed dataset; a script that merely creates an empty table is not recovery.

Check it quickly

Save the Bash block as unlogged.sh. It uses PostgreSQL 18 command-line tools as a non-root user. This container invocation supplies those tools without publishing ports or mounting host data:

docker run --rm --network none --user postgres --entrypoint bash -i \
 postgres:18-alpine < unlogged.sh

#!/usr/bin/env bash
set -euo pipefail
pg_lab=$(mktemp -d /tmp/unlogged-lab.XXXXXX)
cleanup() {
 for cluster in standby primary; do
 if [ -f "$pg_lab/$cluster/postmaster.pid" ]; then
 pg_ctl -D "$pg_lab/$cluster" -m immediate -w stop >/dev/null
 fi
 done
 rm -rf -- "$pg_lab"
}
trap cleanup EXIT
primary() { psql -X -h "$pg_lab" -p 55432 -d postgres -v ON_ERROR_STOP=1 "$@"; }
standby() { psql -X -h "$pg_lab" -p 55433 -d postgres -v ON_ERROR_STOP=1 "$@"; }
start_primary() {
 pg_ctl -D "$pg_lab/primary" -l "$pg_lab/primary.log" \
 -o "-k $pg_lab -p 55432 -c listen_addresses=''" -w start >/dev/null
}
initdb -D "$pg_lab/primary" --no-locale --encoding=UTF8 --auth=trust >/dev/null
start_primary
primary <<'SQL'
CREATE TABLE durable (id integer PRIMARY KEY);
CREATE UNLOGGED TABLE scratch (id integer PRIMARY KEY);
INSERT INTO durable VALUES (1);
INSERT INTO scratch VALUES (1);
BEGIN;
INSERT INTO scratch VALUES (2);
ROLLBACK;
DO $$
BEGIN
 EXECUTE 'CREATE TABLE durable_ref (id integer REFERENCES scratch(id))';
 RAISE EXCEPTION 'a logged table unexpectedly referenced an unlogged table';
EXCEPTION WHEN invalid_table_definition THEN
 RAISE NOTICE 'logged-to-unlogged foreign key rejected';
END $$;
SQL
counts='SELECT (SELECT count(*) FROM durable), (SELECT count(*) FROM scratch)'
test "$(primary -Atc "$counts")" = '1|1'
pg_ctl -D "$pg_lab/primary" -m fast -w stop >/dev/null
start_primary
test "$(primary -Atc "$counts")" = '1|1'
printf 'clean restart: 1|1\n'
pg_basebackup -h "$pg_lab" -p 55432 -D "$pg_lab/standby" -R -X stream -c fast
pg_ctl -D "$pg_lab/standby" -l "$pg_lab/standby.log" \
 -o "-k $pg_lab -p 55433 -c listen_addresses=''" -w start >/dev/null
test "$(standby -Atc 'SELECT pg_is_in_recovery()')" = t
test "$(standby -Atc 'SELECT count(*) FROM durable')" = 1
if standby -Atc 'SELECT count(*) FROM scratch' 2>"$pg_lab/read-error"; then
 echo 'unlogged read unexpectedly succeeded on standby' >&2
 exit 1
fi
grep -F 'cannot access temporary or unlogged relations during recovery' "$pg_lab/read-error"
pg_ctl -D "$pg_lab/standby" -w promote >/dev/null
test "$(standby -Atc "$counts")" = '1|0'
printf 'promoted standby: 1|0\n'
pg_ctl -D "$pg_lab/primary" -m immediate -w stop >/dev/null
start_primary
test "$(primary -Atc "$counts")" = '1|0'
printf 'crash recovery: 1|0\n'
primary -Atc 'SHOW server_version'
echo 'PASS: rollback, foreign key restriction, clean restart, standby, promotion, crash'

The primary and standby use separate Unix sockets inside one temporary directory. The trap stops only these experimental clusters and removes their files. The deliberate immediate shutdown affects the disposable primary, never an existing database. On PostgreSQL 18.6, rollback and clean restart leave counts 1|1; the recovery-mode standby rejects the scratch-table query. Promotion and primary crash recovery each produce 1|0. The exact error text is checked with the cluster’s C locale.

These observations establish lifecycle and constraint behavior, not a throughput improvement or a power-loss guarantee for every filesystem. Benchmark the real workload separately, including rebuild cost. Keep WAL and durability settings enabled for the durable destination; disabling them would invalidate the comparison.

Sources

PostgreSQL CREATE TABLE, unlogged contents and associated indexes, checked 2026-09-10.
PostgreSQL WAL introduction, recovery and durability roles, checked 2026-09-10.
PostgreSQL pg_ctl, clean and immediate shutdown modes, checked 2026-09-10.

WAL archiving preserves a recoverable history

Thu, 22 Apr 2027 00:00:00 +0000

Continuous WAL archiving preserves completed log files outside PostgreSQL’s active WAL directory. Together with a suitable base backup and an uninterrupted recovery chain, those files let recovery replay logged database changes to a covered target. Archiving is separate from ordinary commit acknowledgment: a transaction can commit while its WAL segment is still open or while the archive destination is unavailable.

When it breaks

PostgreSQL modifies buffered data pages during execution. Before a dependent page reaches durable storage, the necessary WAL must be durable first. This ordering does not mean that data files are never written, or that every commit waits for archiving. Temporary and unlogged table contents also do not gain ordinary WAL recovery guarantees just because archiving is enabled.

The archive command’s return code is a data-integrity contract. Zero means the file has been preserved successfully; PostgreSQL can eventually recycle the source when other retention requirements permit. A command that reports success after skipping a failed copy silently breaks that contract. Nonzero results cause retries, and repeated failure retains unarchived WAL, potentially filling the primary’s filesystem. A checkpoint does not repair the destination or discard that obligation.

Existing names need careful treatment. Repeated archival of identical, fully persisted content should succeed. Different bytes under the same name must fail without overwriting the original. Returning success merely because a destination exists can conceal corruption or archives accidentally mixed from different clusters.

Check it quickly

Run the following script as a non-root account with PostgreSQL 18 server and client binaries in PATH. It requires a Linux shell environment supporting cp -a, mktemp, hard links, and sync FILE. The drill was executed on PostgreSQL 18.6. It creates its own private temporary cluster and Unix socket, disables TCP listening, and uses only test data. The local archive illustrates the command contract; it is not an independent disaster-recovery copy.

#!/bin/sh
set -eu
umask 077
lab=$(mktemp -d /tmp/xbcatm-archive.XXXXXX)
mkdir "$lab/socket" "$lab/archive"
primary=$lab/primary
cleanup() {
 if test -f "$primary/postmaster.pid"; then
 pg_ctl -D "$primary" -m fast -w stop >/dev/null
 fi
}
trap cleanup EXIT
initdb -D "$primary" --no-locale --encoding=UTF8 --auth-local=trust --auth-host=reject >/dev/null
cat > "$lab/archive-copy.sh" <<'ARCHIVE_HELPER'
#!/bin/sh
set -eu
wal_source=$1
wal_name=$2
archive_directory=$3
archive_target=$archive_directory/$wal_name
if test -e "$archive_target"; then
 cmp -s "$wal_source" "$archive_target"
 sync "$archive_target" "$archive_directory"
 exit 0
fi
archive_temporary=$(mktemp "$archive_directory/.incoming.XXXXXX")
trap 'rm -f "$archive_temporary"' EXIT HUP INT TERM
cp "$wal_source" "$archive_temporary"
sync "$archive_temporary"
ln "$archive_temporary" "$archive_target" || cmp -s "$wal_source" "$archive_target"
sync "$archive_target" "$archive_directory"
ARCHIVE_HELPER
chmod 700 "$lab/archive-copy.sh"
cat >> "$primary/postgresql.conf" <<CONF
listen_addresses = ''
unix_socket_directories = '$lab/socket'
port = 56432
wal_level = replica
archive_mode = on
archive_command = '$lab/archive-copy.sh "%p" "%f" "$lab/archive"'
CONF
pg_ctl -D "$primary" -l "$lab/primary.log" -w -t 15 start >/dev/null
export PGHOST=$lab/socket PGPORT=56432 PGDATABASE=postgres PGUSER=$(id -un)
export PGCONNECT_TIMEOUT=2
psql -X -v ON_ERROR_STOP=1 -qAt -c 'CREATE TABLE archive_marker (id integer PRIMARY KEY)'
pg_basebackup -D "$lab/base" -X stream -c fast -w
pg_verifybackup -q "$lab/base"
echo base_backup_verified
failures_before=$(psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT failed_count FROM pg_stat_archiver')
psql -X -v ON_ERROR_STOP=1 -qAt <<'SQL'
ALTER SYSTEM SET archive_command='/bin/false';
SELECT pg_reload_conf();
SQL
attempt=0
while test "$(psql -X -v ON_ERROR_STOP=1 -qAt -c "SELECT current_setting('archive_command')='/bin/false'")" != t; do
 attempt=$((attempt+1))
 test "$attempt" -lt 100 || exit 1
 sleep 0.1
done
psql -X -v ON_ERROR_STOP=1 -qAt -c 'INSERT INTO archive_marker VALUES (1)' -c 'SELECT pg_switch_wal()' >/dev/null
attempt=0
while test "$(psql -X -v ON_ERROR_STOP=1 -qAt -c "SELECT failed_count>$failures_before FROM pg_stat_archiver")" != t; do
 attempt=$((attempt+1))
 test "$attempt" -lt 700 || { echo 'archive failure was not observed' >&2; exit 1; }
 sleep 0.1
done
failed_segment=$(psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT last_failed_wal FROM pg_stat_archiver')
test ! -f "$lab/archive/$failed_segment"
echo archive_failure_observed
psql -X -v ON_ERROR_STOP=1 -qAt -c CHECKPOINT
test -f "$primary/pg_wal/$failed_segment"
echo unarchived_wal_retained_after_checkpoint
archived_before=$(psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT archived_count FROM pg_stat_archiver')
psql -X -v ON_ERROR_STOP=1 -qAt <<'SQL'
ALTER SYSTEM RESET archive_command;
SELECT pg_reload_conf();
SQL
attempt=0
while ! test -f "$lab/archive/$failed_segment" || test "$(psql -X -v ON_ERROR_STOP=1 -qAt -c "SELECT archived_count>$archived_before FROM pg_stat_archiver")" != t; do
 attempt=$((attempt+1))
 test "$attempt" -lt 700 || { echo 'archive repair was not observed' >&2; exit 1; }
 sleep 0.1
done
cmp -s "$primary/pg_wal/$failed_segment" "$lab/archive/$failed_segment"
echo archive_repaired
"$lab/archive-copy.sh" "$primary/pg_wal/$failed_segment" "$failed_segment" "$lab/archive"
echo identical_repeat_accepted
printf 'different bytes\n' > "$lab/conflicting-input"
if "$lab/archive-copy.sh" "$lab/conflicting-input" "$failed_segment" "$lab/archive"; then
 echo 'conflicting archive input was accepted' >&2
 exit 1
fi
cmp -s "$primary/pg_wal/$failed_segment" "$lab/archive/$failed_segment"
echo conflicting_repeat_rejected
printf 'lab_directory %s\nfailed_segment %s\n' "$lab" "$failed_segment"

The script prints base_backup_verified, then temporarily replaces the archive command with a real failing executable. It waits for an observed archiver failure, checks that the failed file is absent from the archive, requests a checkpoint, and confirms the original WAL remains. Restoring the command produces archive_repaired only after archival progress and the expected destination file are observed; byte comparison checks the copy itself.

The final controls print identical_repeat_accepted and conflicting_repeat_rejected. The latter supplies deliberately different bytes under the existing name and verifies the genuine archive remains unchanged. The helper stages a copy, synchronizes it, and links the final name without overwriting another file. It returns success for an existing name only after comparing and synchronizing that content. These checks exercise the helper’s behavior, rather than assuming a successful shell invocation proves integrity.

All experimental servers stop on exit, while the printed directory retains logs and test files for inspection. A failed wait or comparison stops the drill. The deliberate archiver failure is an expected observation, not a reason to suppress errors from unrelated steps.

Preserve a recoverable interval

Monitor archive progress alongside backlog and available space. pg_stat_archiver.failed_count captures ordinary command failures such as this test; some shell failures or archiver crashes restart the process without incrementing that counter. Read server logs as well. A growing archived count alone does not prove that every file required by a particular backup and target is present.

WAL normally becomes archivable when a segment completes. On quiet databases, archive_timeout can bound waiting for segment switches, at the cost of more archive storage; streaming replication has different delivery timing. Retention must preserve the base backup, all required WAL, and relevant timeline history for the promised interval. Protect configuration and external dependencies separately. Manifest verification checks backup integrity but does not replace a restore rehearsal. Record the recovered business state and covered endpoint before treating an archive as evidence that a recovery objective is met.

Sources

PostgreSQL 18 continuous archiving, archive return codes, duplicate content, WAL retention, and recovery chains, checked 2026-09-10.
PostgreSQL 18 pg_verifybackup, manifest verification and its limits, checked 2026-09-10.
PostgreSQL 18 cumulative statistics, archiver progress and failure counters, checked 2026-09-10.

Wal · XB Field Notes

Checkpoints establish a recovery starting point

When it breaks

Check it quickly

Diagnose the work that remains

Sources

Postgres WAL archiving reaches point-in-time recovery

When it breaks

Check it quickly

Verify before accepting recovery

Further reading

Sources

UNLOGGED tables skip the write-ahead log

What bypasses WAL

Restart and replication boundaries

When it breaks

Check it quickly

Sources

WAL archiving preserves a recoverable history

When it breaks

Check it quickly

Preserve a recoverable interval

Further reading

Sources