Encryption

pgbranch uses encryption to protect sensitive credentials stored in configuration files.

Overview

When you configure remote storage (S3, R2, etc.), the credentials are encrypted before being stored in .pgbranch/config.json. This allows you to:

• Safely commit config files to version control
• Share project configuration without exposing secrets
• Keep credentials secure on disk

Encryption Key

Key Location

The encryption key is stored at:

~/.pgbranch_key

This is a user-level key, separate from project files.

Key Generation

A key is automatically generated when you:

1. Run pgbranch init for the first time
2. Add your first remote with credentials

You can also manually generate a key:

pgbranch keys generate

Output:

Encryption key generated at ~/.pgbranch_key

Key Status

Check if you have an encryption key:

pgbranch keys status

Output:

Encryption key: ~/.pgbranch_key
Status: Active
Created: 2024-01-15 10:30:00

What Gets Encrypted

Encrypted

• AWS Access Key ID
• AWS Secret Access Key
• R2/MinIO credentials
• Any authentication tokens

Not Encrypted

• Remote URLs
• Remote names
• Configuration settings
• Branch metadata

Configuration File Example

After adding a remote, your config looks like:

{
  "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:base64encodedciphertext...",
        "secretAccessKey": "ENC:v1:base64encodedciphertext..."
      }
    }
  }
}

The ENC:v1: prefix indicates encrypted values.

Key Management

Regenerating Keys

If your key is compromised:

pgbranch keys generate --force

Warning

Regenerating the key makes all previously encrypted credentials unreadable. You’ll need to re-add all remotes with their credentials.

Backing Up Keys

Back up your encryption key securely:

# Copy to secure location
cp ~/.pgbranch_key /secure/backup/location/

# Or view the key to store elsewhere
cat ~/.pgbranch_key

Sharing Keys (Team Use)

For teams sharing the same remote configuration:

Option 1: Share the key

Securely distribute ~/.pgbranch_key to team members:

# Send via secure channel (not email/Slack)
# Each team member places it at ~/.pgbranch_key

Option 2: Use separate credentials

Each team member adds the remote with their own credentials:

pgbranch remote add origin s3://bucket/prefix
# Each person enters their own AWS credentials

Option 3: Use environment variables

Skip credential storage entirely:

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

Then set environment variables:

export AWS_ACCESS_KEY_ID=xxx
export AWS_SECRET_ACCESS_KEY=xxx

Encryption Algorithm

pgbranch uses:

• Algorithm: AES-256-GCM
• Key derivation: 256-bit random key
• Format: ENC:v1:<base64-encoded-ciphertext>

The encryption is designed for local credential protection, not for securing data in transit (HTTPS handles that).

Security Best Practices

Do

• Keep ~/.pgbranch_key secure and backed up
• Use different AWS IAM users per developer
• Rotate credentials periodically
• Use environment variables in CI/CD

Don’t

• Commit ~/.pgbranch_key to version control
• Share the encryption key via insecure channels
• Use the same credentials for production and development

.gitignore Recommendations

Add to your .gitignore:

# pgbranch sensitive files
.pgbranch/config.json  # If it contains DB passwords

# Note: config.json with only remote credentials
# (encrypted) is safe to commit

For the encryption key (which is outside your project):

# The key is at ~/.pgbranch_key
# It's already outside your repo, so no .gitignore needed

Troubleshooting

”Could not decrypt credentials”

Error: could not decrypt credentials: invalid key

Causes:

• Wrong or missing encryption key
• Key was regenerated after credentials were encrypted

Solution:

# Check key status
pgbranch keys status

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

“Encryption key not found”

Error: encryption key not found at ~/.pgbranch_key

Solution:

pgbranch keys generate

Then re-add your remotes.

Moving to a New Machine

1. Copy the encryption key:

   # On old machine
   cat ~/.pgbranch_key
   
   # On new machine
   echo "your-key-content" > ~/.pgbranch_key
   chmod 600 ~/.pgbranch_key

2. Clone your project (with .pgbranch/config.json)

3. Initialize pgbranch:

   pgbranch init -d myapp_dev

4. Test remote access:

   pgbranch remote ls-remote

CI/CD Integration

In CI/CD, avoid using encrypted credentials. Instead:

GitHub Actions

env:
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

steps:
  - name: Setup pgbranch remote
    run: |
      pgbranch init -d test_db
      pgbranch remote add origin s3://bucket/prefix --no-credentials
      pgbranch pull seed-data

GitLab CI

variables:
  AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
  AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY

test:
  script:
    - pgbranch init -d test_db
    - pgbranch remote add origin s3://bucket/prefix --no-credentials
    - pgbranch pull seed-data

Related Topics

• Remote Setup - Configure remote storage
• Configuration - Config file reference