nself pitr

Point-In-Time Recovery for your Postgres database. Continuous WAL archiving to S3-compatible storage means you can restore to any second in history — not just the last snapshot.

Quick start

# Check current PITR configuration
nself pitr status

# Enable WAL archiving (requires S3-compatible bucket config in env)
nself pitr enable

# Verify the archive pipeline is healthy
nself pitr test

Synopsis

nself pitr <SUBCOMMAND> [FLAGS]

Description

nself pitr configures continuous WAL (Write-Ahead Log) archiving from your Postgres instance to any S3-compatible object storage — AWS S3, MinIO, Cloudflare R2, Backblaze B2, and others. WAL segments are shipped in near real-time (typically under 60 seconds lag). Combined with periodic base backups, this gives you the ability to restore to any point in time within your retention window.

Restoration happens into an isolated sidecar container so your production database is never touched during a restore operation. Once the recovery container reaches the target timestamp, you validate the data before promoting it to replace the primary.

Prerequisites

Before enabling PITR, set the following env vars:

nself env set PITR_S3_ENDPOINT  https://s3.amazonaws.com   # or your R2/MinIO endpoint
nself env set PITR_S3_BUCKET    my-nself-wal-archive
nself env set PITR_S3_REGION    us-east-1
nself env set PITR_S3_KEY_ID    AKIAIOSFODNN7EXAMPLE
nself env set PITR_S3_SECRET    wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Subcommands

nself pitr status

Show the current PITR configuration: whether archiving is enabled, the archive endpoint, lag, retention period, and the oldest recoverable point.

nself pitr status
# PITR:             enabled
# Archive endpoint: s3://my-nself-wal-archive (us-east-1)
# WAL lag:          12 seconds
# Retention:        30 days
# Oldest recovery:  2026-04-07T08:22:00Z
# Last base backup: 2026-05-06T03:00:00Z (24 hours ago)

nself pitr enable

Enable WAL archiving. Validates S3 credentials, configures archive_command in Postgres, and schedules a base backup immediately.

nself pitr enable
# Validating S3 credentials...    ✓
# Setting archive_command...      ✓
# Reloading PostgreSQL config...  ✓
# Taking initial base backup...   ✓ (completed in 8s)
# ✓ PITR enabled. WAL archiving is now active.

Set a custom retention window (default: 30 days):

nself pitr enable --retention 14d

nself pitr test

Verify the end-to-end archive pipeline without touching production data. Writes a test WAL segment, confirms it arrives in the S3 bucket, and measures lag.

nself pitr test
# Writing test WAL segment...   ✓
# Waiting for archive upload... ✓ (lag: 8s)
# Verifying segment in S3...    ✓
# PITR pipeline is healthy

nself pitr restore

Restore the database to a specific point in time. Spins up an isolated recovery container, applies WAL segments up to the target timestamp, then pauses for validation before promotion.

# Interactive restore (prompts for target time)
nself pitr restore

# Restore to a specific timestamp (ISO 8601)
nself pitr restore --to 2026-05-07T10:30:00Z

# Restore and auto-promote after validation (production use requires --confirm)
nself pitr restore --to 2026-05-07T10:30:00Z --auto-promote --confirm

The restore flow:

1. Locate the nearest base backup before the target time
2. Start a recovery container from that base backup
3. Apply WAL segments up to the target timestamp
4. Pause — you can now inspect the recovered database at localhost:5433
5. Promote (replace primary) or discard the recovery container

# Inspect the recovered data before promoting
psql -h localhost -p 5433 -U postgres -c "SELECT count(*) FROM np_users;"

# Promote the recovery container to replace the primary
nself pitr restore --promote
# OR discard without promoting
nself pitr restore --discard

nself pitr backup-sync

Take a base backup immediately and upload it to S3. Base backups are taken automatically on a schedule (default: daily at 03:00 UTC), but you can trigger one manually.

nself pitr backup-sync
# Starting base backup...
# Uploading to s3://my-nself-wal-archive/base/2026-05-07T14-22-00/
# ✓ Base backup complete (1.2 GB, 14s)

nself pitr backup-sync-status

List all base backups in the archive bucket with their size and age.

nself pitr backup-sync-status
# TIMESTAMP               SIZE    AGE
# 2026-05-07T03:00:00Z    1.2 GB  11 hours
# 2026-05-06T03:00:00Z    1.1 GB  35 hours
# 2026-05-05T03:00:00Z    1.1 GB  59 hours

nself pitr restore-drill

Run a non-destructive restore drill — spins up a recovery container, restores to the most recent recoverable point, validates basic database health, then tears down the container. Used for routine DR testing.

nself pitr restore-drill
# Locating latest base backup...       ✓
# Starting recovery container...       ✓
# Applying WAL to latest point...      ✓ (lag: 18s)
# Running health checks...             ✓
# Tables accessible: 47/47
# Tearing down recovery container...   ✓
# ✓ Restore drill passed (total: 2m 14s)

nself pitr restore-drill-list

List the results of previous restore drills with timestamps and pass/fail status.

nself pitr restore-drill-list
# TIMESTAMP               RESULT   DURATION   WAL LAG
# 2026-05-07T04:00:00Z    PASS     2m 14s     18s
# 2026-05-06T04:00:00Z    PASS     2m 09s     22s
# 2026-05-04T04:00:00Z    FAIL     —          timeout

Flags

Environment variables

Related

• nself backup — snapshot-based backups (complement to PITR)
• nself db — database management and migrations
• nself doctor — verify PITR configuration is healthy