mysql-bkup/docs/reference/index.md

title, layout, nav_order

title	layout	nav_order
Configuration Reference	default	3

Configuration Reference

mysql-bkup is configured with environment variables, CLI flags and an optional YAML file. For every setting the order is: flag, environment variable, deprecated name, YAML env: section, default. Every secret (DB_PASSWORD, AWS_SECRET_KEY, GPG_PASSPHRASE, ...) can also be read from a file with <NAME>_FILE.

Run mysql-bkup config to see the resolved configuration and where each value comes from (secrets redacted).

Commands

Command	Description
backup	Back up now, or as a daemon with --cron-expression
restore	Restore a backup: -f FILE [-d DB]
migrate	Copy a database (or every database with -a) into TARGET_DB_*, streamed
verify	Download, decrypt and decompress a backup and check its sha256
list	Backup history from the index (--json, --storage-scan)
delete	Delete a backup, its sidecar and its index entry (-f FILE)
prune	Apply the retention policy (--dry-run)
reconcile	Rebuild the backup index (--from-index OLD, --dry-run)
config	Show the resolved configuration; --env-docs prints the tables below
health	Exit 0 when the daemon is healthy (Docker HEALTHCHECK)
version	Print the version

Flags

Flag	Short	Commands	Variable
--dbname	-d	all	DB_NAME
--storage	-s	all	STORAGE (local, s3, gcs, azure, sftp/ssh/remote, ftp)
--path (--remote-path)	-P	all	REMOTE_PATH
--file	-f	restore, verify, delete	FILE_NAME
--config	-c	backup, list, prune, config	BACKUP_CONFIG_FILE
--cron-expression	-e	backup	BACKUP_CRON_EXPRESSION
--all-databases	-a	backup, migrate	BACKUP_ALL_DATABASES
--all-in-one	-A	backup	BACKUP_ALL_IN_ONE
--exclude-db		backup	BACKUP_EXCLUDE_DATABASES
--custom-name		backup	BACKUP_CUSTOM_NAME (fixed name, no timestamp)
--name	-n	backup, list, prune	BACKUP_NAME
--disable-compression		backup	DISABLE_COMPRESSION
--compression		backup	COMPRESSION (gzip, zstd, none)
--encryption		backup	ENCRYPTION (auto, none, gpg, age)
--index-name		all	BACKUP_INDEX_NAME
--result-file		all	RESULT_FILE
--help	-h	all
--version	-v	root

Exit codes

Code	Meaning
0	success
1	failure
2	configuration error
3	database connection or authentication
4	storage
5	encryption or decryption

Environment variables

storage

Variable	Flag	Default	Fallbacks	Description
STORAGE	--storage -s	local		Storage backend: local, s3, gcs, azure, sftp (ssh, remote), ftp (local, s3, gcs, azure, sftp, ssh, ftp, remote)
STORAGE_PATH		/backup		Root directory of the local storage backend
REMOTE_PATH	--path -P		AWS_S3_PATH (deprecated), S3_PATH (deprecated)	Folder inside the storage backend (without file name)

general

Variable	Flag	Default	Fallbacks	Description
BACKUP_NAME	--name -n			Base name of the artifact; a timestamp is appended (default: the database or volume name)
BACKUP_CUSTOM_NAME	--custom-name			Fixed artifact name without timestamp (overwrites the previous one)
FILE_NAME	--file -f			Backup file to restore, verify or delete
BACKUP_CONFIG_FILE	--config -c			YAML configuration file (default /config/config.yaml if present)
BACKUP_TIMEOUT				Abort a backup after this duration (0 = none)
RESTORE_TIMEOUT				Abort a restore after this duration (0 = none)
TMP_DIR		/tmp/backup	BACKUP_TMP_DIR (deprecated)	Scratch directory (only for secret files and disk-based modes)
COMPRESSION	--compression	gzip		Compression: gzip, zstd or none (gzip, zstd, none)
COMPRESSION_LEVEL				Compression level (0 = default)
DISABLE_COMPRESSION	--disable-compression			Same as COMPRESSION=none
RESTORE_VERIFY_FIRST	--verify-first	auto		Verify the whole artifact before restoring (auto: on for GPG-encrypted volumes) (auto, true, false)
LOG_LEVEL		info		Log level (debug, info, warn, error)
LOG_FORMAT		text		Log format (text, json)
TIME_FORMAT		2006-01-02 15:04:05		Time layout used in notifications
RESULT_FILE	--result-file			Write the run result as JSON to this path

