Configuration

pgbranch stores its configuration in .pgbranch/config.json within your project directory.

File Location

your-project/
├── .pgbranch/
│   ├── config.json      # Main configuration
│   ├── branches/        # Branch metadata
│   │   ├── main.json
│   │   └── feature.json
│   └── key              # Local encryption key (deprecated)
├── src/
└── ...

Configuration Schema

{
  "database": "string",
  "host": "string",
  "port": "number",
  "user": "string",
  "password": "string",
  "remotes": {
    "<name>": {
      "name": "string",
      "type": "string",
      "url": "string",
      "options": {}
    }
  },
  "defaultRemote": "string"
}

Fields

Database Connection

Field	Type	Required	Default	Description
database	string	Yes	-	PostgreSQL database name
host	string	No	localhost	PostgreSQL host
port	number	No	5432	PostgreSQL port
user	string	No	postgres	PostgreSQL user
password	string	No	""	PostgreSQL password

Remotes

Field	Type	Required	Description
remotes	object	No	Map of remote configurations
defaultRemote	string	No	Name of default remote

Remote Configuration

Each remote in the remotes object:

Field	Type	Required	Description
name	string	Yes	Remote identifier
type	string	Yes	Backend type (s3, filesystem, r2)
url	string	Yes	Remote URL
options	object	No	Backend-specific options

Example Configurations

Minimal (Local Only)

{
  "database": "myapp_dev",
  "host": "localhost",
  "port": 5432,
  "user": "postgres"
}

With S3 Remote

{
  "database": "myapp_dev",
  "host": "localhost",
  "port": 5432,
  "user": "postgres",
  "remotes": {
    "origin": {
      "name": "origin",
      "type": "s3",
      "url": "s3://my-bucket/pgbranch",
      "options": {
        "region": "us-east-1",
        "accessKeyId": "ENC:v1:...",
        "secretAccessKey": "ENC:v1:..."
      }
    }
  },
  "defaultRemote": "origin"
}

With Multiple Remotes

{
  "database": "myapp_dev",
  "host": "localhost",
  "port": 5432,
  "user": "postgres",
  "remotes": {
    "team": {
      "name": "team",
      "type": "s3",
      "url": "s3://team-bucket/pgbranch",
      "options": {
        "region": "us-east-1",
        "accessKeyId": "ENC:v1:...",
        "secretAccessKey": "ENC:v1:..."
      }
    },
    "backup": {
      "name": "backup",
      "type": "filesystem",
      "url": "/mnt/backup/pgbranch"
    },
    "r2": {
      "name": "r2",
      "type": "r2",
      "url": "r2://account123/pgbranch-bucket/snapshots",
      "options": {
        "accessKeyId": "ENC:v1:...",
        "secretAccessKey": "ENC:v1:..."
      }
    }
  },
  "defaultRemote": "team"
}

With MinIO

{
  "database": "myapp_dev",
  "host": "localhost",
  "port": 5432,
  "user": "postgres",
  "remotes": {
    "minio": {
      "name": "minio",
      "type": "s3",
      "url": "s3://pgbranch-bucket/snapshots",
      "options": {
        "endpoint": "http://minio.local:9000",
        "accessKeyId": "ENC:v1:...",
        "secretAccessKey": "ENC:v1:...",
        "forcePathStyle": true
      }
    }
  },
  "defaultRemote": "minio"
}

Remote Options by Type

S3 Options

Option	Type	Required	Description
region	string	Yes*	AWS region
accessKeyId	string	Yes*	AWS access key (encrypted)
secretAccessKey	string	Yes*	AWS secret key (encrypted)
endpoint	string	No	Custom S3 endpoint (for MinIO)
forcePathStyle	boolean	No	Use path-style URLs

*Can be provided via environment variables instead

R2 Options

Option	Type	Required	Description
accessKeyId	string	Yes	R2 access key (encrypted)
secretAccessKey	string	Yes	R2 secret key (encrypted)

Filesystem Options

No options required for filesystem remotes.

Branch Metadata

Branch files in .pgbranch/branches/:

{
  "name": "feature-auth",
  "created": "2024-01-15T14:22:00Z",
  "parent": "main",
  "snapshot": "pgbranch_feature_auth_abc123",
  "lastAccessed": "2024-01-16T10:30:00Z"
}

Environment Variables

pgbranch respects standard PostgreSQL and AWS environment variables:

PostgreSQL

Variable	Description
PGHOST	PostgreSQL host
PGPORT	PostgreSQL port
PGUSER	PostgreSQL user
PGPASSWORD	PostgreSQL password
PGDATABASE	PostgreSQL database

AWS/S3

Variable	Description
AWS_ACCESS_KEY_ID	AWS access key
AWS_SECRET_ACCESS_KEY	AWS secret key
AWS_REGION	AWS region
AWS_ENDPOINT_URL	Custom S3 endpoint

Environment variables take precedence over config file values.

Version Control

Safe to Commit

• .pgbranch/config.json (if using encrypted credentials or no passwords)
• .pgbranch/branches/*.json

Do Not Commit

• .pgbranch/config.json if it contains plaintext database passwords
• ~/.pgbranch_key (user-level encryption key)

Recommended .gitignore

.pgbranch/config.json

# Only if config contains plaintext passwords

Editing Configuration

While you can edit config.json manually, it’s recommended to use commands:

# Database settings
pgbranch init -d newdb -H newhost

# Remotes
pgbranch remote add name url
pgbranch remote remove name
pgbranch remote set-default name

Validating Configuration

pgbranch validates config on every command. Common validation errors:

Error: database name is required
Error: invalid remote URL format
Error: remote 'origin' not found

Migrating Configuration

If you need to update configuration format:

# Backup current config
cp .pgbranch/config.json .pgbranch/config.json.bak

# Reinitialize (preserves branches)
pgbranch init -d myapp_dev

# Re-add remotes
pgbranch remote add origin s3://bucket/prefix