diff --git a/README.md b/README.md index 3653fb2..fbb6fe6 100644 --- a/README.md +++ b/README.md @@ -18,43 +18,45 @@ These tools are part of the collection of [PostgreSQL Client Applications](https On an Ubuntu server, these tools are contained within the package `postgresql-client-` based on the major version of PostgreSQL being used. ## Configuration -Configuration for pg2s3 is handled exclusively through environment variables. -This leaves out the need for config files, command line parameters, and the precedence rules that exist between them. -Note that the S3 bucket defined by `PG2S3_S3_BUCKET_NAME` must be created outside of this tool. +Configuration for pg2s3 is handled exclusively through a config file written in [TOML](https://github.com/toml-lang/toml). +By default, pg2s3 will look for a config file named `pg2s3.toml` in the current directory. +The config file loaded by pg2s3 can be customized by using the `-conf` flag. +Note that the S3 bucket defined by `s3_bucket_name` must be created outside of this tool. Bucket creation has more configuration and security options than pg2s3 is positioned to deal with. -Additionally, the value defined by `PG2S3_BACKUP_RETENTION` simply refers to the _number_ of backups kept during a prune. -It has nothing to do with the backups' age or total bucket size. + +Additionally, the value defined by `backup_retention` simply refers to the _number_ of backups kept during a prune. +It has nothing to do with a backup's age or total bucket size. If programmatic backups are in use, you'll want to consider the scheduling frequency when determining an appropriate retention count. -The following environment variables are required to run pg2s3: +The following settings are required to run pg2s3: -| Variable | Description | -| ---------------------------- | ----------- | -| `PG2S3_PG_CONNECTION_URI` | PostgreSQL connection string | -| `PG2S3_S3_ENDPOINT` | S3-compatible storage endpoint | -| `PG2S3_S3_ACCESS_KEY_ID` | S3-compatible storage access key ID | -| `PG2S3_S3_SECRET_ACCESS_KEY` | S3-compatible storage secret access key | -| `PG2S3_S3_BUCKET_NAME` | S3-compatible storage bucket name | -| `PG2S3_BACKUP_PREFIX` | Prefix attached to the name of each backup | -| `PG2S3_BACKUP_RETENTION` | Number of backups to retain after pruning | +| Setting | Description | +| ---------------------- | ----------- | +| `pg_connection_uri` | PostgreSQL connection string | +| `s3_endpoint` | S3-compatible storage endpoint | +| `s3_access_key_id` | S3-compatible storage access key ID | +| `s3_secret_access_key` | S3-compatible storage secret access key | +| `s3_bucket_name` | S3-compatible storage bucket name | +| `backup_prefix` | Prefix attached to the name of each backup | +| `backup_retention` | Number of backups to retain after pruning | ## Encryption Backups managed by pg2s3 can be optionally encrypted using [age](https://github.com/FiloSottile/age). -To enable this feature, an age public key must be defined as an additional environment variable. +To enable this feature, an age public key must be defined within the config file. Note that the private key associated with this public key must be kept safe and secure! When restoring a backup, pg2s3 will prompt for the private key. This key is intentionally absent from pg2s3's environment in order to require user intervention for any data decryption. -| Variable | Description | -| ------------------------- | ----------- | -| `PG2S3_AGE_PUBLIC_KEY` | Public key for backup encryption | +| Setting | Description | +| ---------------- | ----------- | +| `age_public_key` | Public key for backup encryption | ## Usage The pg2s3 command-line tool offers three commands: -* `pg2s3 backup` - Create a new backup and upload to S3 -* `pg2s3 restore` - Download the latest backup from S3 and restore -* `pg2s3 prune` - Prune old backups from S3 +* `pg2s3 -backup` - Create a new backup and upload to S3 +* `pg2s3 -restore` - Download the latest backup from S3 and restore +* `pg2s3 -prune` - Prune old backups from S3 ## Local Development To develop and test locally, containers for [PostgreSQL](https://www.postgresql.org/) and [MinIO](https://min.io/) must be running: @@ -70,6 +72,5 @@ docker compose down ## Testing With the above containers running: ``` -source testdata/environment go test ./... ```