scheduling

Variable	Flag	Default	Fallbacks	Description
BACKUP_CRON_EXPRESSION	--cron-expression -e			Run as a daemon on this cron schedule (5 or 6 fields, @daily, @every 6h)
BACKUP_RUN_ON_START				In daemon mode, run one backup immediately at start
BACKUP_RESCUE_MODE				Deprecated: runs always continue with the remaining targets after a failure
METRICS_ADDR				Serve Prometheus /metrics and /healthz on this address in daemon mode (e.g. :9090)
HEALTH_FILE		/tmp/bkup-health.json		State file read by the health command
HEALTH_MAX_AGE				health fails when the last success is older than this (default: 2x the schedule interval)

retention

Variable	Flag	Default	Fallbacks	Description
BACKUP_RETENTION_DAYS		0		Delete backups older than N days (0 = keep)
BACKUP_RETENTION_COUNT		0		Keep only the newest N backups (0 = no limit)
BACKUP_RETENTION_ALLOW_ROOT				Allow pattern-based retention at the storage root (index disabled)
BACKUP_RETENTION_ADOPT_LEGACY				Import pre-index backups matching this tool's naming into the index
BACKUP_INDEX		true		Keep the backup index file and per-backup .meta.json sidecars
BACKUP_INDEX_NAME	--index-name	{tool}-metadata.json		Index file name; placeholders {tool} {engine} {name} {db}

storage-s3

Variable	Flag	Default	Fallbacks	Description
AWS_S3_ENDPOINT			S3_ENDPOINT (deprecated), AWS_ENDPOINT_URL_S3, AWS_ENDPOINT_URL	S3 endpoint (empty = AWS)
AWS_S3_BUCKET_NAME			BUCKET_NAME (deprecated), AWS_BUCKET_NAME (deprecated)	S3 bucket
AWS_REGION		us-east-1	AWS_DEFAULT_REGION	S3 region
AWS_ACCESS_KEY			ACCESS_KEY (deprecated), AWS_ACCESS_KEY_ID	S3 access key (empty = default AWS credential chain)
AWS_SECRET_KEY			SECRET_KEY (deprecated), AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY_FILE	S3 secret key
AWS_SESSION_TOKEN			AWS_SESSION_TOKEN_FILE	S3 session token
AWS_PROFILE				AWS shared config profile
AWS_DISABLE_SSL				Use http for the S3 endpoint
AWS_FORCE_PATH_STYLE				Path-style S3 addressing (MinIO)
S3_STORAGE_CLASS				S3 storage class
S3_SSE				Server-side encryption: AES256 or aws:kms (aes256, aws:kms)
S3_SSE_KMS_KEY_ID				KMS key id for aws:kms
S3_PART_SIZE		64MiB		Multipart part size; max object size is 10000 x this
S3_UPLOAD_CONCURRENCY		2		Parallel part uploads (memory = part size x this)

storage-sftp

Variable	Flag	Default	Fallbacks	Description
SFTP_HOST				SFTP host
SFTP_PORT		22		SFTP port
SFTP_USER				SFTP user
SFTP_PASSWORD			SFTP_PASSWORD_FILE	SFTP password
SFTP_IDENTITY_FILE				SFTP private key file (the SSH agent is also used when SSH_AUTH_SOCK is set)
SFTP_IDENTITY_PASSPHRASE			SFTP_IDENTITY_PASSPHRASE_FILE	Passphrase of the SFTP private key
SFTP_KNOWN_HOSTS				known_hosts file used to verify the SFTP host key (default ~/.ssh/known_hosts)
SFTP_INSECURE_IGNORE_HOST_KEY				Do not verify the SFTP host key (insecure)

storage-ftp

Variable	Flag	Default	Fallbacks	Description
FTP_HOST			FTP_HOST_NAME (deprecated)	FTP host
FTP_PORT		21		FTP port
FTP_USER				FTP user
FTP_PASSWORD			FTP_PASSWORD_FILE	FTP password
FTP_TLS				Use explicit FTPS

