viperadnan/dbstash repository overview

⁠dbstash

Database backup via rclone. Stream database dumps directly to any cloud storage without intermediate files or local disk pressure. Run as a standalone CLI or as Docker containers.

⁠Features

• Zero Disk Usage — Stream dumps directly to cloud storage (stream mode)
• CLI and Docker — Run as a standalone binary with flags or as purpose-built Docker images
• Any Cloud Storage — Works with S3, GCS, Azure, Dropbox, 40+ backends via rclone
• Multiplatform — Built for linux/amd64 and linux/arm64
• Flexible Scheduling — Cron expressions or one-time backups
• Secrets Support — Docker secrets via _FILE environment variables
• Compression — Native dump tool compression support
• Retention Policies — Automatic cleanup by age or file count
• Notifications — Slack/Discord webhooks on success or failure
• Hooks — Pre/post-backup shell command execution
• Encryption at Rest — Transparent encryption via rclone's crypt remote

⁠Quick Start

dbstash requires only three things to run:

1. Database connection — DB_URI or DB_HOST + DB_NAME
2. Rclone remote — RCLONE_REMOTE (where to store backups)
3. Rclone config — A valid rclone config file

# One-time PostgreSQL backup to S3
docker run --rm \
  -e DB_URI="postgresql://user:pass@host:5432/mydb" \
  -e RCLONE_REMOTE="s3:my-bucket/backups" \
  -e BACKUP_SCHEDULE=once \
  -v /path/to/rclone.conf:/root/.config/rclone/rclone.conf:ro \
  ghcr.io/viperadnan-git/dbstash:pg-17

# Dump all MongoDB databases
docker run --rm \
  -e DB_URI="mongodb+srv://user:[email protected]" \
  -e BACKUP_ALL_DATABASES=true \
  -e RCLONE_REMOTE="s3:my-bucket/backups" \
  -e BACKUP_SCHEDULE=once \
  -v /path/to/rclone.conf:/root/.config/rclone/rclone.conf:ro \
  ghcr.io/viperadnan-git/dbstash:mongo-8

⁠CLI Usage

dbstash is also available as a standalone binary. Pre-built binaries for Linux, macOS, and Windows can be downloaded from Releases⁠. Requires rclone and the engine's dump tool (pg_dump, mongodump, mysqldump, redis-cli) to be installed.

dbstash <engine> [flags]

All flags map 1:1 to environment variables (DB_HOST -> --db-host). Run dbstash <engine> --help for details.

Flags and environment variables can be mixed. Precedence: CLI flag > environment variable > default value.

⁠Available Docker Images

Tag Strategy:

• :engine-version (e.g. :pg-17) — Pinned to specific database version
• :engine and :engine-latest (e.g. :pg, :pg-latest) — Both point to the latest version
• :engine-version-dbstashversion (e.g. :pg-17-0.7.0) — Created on git tag releases

All images: ghcr.io/viperadnan-git/dbstash:<tag>

⁠How It Works

dbstash streams database dump output directly to rclone, avoiding local disk usage:

dump stdout --> rclone rcat remote:path/filename

No intermediate files are created on disk (in stream mode). The Go binary handles process piping, scheduling, retention cleanup, and notifications.

⁠Docker Compose Example

services:
  backup-pg:
    image: ghcr.io/viperadnan-git/dbstash:pg-16
    environment:
      DB_URI_FILE: /run/secrets/pg_uri
      RCLONE_REMOTE: "s3:my-bucket/backups/pg"
      RCLONE_CONFIG_FILE: /run/secrets/rclone_conf
      BACKUP_SCHEDULE: "0 */6 * * *"
      BACKUP_NAME_TEMPLATE: "{db}-{timestamp}"
      BACKUP_TIMEOUT: "1h"
      RETENTION_MAX_FILES: 20
      RETENTION_MAX_DAYS: 30
      NOTIFY_WEBHOOK_URL: ${DISCORD_WEBHOOK_URL}
      NOTIFY_ON: failure
      LOG_LEVEL: info
      TZ: Asia/Kolkata
    secrets:
      - pg_uri
      - rclone_conf
    restart: unless-stopped

secrets:
  pg_uri:
    file: ./secrets/pg_uri.txt
  rclone_conf:
    file: ./secrets/rclone.conf

⁠Configuration

All options can be set via environment variables or CLI flags. In Docker mode, use environment variables. In CLI mode, use flags (which fall back to environment variables automatically).

⁠Connection

*Either DB_URI/DB_URI_FILE or DB_HOST + DB_NAME must be provided. When BACKUP_ALL_DATABASES=true, DB_NAME is not required. DB_NAME and BACKUP_ALL_DATABASES are mutually exclusive.

⁠Rclone

⁠Schedule & Naming

⁠Name Template Tokens

The BACKUP_NAME_TEMPLATE value is expanded at backup time by replacing tokens with runtime values. The file extension is appended automatically based on the engine and compression setting (override with BACKUP_EXTENSION). All timestamps respect the TZ environment variable (default UTC).

Default template: {db}-{timestamp} produces filenames like myapp-20260207T020000Z.sql.

⁠Retention

⁠Notifications

⁠Hooks

Post-backup hooks receive DBSTASH_STATUS (success/failure) and DBSTASH_FILE (remote path) as environment variables.

⁠Logging

⁠Backup Modes

⁠Compression

⁠All Databases

Set BACKUP_ALL_DATABASES=true to dump every database on the server instead of a single one.

DB_NAME and BACKUP_ALL_DATABASES are mutually exclusive. When using a URI, the database name is automatically stripped for engines that would otherwise scope the dump to a single database.

⁠Encryption at Rest

Use rclone's native crypt remote:

[s3-backup]
type = s3
provider = AWS
access_key_id = ...
secret_access_key = ...

[s3-backup-encrypted]
type = crypt
remote = s3-backup:my-bucket/backups
password = ... (obscured)

Set RCLONE_REMOTE=s3-backup-encrypted: and all backups are transparently encrypted.

⁠Docker Secrets

Any sensitive env var supports a _FILE suffix. dbstash reads the secret from the file at startup:

services:
  backup:
    image: ghcr.io/viperadnan-git/dbstash:pg-16
    environment:
      DB_URI_FILE: /run/secrets/db_uri
      RCLONE_CONFIG_FILE: /run/secrets/rclone_conf
    secrets:
      - db_uri
      - rclone_conf

secrets:
  db_uri:
    file: ./secrets/db_uri.txt
  rclone_conf:
    file: ./secrets/rclone.conf

Supported _FILE variants: DB_URI_FILE, DB_PASSWORD_FILE, RCLONE_CONFIG_FILE.

⁠Health Check

When running with a cron schedule, dbstash serves a health endpoint:

GET :8080/healthz

Returns:

{"status": "healthy", "engine": "pg", "last_backup": "2026-02-07T02:00:05Z", "last_status": "success"}

⁠License

MIT⁠