Skip to content

Set up R2

R2 has no egress fees, so downloading backups for drills and restores costs nothing. The free tier (10 GB) is enough for most small databases. You need a Cloudflare account, and R2 asks for a payment method even on the free tier.

In the Cloudflare dashboard:

  1. Click R2 Object Storage in the sidebar. If this is your first time, accept the R2 terms.

  2. Click Create bucket. Name it, for example acme-db-backups. Leave Location on Automatic and Default storage class on Standard, then click Create bucket.

    To keep the data in the EU, choose the European Union (EU) jurisdiction here. That bucket gets its own endpoint (see below).

  3. Leave Public access off. Backups are encrypted anyway, but nobody needs to read them over the web.

  1. Back on the R2 overview page, click Manage API tokens (under Account details → API Tokens).

  2. Click Create Account API token. (A User API token works too.)

  3. Give it a name like pgbackup-acme.

  4. Under Permissions, choose Object Read & Write. prune deletes old backups, and this permission includes that.

  5. Under Specify bucket(s), choose Apply to specific buckets only and pick your bucket.

  6. Leave TTL on Forever, or set an expiry and a reminder to rotate the token. Click Create API Token.

  7. Copy the Access Key ID and the Secret Access Key. The secret is shown only once. Also copy the endpoint shown for S3 clients.

Terminal window
S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
S3_BUCKET=acme-db-backups
S3_PREFIX=acme # a short name for the app; one bucket can hold many apps
AWS_ACCESS_KEY_ID=<Access Key ID>
AWS_SECRET_ACCESS_KEY=<Secret Access Key>

Leave S3_REGION unset: auto is right for R2.

EU jurisdiction buckets use a different endpoint:

Terminal window
S3_ENDPOINT=https://<account-id>.eu.r2.cloudflarestorage.com

Then check it all with pgb doctor. It writes a tiny test file under the prefix and deletes it again.

Drills and restores only read backups, so a token with Object Read only works for them. But every drill also writes a small record to <prefix>/.drills/, which is how pgb list and pgb doctor know when you last drilled. A read-only token can’t write it. The drill still runs, with a warning, but it isn’t remembered.

To keep the records, give the laptop token Object Read & Write too, limited to the same bucket.

Keys and security: where the public and private keys live, and what happens if you lose one.

Also: keep using folders you already have, with lifecycle and lock rules (Use your existing folders), or use something other than R2 (Other storage).

pgbackup-r2 is an open-source tool from Iotabyt. MIT licensed.