Remote Setup

import { Tabs, TabItem } from ‘@astrojs/starlight/components’;

This guide covers setting up different remote storage backends for pgbranch.

Remote Management Commands

# Add a new remote
pgbranch remote add <name> <url>

# List configured remotes
pgbranch remote list

# Remove a remote
pgbranch remote remove <name>

# Set default remote
pgbranch remote set-default <name>

# List branches on a remote
pgbranch remote ls-remote

Storage Backend Setup

AWS S3

Prerequisites

• AWS account with S3 access
• IAM user with S3 permissions
• Access Key ID and Secret Access Key

Required IAM Permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

Add Remote

pgbranch remote add origin s3://your-bucket-name/pgbranch

You’ll be prompted for:

• AWS Access Key ID
• AWS Secret Access Key
• AWS Region (e.g., us-east-1)

Configuration

The remote is stored in .pgbranch/config.json:

{
  "remotes": {
    "origin": {
      "name": "origin",
      "type": "s3",
      "url": "s3://your-bucket-name/pgbranch",
      "options": {
        "region": "us-east-1",
        "accessKeyId": "[encrypted]",
        "secretAccessKey": "[encrypted]"
      }
    }
  },
  "defaultRemote": "origin"
}

MinIO (Self-Hosted S3)

MinIO provides S3-compatible storage you can self-host.

Prerequisites

• MinIO server running
• Access credentials

Add Remote

pgbranch remote add minio s3://bucket-name/pgbranch

When prompted, provide:

• Access Key
• Secret Key
• Endpoint URL (e.g., http://localhost:9000)

Example with Custom Endpoint

pgbranch remote add minio s3://pgbranch-bucket/snapshots
# Access Key: minioadmin
# Secret Key: minioadmin
# Endpoint: http://minio.local:9000

Docker MinIO Setup

Quick MinIO setup for testing:

docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"

Then create a bucket via the MinIO console at http://localhost:9001.

Cloudflare R2

R2 offers S3-compatible storage with no egress fees.

Prerequisites

• Cloudflare account
• R2 subscription enabled
• R2 bucket created
• API token with R2 permissions

Add Remote

pgbranch remote add r2 r2://account-id/bucket-name/prefix

You’ll be prompted for:

• Access Key ID (R2 token)
• Secret Access Key
• Account ID (from Cloudflare dashboard)

Getting R2 Credentials

1. Go to Cloudflare Dashboard → R2
2. Click “Manage R2 API Tokens”
3. Create a token with “Object Read & Write” permissions
4. Copy the Access Key ID and Secret Access Key

Example

pgbranch remote add r2 r2://abc123def456/pgbranch-snapshots/dev
# Access Key ID: [your-r2-access-key]
# Secret Access Key: [your-r2-secret-key]

Local Filesystem

Use a local or network-mounted directory for storage.

Add Remote

# Absolute path
pgbranch remote add local /path/to/storage

# File URL format
pgbranch remote add local file:///path/to/storage

No credentials are required for filesystem storage.

Use Cases

• Network shares: Mount a NAS or network drive
• Local backup: Store on a different disk
• Testing: Try remotes without cloud setup

Example with NAS

# Mount NAS first
mount -t nfs nas.local:/shared /mnt/nas

# Add as remote
pgbranch remote add nas /mnt/nas/pgbranch-snapshots

Permissions

Ensure the directory is writable:

mkdir -p /path/to/storage
chmod 755 /path/to/storage

Managing Remotes

List Remotes

pgbranch remote list

Output:

origin (default)
  Type: s3
  URL: s3://my-bucket/pgbranch

backup
  Type: filesystem
  URL: /backups/pgbranch

Set Default Remote

pgbranch remote set-default backup

The default remote is used when you don’t specify --remote:

pgbranch push main          # Uses default remote
pgbranch push main -r origin  # Uses 'origin' remote

Remove a Remote

pgbranch remote remove backup

This only removes the configuration; branches already pushed remain in storage.

List Remote Branches

# List branches on default remote
pgbranch remote ls-remote

# List branches on specific remote
pgbranch remote ls-remote -r origin

Output:

main
  Pushed: 2024-01-15 10:30:00
  Size: 45 MB
  Description: Initial schema with seed data

feature-auth
  Pushed: 2024-01-16 14:22:00
  Size: 48 MB

Skip Credentials Prompt

For automation or when using environment variables:

pgbranch remote add origin s3://bucket/prefix --no-credentials

Then set credentials via environment variables:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_REGION

Multiple Remotes

You can configure multiple remotes for different purposes:

# Team shared storage
pgbranch remote add team s3://team-bucket/pgbranch

# Personal backup
pgbranch remote add personal r2://account/personal-bucket/pgbranch

# Local fast access
pgbranch remote add local /mnt/fast-ssd/pgbranch

# Set team as default
pgbranch remote set-default team

Push to specific remotes:

pgbranch push main -r team
pgbranch push main -r personal

Troubleshooting

Connection Refused

Error: could not connect to remote: connection refused

• Check the endpoint URL
• Verify network connectivity
• For MinIO, ensure the server is running

Access Denied

Error: access denied to bucket

• Verify credentials are correct
• Check IAM permissions (S3)
• Ensure bucket exists

Invalid Credentials

Error: invalid credentials

• Re-add the remote with correct credentials
• Check for typos in access keys
• Verify the credentials haven’t been rotated

Next Steps

• Push and pull branches
• Configure credential encryption