Remote Storage Overview

pgbranch supports remote storage backends, allowing you to share database snapshots with your team or sync across your own machines.

Why Use Remotes?

Team Collaboration

Share a known-good database state with your team:

# Developer A creates and pushes a branch
pgbranch branch seed-data
# ... add test data ...
pgbranch push seed-data

# Developer B pulls the same state
pgbranch pull seed-data

Everyone works with identical database states.

Multi-Machine Sync

Sync your database branches between work and home:

# At work
pgbranch push feature-wip

# At home
pgbranch pull feature-wip

Onboarding

New team members can quickly get a working database:

pgbranch init -d myapp_dev
pgbranch pull seed-data
pgbranch checkout seed-data

No need to run migrations and seed scripts from scratch.

Supported Backends

Backend	URL Format	Best For
Filesystem	`/path/to/dir` or `file:///path`	Local network shares, NAS
AWS S3	`s3://bucket/prefix`	Teams using AWS
MinIO	`s3://bucket/prefix` (with endpoint)	Self-hosted S3-compatible
Cloudflare R2	`r2://account-id/bucket/prefix`	Cost-effective storage

How It Works

Push Operation

When you push a branch:

pgbranch creates a compressed archive of the template database
The archive is encrypted (if configured)
The archive is uploaded to the remote storage

Template DB: pgbranch_main_abc123
                │
                ▼
         pg_dump + compress
                │
                ▼
         Encrypt (optional)
                │
                ▼
         Upload to S3/R2/etc.

Pull Operation

When you pull a branch:

pgbranch downloads the archive from remote storage
The archive is decrypted (if needed)
The archive is restored as a local template database

Download from S3/R2/etc.
         │
         ▼
    Decrypt (if needed)
         │
         ▼
    Decompress + pg_restore
         │
         ▼
Template DB: pgbranch_main_abc123

Security

Credential Encryption

Remote storage credentials are encrypted locally using a key stored in ~/.pgbranch_key. This means:

Config files can be safely committed to version control
Credentials are not exposed in plaintext
Each machine has its own encryption key

Learn more about encryption

Archive Encryption

Database archives can be encrypted before upload (coming soon).

Quick Start

1. Add a Remote

pgbranch remote add origin s3://my-bucket/pgbranch

You’ll be prompted for credentials.

2. Push a Branch

pgbranch push main

3. Pull on Another Machine

pgbranch pull main

Storage Costs

Database archives are compressed but can still be large. Consider:

Database Size	Compressed Archive
100 MB	~20-40 MB
1 GB	~200-400 MB
10 GB	~2-4 GB

Compression ratio depends on data content (text compresses better than binary).

Cost Optimization Tips

Prune old branches before pushing
Use lifecycle policies on S3/R2 to auto-delete old archives
Push only what you need (not every local branch)

Limitations

No Streaming

Entire archives must be downloaded/uploaded. For very large databases, this can be slow.