storage-azure

Variable	Flag	Default	Fallbacks	Description
AZURE_STORAGE_ACCOUNT_NAME				Azure storage account
AZURE_STORAGE_ACCOUNT_KEY			AZURE_STORAGE_ACCOUNT_KEY_FILE	Azure storage account key
AZURE_STORAGE_CONTAINER_NAME				Azure blob container
AZURE_STORAGE_ENDPOINT				Azure blob endpoint (Azurite, sovereign clouds)
AZURE_STORAGE_SAS_TOKEN			AZURE_STORAGE_SAS_TOKEN_FILE	Azure SAS token (instead of the account key)

storage-gcs

Variable	Flag	Default	Fallbacks	Description
GCS_BUCKET				GCS bucket
GCS_CREDENTIALS_FILE			GOOGLE_APPLICATION_CREDENTIALS	GCS service account JSON file
GCS_CREDENTIALS_JSON			GCS_CREDENTIALS_JSON_FILE	GCS service account JSON content
GCS_ENDPOINT				GCS endpoint (emulators)

encryption

Variable	Flag	Default	Fallbacks	Description
ENCRYPTION	--encryption	auto		auto (from the keys set), none, gpg or age (auto, none, gpg, age)
ENCRYPTION_ARMOR				ASCII-armor encrypted output
GPG_PASSPHRASE			GPG_PASSPHRASE_FILE	GPG symmetric passphrase
GPG_PUBLIC_KEY				GPG public key(s): file path or inline key (default /config/gnupg/public_key.{asc,gpg})
GPG_PRIVATE_KEY			GPG_PRIVATE_KEY_FILE	GPG private key for restore: file path or inline key (default /config/gnupg/private_key.{asc,gpg})
GPG_PRIVATE_KEY_PASSPHRASE			GPG_PRIVATE_KEY_PASSPHRASE_FILE	Passphrase of the GPG private key (default GPG_PASSPHRASE)
AGE_RECIPIENTS				age recipients (age1..., ssh-ed25519 ...), comma or newline separated
AGE_RECIPIENTS_FILE				File with age recipients
AGE_PASSPHRASE			AGE_PASSPHRASE_FILE	age passphrase (scrypt)
AGE_IDENTITY			AGE_IDENTITY_FILE	age identity (AGE-SECRET-KEY-...) for restore
AGE_IDENTITY_FILE				age identity file for restore (default /config/age/identity.txt)

notifications

Variable	Flag	Default	Fallbacks	Description
MAIL_HOST				SMTP host
MAIL_PORT		587		SMTP port
MAIL_USERNAME				SMTP user
MAIL_PASSWORD			MAIL_PASSWORD_FILE	SMTP password
MAIL_FROM				Sender address
MAIL_TO				Recipients, comma separated
MAIL_SKIP_TLS				Deprecated: true skips certificate verification (use MAIL_INSECURE_SKIP_VERIFY)
MAIL_INSECURE_SKIP_VERIFY				Skip SMTP certificate verification
MAIL_TLS		starttls		SMTP TLS mode (starttls, tls, none)
TG_TOKEN			TELEGRAM_BOT_TOKEN, TG_TOKEN_FILE	Telegram bot token
TG_CHAT_ID			TELEGRAM_CHAT_ID	Telegram chat id
POSTA_URL				Posta base URL (https://posta.example.com) for email notifications through Posta
POSTA_API_KEY			POSTA_API_KEY_FILE	Posta API key with the send scope
POSTA_WORKSPACE_ID				Posta workspace id (only for account-wide API keys)
POSTA_FROM				Posta sender address (default MAIL_FROM)
POSTA_TO				Posta recipients, comma separated (default MAIL_TO)
POSTA_TEMPLATE				Posta template name for notifications; the event fields are passed as template data (default: built-in HTML)
POSTA_TEMPLATE_ERROR				Posta template name for failures (default POSTA_TEMPLATE)
POSTA_LANGUAGE				Posta template language
WEBHOOK_URL				Generic JSON webhook URL
WEBHOOK_SECRET			WEBHOOK_SECRET_FILE	HMAC-SHA256 secret for the X-Bkup-Signature header
SLACK_WEBHOOK_URL			SLACK_WEBHOOK_URL_FILE	Slack incoming webhook URL
DISCORD_WEBHOOK_URL			DISCORD_WEBHOOK_URL_FILE	Discord webhook URL
NTFY_URL				ntfy topic URL
NTFY_TOKEN			NTFY_TOKEN_FILE	ntfy access token
NOTIFY_ON		always		When to notify (always, failure, success, never)
HEALTHCHECK_PING_URL				healthchecks.io-style URL pinged on start (/start), success and failure (/fail)
BACKUP_REFERENCE				Free text included in notifications
TEMPLATES_DIR		/config/templates		Directory with custom notification templates

database

Variable	Flag	Default	Fallbacks	Description
DB_URL			DB_URL_FILE	Connection URL mysql://user:password@host:port/database?ssl-mode=required (overrides host, port, user, password)
DB_HOST		localhost		Database host (a path starting with / is a Unix socket)
DB_PORT		3306		Database port
DB_NAME	--dbname -d			Database name
DB_USER			DB_USERNAME	Database user
DB_PASSWORD			DB_PASSWORD_FILE	Database password
DB_SSL_MODE		disabled		TLS mode: disabled, preferred, required, verify_ca, verify_identity (1.x values 0 and 1 mean disabled and required)
DB_SSL_CA		/etc/ssl/certs/ca-certificates.crt		CA certificate file, used with DB_SSL_MODE=verify_ca or verify_identity
DB_SSL_CERT				Client certificate file
DB_SSL_KEY				Client key file
BACKUP_ALL_DATABASES	--all-databases -a			Back up every database, one file each
BACKUP_ALL_IN_ONE	--all-in-one -A			Back up every database into a single file
BACKUP_EXCLUDE_DATABASES	--exclude-db			Databases to skip with --all-databases, comma separated
TARGET_DB_URL			TARGET_DB_URL_FILE	migrate: target connection URL
TARGET_DB_HOST				migrate: target host
TARGET_DB_PORT		3306		migrate: target port
TARGET_DB_NAME				migrate: target database (default: the source name)
TARGET_DB_USER			TARGET_DB_USERNAME	migrate: target user
TARGET_DB_PASSWORD			TARGET_DB_PASSWORD_FILE	migrate: target password
TARGET_DB_SSL_MODE		disabled		migrate: target TLS mode (same values as DB_SSL_MODE)
TARGET_DB_SSL_CA		/etc/ssl/certs/ca-certificates.crt		migrate: target CA certificate file
MYSQL_CLIENT		auto		Client tools: auto (mariadb-dump for MariaDB, Oracle mysqldump for MySQL), mysql or mariadb (auto, mysql, mariadb)
RESTORE_NO_DEFINER		auto		Remove DEFINER clauses on restore (views, triggers, routines and events then belong to the restoring user); auto = when that user lacks SET_USER_ID/SUPER (auto, true, false)

Scheduled Backups

Running in Scheduled Mode

• Docker: Use the --cron-expression flag or the BACKUP_CRON_EXPRESSION environment variable to schedule backups.
• Kubernetes: Use a CronJob resource for scheduled backups.

Cron Syntax

The cron syntax consists of five fields (a sixth, leading seconds field is also accepted):

* * * * * command

Field	Description	Values
Minute	Minute of the hour	0-59
Hour	Hour of the day	0-23
Day of Month	Day of the month	1-31
Month	Month of the year	1-12
Day of Week	Day of the week (0 = Sunday)	0-7

Examples

• Every 30 minutes: */30 * * * *
• Every hour at minute 0: 0 * * * *
• Every day at 1:00 AM: 0 1 * * *

Predefined Schedules

Entry	Description	Equivalent To
@yearly (or @annually)	Run once a year, midnight, Jan. 1st	0 0 1 1 *
@monthly	Run once a month, midnight, first of month	0 0 1 * *
@weekly	Run once a week, midnight between Sat/Sun	0 0 * * 0
@daily (or @midnight)	Run once a day, midnight	0 0 * * *
@hourly	Run once an hour, beginning of hour	0 * * * *

Intervals

You can also schedule backups at fixed intervals using the format:

@every <duration>

• Example: @every 1h30m10s runs the backup every 1 hour, 30 minutes, and 10 seconds.