HOLLAND(1)

📦

version 1.3.1 · 2 versions

1.3.1 · epel 9 (latest)
1.3.1 · epel 10

, in epel 9

💖 NAME 💖

holland — Holland Documentation, bestie. That’s the whole manual vibe, and we’re diving in 💅

🌸 TABLE OF CONTENTS 🌸

okay so the whole map is below, bestie — same sections, same order, no cap.

💖 Introduction to Holland 💖

Holland is an Open Source backup framework originally developed by Rackspace and written in Python. Its goal is to help facilitate backing up databases with greater configurability, consistency, and ease. Holland currently focuses on MySQL, however future development will include other database platforms and even non-database related applications. Because of its plugin structure, Holland can be used to backup anything you want by whatever means you want.

🚨 Important vibe check: Python2 support has been removed as of holland 1.2.0.

🦋 Dependencies 🦋

The core Holland framework has the following dependencies (available on any remotely modern Linux distribution):

Python >= 3.6
pkg_resources
python-setuptools
ConfigParser

MySQL based plugins additionally require the MySQLdb python connector:

pyMySQL

Note that other plugins may have additional dependency requirements.

👑 Holland Command-Line Reference 👑

Here are the commands available from the 'holland' command-line tool:

✨ help (h) ✨

Usage:

holland <command> --help(-h)

Provides basic information about the provided command. If no command is provided, it displays global help instead.

✨ backup (bk) ✨

Usage:

holland backup [backup-set1, backup-set2, ..., backup-setN]

Runs the backup operation. If no backup-sets are specified, all active backup-sets (those defined in the 'backupsets' variable in holland.conf) are backed up.

One or more backup-sets can be specified directly, in which case only those backup-sets are backed up.

Additional Command Line Arguments:

--dry-run (-n) — Can be used here to simulate, but not actually run, a backup. This should be used when troubleshooting a particular error before trying to run a real backup.
--no-lock (-f) — Normally, only one instance of Holland can run at any given time using lock-files. Using this flag causes the lock-files to be ignored. This has some very clear use-cases but otherwise be mindful of using this setting as it can cause backups to fail in some cases.
--abort-immediately — abort on the first backup-set that fails (assuming multiple backupsets were specified)

Examples:

# holland bk --dry-run weekly: Attempts a dry-run of the weekly backup-set.

# holland bk --no-lock --abort-immediately: Attempts a backup of all the
default backup-sets ignoring locks and aborting immediately if one of the
backup-sets fails.

✨ list-backups (lb) ✨

Usage:

holland list-backups

Provides extended information about available backups.

✨ list-plugins (lp) ✨

Usage:

holland list-plugins

Lists all the available (installed) plugins available to Holland.

✨ mk-config (mc) ✨

Usage:

holland mk-config <provider>

Generates a template backup-set for a particular provider (such as mysqldump). By default, the output is sent to standard out but can be copied to a file, either by using the --file, --edit, or -name options (see below).

Additional Command Line Arguments:

--edit — Load the file into the system text-editor for further modifications.
--file=FILE (-f) — Write the output directly to provided file.
--name=NAME — Creates a backup-set usable in Holland, which basically means that a file is created of the provided name under the backup-set directory.
--provider — Indicates that the default provider configuration should be outputted instead. This is really only used when creating a provider config specifically - it should not be used for backup-sets.

Examples:

# holland mk-config mysql-lvm > mysql-lvm.conf: Output the default
configuration for MySQL-LVM backups and write the contents out to
mysql-lvm.conf in the current working directory.

# holland mc mysqldump --name=Bob --edit: Create a backup-set using the
mysqldump provider named Bob and allow interactive editing of the
backup-set before saving the file.

✨ purge (pg) ✨

Usage:

holland purge <backup-set>/<backup-id>

Purges old backups by specifying the backup-set name and set-id.

For example:

# holland purge mybackups/20090502_155438: Purge one of the backups taken on May 2nd, 2009 from the mybackups backup-set.

🌈 Usage and Implementation Overview 🌈

Because Holland is very pluggable, it may first seem a bit confusing when it comes to configuring Holland to do something useful. Out of the box, Holland is designed to backup MySQL databases using the mysqldump provider. This is the simplest setup, and may be sufficient for most people. However, others may wish to have more fine-grained control over their backups and/or use another method other than mysqldump.

For instance, one can configure a backup set to backup certain databases using mysqldump, others using the mysql-lvm plugins etc. All this is done by a mix of providers and backup-sets.

🎀 Backup-Sets 🎀

Each backup-set implements exactly one provider and will inherit the default values of that provider. These values can be overridden to adjust the behavior of the backup set. This includes defining what databases or tables to include (or exclude) in the backup, the type of compression used (if any), what locking method to use, among other things.

💅 Providers 💅

Providers essentially provide a backup service for use in a backup set.

mysqldump — Uses the mysqldump utility to backup databases.
MySQL + LVM — Backup MySQL databases using LVM snapshots which allows for near lockless or fully lockless (when transactional engines are used) backups.
mysqldump + LVM — This plugin creates an LVM snapshot, starts a mysql instance using the snapshot as its datadir, and then use the mysqldump utility to backup the databases.
XtraBackup — New in version 1.0.8. Backup MySQL databases using Percona's XtraBackup tool. This provides a near lockless backup when using the InnoDB storage engine.
pgdump — Backup PostgreSQL databases using the pgdump utility.
pg_basebackup — New in version 1.2.8. Backup PostgreSQL databases using the pg_basebackup utility.
mariabackup — New in version 1.1.0. Backup MySQL databases using MariaDB's mariabackup tool.
mongodump — New in version 1.1.0. This plugin performs logical backups of a MongoDB by using the mongodump utility.
Example — This is used solely as a template for designing providers. It otherwise does nothing.

As Holland is a framework, it can actually backup most anything as long as there is a provider for it. This includes things that have nothing to do with databases. The idea is to present an easy to use and clear method of backing up and restoring backups no matter the source.

🧚 Holland Config Files 🧚

By default, Holland's configuration files reside in /etc/holland. The main configuration file is holland.conf, however there are a number of other configuration files for configuring default settings for providers and for configuring backup sets.

Each configuration file has one or more sections, defined by square brackets. Underneath each section, one or more configuration option can be specified. These options are in a standard "option = value" format. Comments are prefixed by the # sign.

Note that many settings have default values and, as a result, can either be commented out or omitted entirely.

🍓 holland.conf - main config 🍓

The main configuration file (usually /etc/holland/holland.conf) defines both global settings as well as the active backup sets. It is divided into two sections [holland] and [logging].

💖 [holland] 💖

plugin-dirs — Defines where the plugins can be found. This can be a comma-separated list but usually does not need to be modified.
backup_directory — Top-level directory where backups are held.
backupsets — A comma-separated list of all the backup sets Holland should backup. Each backup set is defined in /etc/holland/backupsets/<name>.conf by default.
umask — Sets the umask of the resulting backup files.
path — Defines a path for holland and its spawned processes

🌸 [logging] 🌸

filename — The log file itself.
level — Sets the verbosity of Holland's logging process. Available options are debug, info, warning, error, and critical
format — Define the format of the log message. This option should be in the format defined by the 'logging' python library. New in version 1.1.0.

💜 Provider Configs 💜

These files control the global settings / defaults for the providers used by the backup-sets. Many of these global settings can be overridden if defined in a backup-set. Note that each provider's configuration file should begin with [provider-name].

🎀 mysqldump Provider Configuration [mysqldump] 🎀

Backs up a MySQL database using the mysqldump tool.

🦋 [mysqldump] 🦋

mysql-binpath = /path/to/mysql/bin — Defines the location of the MySQL binary utilities. If not provided, Holland will use whatever is in the path.
lock-method = flush-lock | lock-tables | single-transaction | auto-detect | none — Defines which lock method to use. By default, auto-detect will be used.
- flush-lock — flush-lock will place a global lock on all tables involved in the backup regardless of whether or not they are in the backup-set. If file-per-database is enabled, then flush-lock will lock all tables for every database being backed up. In other words, this option may not make much sense when using file-per-database.
- lock-tables — lock-tables will lock all tables involved in the backup. If file-per-database is enabled, then lock-tables will only lock all the tables associated with that database.
- single-transaction — Forces the use of --single-transaction which enables semi-transparent backups of transactional tables. Forcing this can cause inconsistencies with non-transactional tables, however. While non-transactional tables will still lock, they will only lock when they are actually being backed up. Use this setting with extreme caution when backing non-transactional tables.
- auto-detect — Let Holland decide which option to use by checking to see if a database or backup-set only contains transactional tables. If so, --single-transaction will be used. Otherwise, --lock-tables will be used.
none — literally does absolutely no explicit locking when backing up the databases or backup-set. This should only be used when backing up a slave, and only after the slave has been turned off (ie, this can be used with the stop-slave option). 💀
exclude-invalid-views = yes | no (default: no) — whether to automate exclusion of invalid views that would otherwise cause mysqldump to fail. Heads up: this adds additional overhead, so this option is not enabled by default. ✨ When enabled, this option will scan the INFORMATION_SCHEMA.VIEWS table and execute SHOW FIELDS against each view. If a view is detected as invalid, an ignore-table option will be added to exclude the table. Additionally, the plugin will attempt to save the view definition to invalid_views.sql in the backupset's backup directory. New in version 1.0.8.
dump-routines = yes | no (default: yes) — whether or not to backup routines in the backup set directly. Routines are stored in the mysql database, but it can sometimes be convenient to include them in a backup-set directly. Changed in version 1.0.8: this option now enabled by default. 🫶
dump-events = yes | no — whether or not to dump events explicitly. Like routines, events are stored in the mysql database. Nonetheless, it can sometimes be convenient to include them in the backup-set directly. Note: this feature requires MySQL 5.1 or later. The mysqldump plugin will automatically disable events if the version of mysqldump is too old. Changed in version 1.0.8: this option is now enabled by default. 🌸
stop-slave = yes | no — stops the SQL_THREAD during the backup. This means that writes from the master will continue to spool but will not be replayed. This helps avoid lock wait timeouts among things while still allowing data to be spooled from the master. Note that previous versions of Holland prior to 1.0.6 simply ran a STOP SLAVE instead, which suspends both replication threads. 🌀
bin-log-position = yes | no — record the binary log name and position at the time of the backup. The information provided by this option is collected just before locking the database. Note that if both stop-slave and bin-log-position are enabled, Holland will grab the master binary log name and position at the time of the backup which can be useful in using the backup to create slaves or for point in time recovery using the master's binary log. This information is found within the backup.conf file located in the backup-set destination directory (/var/spool/holland/<backup-set>/<backup> by default). For example:

[mysql:replication]
slave_master_log_pos = 4512
slave_master_log_file = 260792-mmm-agent1-bin-log.000001

flush-logs = yes | no — whether or not to run FLUSH LOGS in MySQL with the backup. When FLUSH LOGS is actually executed depends on whether database filtering is being used and whether file-per-database is enabled. Generally speaking, it does not make sense to use flush-logs with file-per-database since the binary logs will not be consistent with the backup. 🔥
file-per-database = yes | no — whether or not to split up each database into its own file. Note that it can be more consistent and efficient to backup all databases into one file, however this means that restoring a single database can be difficult if multiple databases are defined in the backup set. 💾
arg-per-database = JSON object — if file-per-database is enabled, this argument is used to specify mysqldump arguments per database. It takes a JSON object with the database names as keys. Example: {"employee1": "--no-data"} adds the '--no-data' argument to the mysqldump command when backing up the 'employee1' database. New in version 1.0.9. 🎀
additional-options = <mysqldump argument>[, <mysqldump argument>] — can optionally specify additional options directly to mysqldump if there is no native Holland option available. This option accepts a comma delimited list of arguments to pass on the commandline. 🧚
extra-defaults = yes | no (default: no) — this option controls whether mysqldump will only read options as set by holland or if additional options from global config files are read. By default, the plugin only uses options as set in the backupset config and includes authentication credentials only from the [client] section in ~/.my.cnf. 👑
estimate-method = plugin | const:<size> (default: plugin) — this option will skip some of the heavyweight queries necessary to calculate the size of tables to be backed up. If a constant size is specified, then only table names are evaluated and only if table filtering is being used. Valid units for size are: K, M, G, T, P, E (case-insensitive). Additionally, engines will be looked up via SHOW CREATE TABLE if lock-method = auto-detect, in order for the plugin to determine if tables are using a transactional storage engine. With plugin, the default behavior of reading both size information and table names from the information schema is used, which may be slow particularly for a large number of tables. ⭐

🗂️ Database and Table filtering

databases = <glob>
exclude-databases = <glob>
tables = <glob>
exclude-tables = <glob>

The above options accept GLOBs in comma-separated lists. Multiple filtering options can be specified. When filtering on tables, be sure to include both the database and table name. 🦋

Be careful with quotes. Normally these are not needed, but when quotes are necessary, be sure to only quote each filtering statement, as opposed to putting quotes around all statements. iykyk 💅

Below are a few examples of how these can be applied:

Default (backup everything):

databases = *
tables = *

Using database inclusion and exclusions:

databases = drupal*, smf_forum,
exclude-databases = drupal5

Including Tables:

tables = phpBB.sucks, drupal6.node*, smf_forum.*

Excluding Tables:

exclude-tables = mydb.uselesstable1, x_cart.*, *.sessions

🗜️ [compression]

Specify various compression settings, such as compression utility, compression level, etc. 🎀

method = gzip| gzip-rsyncable | pigz | bzip2 | pbzip2 | lzop | lzma | gpg | zstd — define which compression method to use. Note that some methods may not be available by default on every system and may need to be compiled or installed. For gpg compression, a key should already exist (gpg --gen-key) and default-recipient must be configured in ~/.gnupg/gpg.conf. 🔐
inline = yes | no — whether or not to pipe the output of the backup command into the compression utility. Enabling this is recommended since it usually only marginally impacts performance, particularly when using a lower compression level. 🌈
level = 0-9 — specify the compression ratio. The lower the number, the lower the compression ratio, but the faster the backup will take. Generally, setting the level to 1 or 2 results in favorable compression of textual data and is noticeably faster than the higher levels. Setting the level to 0 effectively disables compression. ⚡
bin-path = <full path to utility> — this only needs to be defined if the compression utility is not in the usual places or not in the system path. 📍
options = <string> — add commandline options to the configuration compression command. Example: options = "-Q4" 🎯
split = yes | no — defaults to no. If set, the backup will be piped through the split command. This may be useful for users with large databases, as some backup systems perform better with many smaller files instead of 1 large one. This defaults to 1GB file size, so this option isn't helpful if your dumps are smaller than that. For python2.6, this option will be disabled if the subprocess32 module isn't available. New in version 1.1.13. 🍓

🔌 MySQL connection info [mysql:client]

These are optional and, if left undefined, Holland will try to login using the standard .my.cnf conventions. 🫶

user = <user> — the user to connect to MySQL as.
password = <password> — the password for the MySQL user.
socket = <socket> — the socket file to connect to MySQL with.
host = <host> — this would be used for connecting to MySQL remotely.
port = <port> — used if MySQL is running on a port other than 3306. 🔌

🧚 MySQL LVM Provider Configuration [mysql-lvm]

Creates an LVM snapshot of a running MySQL instance and performs a binary-based backup with minimal locking. MySQL must be running on an LVM volume with reserved space for snapshots. It is highly recommended that this volume be separate from the one storing the resulting backups. 💜

💾 [mysql-lvm]

snapshot-size = <size-in-MB> — the size of the snapshot itself. By default it is 20% of the size of the MySQL LVM mount or the remaining free-space in the Volume Group (if there is less than 20% available) up to 15GB. If snapshot-size is defined, the number represents the size of the snapshot in megabytes. 📏
snapshot-name = <name> — the name of the snapshot, the default being the name of the MySQL LVM volume + _snapshot (ie Storage-MySQL_snapshot). 🏷️
snapshot-mountpoint = <path> — where to mount the snapshot. By default a randomly generated directory under /tmp is used. 📂
innodb-recovery = yes | no (default: no) — whether or not to run an InnoDB recovery operation. This avoids needing to do so during a restore, though will make the backup process itself take longer. 🐢
force-innodb-backup = yes | no (default: no) — whether to attempt a backup even if the mysql-lvm plugin thinks it cannot obtain a good backup. This can occur when innodb data files are outside of the mysql datadir or exist on entirely separate logical volumes. 💪
lock-tables = yes | no (default: yes) — whether or not to run a FLUSH TABLES WITH READ LOCK to grab various bits of information (such as the binary log name and position). Disabling this requires that binary logging is disabled and InnoDB is being used exclusively. Otherwise, it is possible that the backup could contain crashed tables. 🔒
extra-flush-tables = yes | no (default: yes) — whether or not to run a FLUSH TABLES before running the full FLUSH TABLES WITH READ LOCK. Should make the FLUSH TABLES WITH READ LOCK operation a bit faster. 🧼
archive-method = tar | dir (default: tar) — create a tar file of the datadir, or just copy it. 📦

📦 [tar]

exclude = pattern[, pattern...]

so, patterns to exclude from the archive 🚫 these should be relative paths, and they're almost always relative to the mysql data directory. like, if you wanna keep the binary logs in the data directory out of your backup, you'd write something like:

exclude = ./bin-log.*, mysql.sock

pre-args = <string> — extra arguments to append to the tar commandline before the backup path is specified. this should be the full string exactly as you might specify on the commandline. shell globbing is not supported 🙅 for instance you might add the /etc/my.cnf to the tar archive via:

pre-args = -C /etc ./my.cnf

post-args = <string> — extra arguments to append to the tar commandline after the backup path is specified. this should be a string exactly as you might specify on the commandline. shell globbing is not evaluated. periodt 💅

✨ `[compression]`

specify various compression settings, such as compression utility, compression level, etc. the whole vibe 🎀

method = gzip| gzip-rsyncable | pigz | bzip2 | pbzip2 | lzop | lzma | gpg | zstd — define which compression method to use. note that some methods may not be available by default on every system and may need to be compiled or installed 😭 for gpg compression, a key should already exist (gpg --gen-key) and default-recipient must be configured in ~/.gnupg/gpg.conf.
inline = yes | no — whether or not to pipe the output of the backup command into the compression utility. enabling this is recommended since it usually only marginally impacts performance, particularly when using a lower compression level. it's giving free efficiency 🫶
level = 0-9 — specify the compression ratio. the lower the number, the lower the compression ratio, but the faster the backup will take. generally, setting the level to 1 or 2 results in favorable compression of textual data and is noticeably faster than the higher levels. setting the level to 0 effectively disables compression. no cap.
bin-path = <full path to utility> — this only needs to be defined if the compression utility is not in the usual places or not in the system path.
options = <string> — add commandline options to the configuration compression command.

options = "-Q4"

split = yes | no — defaults to no. if set the backup will be piped through the split command. this may be useful for user's with large databases, as some backup systems perform better with many smaller files instead of 1 large one. this defaults to 1GB file size, so this option isn't helpful if your dumps are smaller than that. for python2.6, this option will be disabled if the subprocess32 module isn't available. New in version 1.1.13.

🐬 MySQL connection info `[mysql:client]`

these are optional and, if left undefined, Holland will try to login using the standard .my.cnf conventions. lowkey convenient 💖

user = <user> the user to connect to MySQL as.
password = <password> the password for the MySQL user.
socket = <socket> the socket file to connect to MySQL with.
host = <host> this would be used for connecting to MySQL remotely.
port = <port> used if MySQL is running on a port other than 3306.

🌈 mysqldump LVM Provider Configuration `[mysqldump-lvm]`

backs up one or more MySQL databases by creating an LVM snapshot and then starting a instance of MySQL on top of it to then perform a mysqldump. this effectively produces a non-blocking logical backup. iconic behaviour, honestly 👑

🦋 `[mysql-lvm]`

snapshot-size = <size-in-MB> — the size of the snapshot itself. by default it is 20% of the size of the MySQL LVM mount or the remaining free-space in the Volume Group (if there is less than 20% available) up to 15GB. if snapshot-size is defined, the number represents the size of the snapshot in megabytes.
snapshot-name = <name> — the name of the snapshot, the default being the name of the MySQL LVM volume + "_snapshot" (ie Storage-MySQL_snapshot).
snapshot-mountpoint = <path> — where to mount the snapshot. by default a randomly generated directory under /tmp is used 🙈
innodb-recovery = yes | no (default: no) — whether or not to run an InnoDB recovery operation. this avoids needing to do so during a restore, though will make the backup process itself take longer. trade-offs, bestie 😭
lock-tables = yes | no (default: yes) — whether or not to run a FLUSH TABLES WITH READ LOCK to grab various bits of information (such as the binary log name and position). disabling this requires that binary logging is disabled and InnoDB is being used exclusively. otherwise, it is possible that the backup could contain crashed tables 💀 not the vibe.
extra-flush-tables = yes | no (default: yes) — whether or not to run a FLUSH TABLES before running the full FLUSH TABLES WITH READ LOCK. should make the FLUSH TABLES WITH READ LOCK operation a bit faster. little speed boost, we love to see it ✨

🌸 `[mysqld]`

mysqld-exe = <path>[, <path>...] (default: mysqld in PATH, /usr/libexec/mysqld) — this provides a list of locations where the mysqld process to use might be found. this is searched in order of entries in this list.
user = <name> — the --user parameter to use with mysqld.
innodb-buffer-pool-size = <size> (default: 128M) — how large to size the innodb-buffer-pool-size.
tmpdir = <path> (default: system tempdir) — path to the --tmpdir that mysqld should use.
log-error = <path> (default: tempdir/holland_lvm.log) — define path for mysqld's error log. the default location get cleaned up by Holland after the backup is complete. this settings allows the user to define the log file in another location and can be useful for debugging issue with the MySQL instance running on the snapshot. honestly a lifesaver for debugging 🧚 New in version 1.0.9.

🎀 `[mysqldump]`

mysqldump-lvm supports almost all of the options from the mysqldump plugin. --master-data is not supported, as the mysqld process will not read binary logs, so this plugin will automatically disable bin-log-position, if set.

binary log information from SHOW MASTER STATUS and SHOW SLAVE STATUS is recorded in the ${backup_directory}/backup.conf file under the [mysql:replication] section 📝

💜 `[compression]`

specify various compression settings, such as compression utility, compression level, etc. (yep — the page really does print this block twice, so here it is again, no skipping 💅)

method = gzip| gzip-rsyncable | pigz | bzip2 | pbzip2 | lzop | lzma | gpg | zstd — define which compression method to use. note that some methods may not be available by default on every system and may need to be compiled or installed. for gpg compression, a key should already exist (gpg --gen-key) and default-recipient must be configured in ~/.gnupg/gpg.conf.
inline = yes | no — whether or not to pipe the output of the backup command into the compression utility. enabling this is recommended since it usually only marginally impacts performance, particularly when using a lower compression level.
level = 0-9 — specify the compression ratio. the lower the number, the lower the compression ratio, but the faster the backup will take. generally, setting the level to 1 or 2 results in favorable compression of textual data and is noticeably faster than the higher levels. setting the level to 0 effectively disables compression.
bin-path = <full path to utility> — this only needs to be defined if the compression utility is not in the usual places or not in the system path.
options = <string> — add commandline options to the configuration compression command.

options = "-Q4"

split = yes | no — defaults to no. if set the backup will be piped through the split command. this may be useful for user's with large databases, as some backup systems perform better with many smaller files instead of 1 large one. this defaults to 1GB file size, so this option isn't helpful if your dumps are smaller than that. for python2.6, this option will be disabled if the subprocess32 module isn't available. New in version 1.1.13.

🫶 `[mysql:client]`

these are optional and, if left undefined, Holland will try to login using the standard .my.cnf conventions.

user = <user> the user to connect to MySQL as.
password = <password> the password for the MySQL user.
socket = <socket> the socket file to connect to MySQL with.
host = <host> this would be used for connecting to MySQL remotely.
port = <port> used if MySQL is running on a port other than 3306.

🔥 Xtrabackup Provider Configuration `[xtrabackup]`

backs up a MySQL instance using Percona's Xtrabackup tool. main character energy fr 🔥

🌟 `[xtrabackup]`

global-defaults = <path> (default: /etc/my.cnf) — the MySQL configuration file for xtrabackup to parse. this is !include'd into the my.cnf the xtrabackup plugin generates.
innobackupex = <name> (default: innobackupex-1.5.1) — the path to the innobackupex script to run. if this is a relative path this will be found in holland's environment PATH as configured in /etc/holland/holland.conf. Changed in version 1.1.12: for xtrabackup version 8.0 or greater, this option is ignored.
ibbackup = <name> — the path to the ibbackup command to use. by default, no --ibbackup option is passed to the innobackupex script. usually innobackupex will detect this by itself and this should not need to be set.
stream = tar|xbstream|yes|no (default: xbstream) — whether to generate a streaming backup. Changed in version 1.0.8: 'tar' and 'xbstream' are now valid options. the old stream = yes is now equivalent to stream = tar and stream = no disables streaming entirely and will result in a normal directory copy with xtrabackup. Changed in version 1.1.12: for xtrabackup version 8.0 or greater, 'xbstream' will be used unless this value is set to 'no'. Changed in version 1.3.0: the default stream method has switched from tar to xbstream.
apply-logs = yes | no (default: yes) — whether to run innobackupex --apply-logs at the end of the backup. this is only supported when performing a non-streaming, non-compressed backup. in this case, even if apply-logs = yes (the default), the prepare stage will be skipped. even with an uncompressed, non-streaming backup you may want to disable apply-logs if you wish to use incremental backups. read that twice bestie, it's a whole tangle 😭 New in version 1.0.8.
slave-info = yes | no (default: yes) — whether to enable the --slave-info innobackupex option.
safe-slave-backup = yes | no (default: yes) — whether to enable the --safe-slave-backup innobackupex option.
no-lock = yes | no (default: no) — whether to enable the --no-lock innobackupex option.
tmpdir = <path> (default: ${backup_directory}) — the path for the innobackupex --tmpdir option. by default this will use the current holland backup directory to workaround the following bug: https://bugs.launchpad.net/percona-xtrabackup/+bug/1007446 🙈

🆕 New in version 1.0.8.

additional-options = <option>[, <option>...] — a whole list of extra flags you wanna hand off to innobackupex, fr fr. It's a comma separated list, so just line 'em up with commas between and you're golden 💅
pre-command = <command-string> — a command that runs before this xtrabackup run kicks off. Like, say you wanna generate a mysqldump schema dump first and then let xtrabackup do its thing — this is your moment ✨. Any instances of ${backup_directory} and ${backupdir} inside it get swapped out for the current holland backup directory, aka the place where the xtrabackup data is gonna live.
strict = yes | no (default: yes) — if you set strict to no, it adds the --strict=OFF option onto the xtrabackup command. The strict option in xtrabackup is the thing that blocks errors and warnings over invalid command line options, so yeah — turning it off is a choice, bestie 😭

🆕 New in version 1.2.10.

[compression] 🎀

All your squish settings live here — which compression utility, what compression level, the whole vibe check.

method = gzip| gzip-rsyncable | pigz | bzip2 | pbzip2 | lzop | lzma | gpg | zstd — picks which compression method we're using. Heads up tho: some of these methods might not be available by default on every system, and might need to be compiled or installed first. Not all of them are just sitting there, yk?

For gpg compression, a key should already exist (via gpg --gen-key) and default-recipient must be configured in ~/.gnupg/gpg.conf. That's a you-problem, prep it ahead of time 🔑

inline = yes | no — whether or not to pipe the output of the backup command straight into the compression utility. Enabling this is recommended — it usually only marginally impacts performance, especially when you're running a lower compression level. Highkey free real estate 💖
level = 0-9 — sets the compression ratio. Lower number = lower compression ratio = faster backup. Generally 1 or 2 gives you favorable compression of textual data and is noticeably faster than the higher levels. And 0 effectively disables compression entirely, so like... nothing. Zero squish 🫠
bin-path = <full path to utility> — only define this if your compression utility isn't in the usual places or not in the system path. Otherwise ignore it, she's fine 🌸
options = <string> — toss commandline options onto the compression command from your config.

options = "-Q4"

split = yes | no — defaults to no. If you set it, the backup gets piped through the split command. This can be useful for people with large databases, since some backup systems perform better with many smaller files instead of 1 large one. It defaults to a 1GB file size, so this option isn't helpful if your dumps are smaller than that. Sorry to the small-dump girlies 💀

For python2.6, this option will be disabled if the subprocess32 module isn't available.

🆕 New in version 1.1.13.

MySQL connection info [mysql:client] 🦋

These are all optional, and if you leave them undefined, Holland will try to login using the standard .my.cnf conventions. So like, she'll figure it out 🌈

user = <user>

The user to connect to MySQL as.

password = <password>

The password for the MySQL user.

socket = <socket>

The socket file to connect to MySQL with.

host = <host>

This would be used for connecting to MySQL remotely.

port = <port>

Used if MySQL is running on a port other than 3306.

pgdump Provider Configuration [pgdump] 🐘

Backs up a PostgreSQL instance using the pgdump utility. Slay.

[pgdump]

format = custom | tar | plain (default: custom) — defines the --format option for pg_dump. This defaults to --format=custom. The custom format is required for pg_restore to do partial restore as well as enabling parallel restores. If set to custom, the --compress option will be passed to pgdump. Custom really is the main character here 👑
additional-options = <command-string> — pass additional options to the pg_dump command.

⚠️ Only the 'level' option will be used if 'format=custom'.

[compression] 🎀

Specify various compression settings, such as compression utility, compression level, etc. (yes, again — every provider gets its own lil compression corner 💅)

method = gzip| gzip-rsyncable | pigz | bzip2 | pbzip2 | lzop | lzma | gpg | zstd — define which compression method to use. Note that some methods may not be available by default on every system and may need to be compiled or installed.

For gpg compression, a key should already exist (gpg --gen-key) and default-recipient must be configured in ~/.gnupg/gpg.conf.

inline = yes | no — whether or not to pipe the output of the backup command into the compression utility. Enabling this is recommended since it usually only marginally impacts performance, particularly when using a lower compression level.
level = 0-9 — specify the compression ratio. The lower the number, the lower the compression ratio, but the faster the backup will take. Generally, setting the level to 1 or 2 results in favorable compression of textual data and is noticeably faster than the higher levels. Setting the level to 0 effectively disables compression.
bin-path = <full path to utility> — this only needs to be defined if the compression utility is not in the usual places or not in the system path.
options = <string> — add commandline options to the configuration compression command.

options = "-Q4"

split = yes | no — defaults to no. If set, the backup will be piped through the split command. This may be useful for user's with large databases, as some backup systems perform better with many smaller files instead of 1 large one. This defaults to 1GB file size, so this option isn't helpful if your dumps are smaller than that.

For python2.6, this option will be disabled if the subprocess32 module isn't available.

🆕 New in version 1.1.13.

[pgauth] 🔐

username = <name> — username for pg_dump to authenticate with.
password = <string> — password for pg_dump to authenticate with.
hostname = <string> — hostname for pg_dump to connect with.
port = <integer> — TCP port for pg_dump to connect on.

pg_basebackup Provider Configuration [pg_basebackup] 🐘✨

Backs up a PostgreSQL instance using the pg_basebackup utility.

[pg_basebackup]

format = tar | plain (default: tar) — defines the --format option for pg_basebackup.
wal-method = none | fetch | plain (default: fetch) — defines the --wal-method used for pg_basebackup.
checkpoint = none | fast | spread (default: fast) — defines the --checkpoint used for pg_basebackup.
additional-options = <command-string> (default: none) — pass additional options to the pg_basebackup command. This will expand backup_directory/backupdir variables. 🫶

[compression] 🎀

Specify various compression settings, such as compression utility, compression level, etc.

method = gzip| gzip-rsyncable | pigz | bzip2 | pbzip2 | lzop | lzma | gpg | zstd — define which compression method to use. Note that some methods may not be available by default on every system and may need to be compiled or installed.

For gpg compression, a key should already exist (gpg --gen-key) and default-recipient must be configured in ~/.gnupg/gpg.conf.

inline = yes | no — whether or not to pipe the output of the backup command into the compression utility. Enabling this is recommended since it usually only marginally impacts performance, particularly when using a lower compression level.
level = 0-9 — specify the compression ratio. The lower the number, the lower the compression ratio, but the faster the backup will take. Generally, setting the level to 1 or 2 results in favorable compression of textual data and is noticeably faster than the higher levels. Setting the level to 0 effectively disables compression.
bin-path = <full path to utility> — this only needs to be defined if the compression utility is not in the usual places or not in the system path.
options = <string> — add commandline options to the configuration compression command.

options = "-Q4"

split = yes | no — defaults to no. If set, the backup will be piped through the split command. This may be useful for user's with large databases, as some backup systems perform better with many smaller files instead of 1 large one. This defaults to 1GB file size, so this option isn't helpful if your dumps are smaller than that.

For python2.6, this option will be disabled if the subprocess32 module isn't available.

🆕 New in version 1.1.13.

[pgauth] 🔐

username = <name> — username for pg_basebackup to authenticate with.
password = <string> — password for pg_basebackup to authenticate with.
hostname = <string> — hostname for pg_basebackup to connect with.
port = <integer> — TCP port for pg_basebackup to connect on.

mongodump Provider Configuration [mongodump] 🍃

This plugin performs logical backups of a MongoDB by using the mongodump utility. Cute, efficient, iconic.

[mongodump]

host = <string> — hostname for mongodump to connect with.
username = <name> — username for mongodump to authenticate with.
password = <string> — password for mongodump to authenticate with.
port = <integer> — TCP port for mongodump to connect on.
uri = <string> — use a connection string instead of a host, username, and password. One string to rule them all 🔥

🆕 New in version 1.1.14.

[compression] 🎀

Specify various compression settings, such as compression utility, compression level, etc.

method = gzip| gzip-rsyncable | pigz | bzip2 | pbzip2 | lzop | lzma | gpg | zstd — define which compression method to use. Note that some methods may not be available by default on every system and may need to be compiled or installed.

For gpg compression, a key should already exist (gpg --gen-key) and default-recipient must be configured in ~/.gnupg/gpg.conf.

inline = yes | no — whether or not to pipe the output of the backup command into the compression utility. Enabling this is recommended since it usually only marginally impacts performance, particularly when using a lower compression level.
level = 0-9 — specify the compression ratio. The lower the number, the lower the compression ratio, but the faster the backup will take. Generally, setting the level to 1 or 2 results in favorable compression of textual data and is noticeably faster than the higher levels. Setting the level to 0 effectively disables compression.
bin-path = <full path to utility> — this only needs to be defined if the compression utility is not in the usual places or not in the system path.
options = <string> — add commandline options to the configuration compression command.

options = "-Q4"

split = yes | no — The default is no. If you set it, the backup gets piped through the split command. This can be a whole vibe for users with large databases, because some backup systems perform better with many smaller files instead of 1 large one. It defaults to a 1GB file size, so this option isn’t helpful if your dumps are smaller than that.

For python2.6, this option will be disabled if the subprocess32 module isn’t available.

New in version 1.1.13.

🦋 Mariabackup Provider Configuration [mariabackup] 🦋

Backs up a MySQL instance using mariabackup tool.

💜 `[mariabackup]` 💜

global-defaults = <path> (default: /etc/my.cnf) — The MySQL configuration file for mariabackup to parse. This is !include'd into the my.cnf the mariabackup plugin generates.
innobackupex = <name> (default: innobackupex-1.5.1) — The path to the innobackupex script to run. If this is a relative path, this will be found in holland’s environment PATH as configured in /etc/holland/holland.conf.
ibbackup = <name> — The path to the ibbackup command to use. By default, no --ibbackup option is passed to the innobackupex script. Usually innobackupex will detect this by itself and this should not need to be set.
stream = mbstream (default: mbstream) — Placeholder.
apply-logs = yes | no (default: yes) — Whether to run innobackupex --apply-logs at the end of the backup. This is only supported when performing a non-streaming, non-compressed backup. In this case, even if apply-logs = yes (the default), the prepare stage will be skipped. Even with an uncompressed, non-streaming backup you may want to disable apply-logs if you wish to use incremental backups.
slave-info = yes | no (default: yes) — Whether to enable the --slave-info innobackupex option.
safe-slave-backup = yes | no (default: yes) — Whether to enable the --safe-slave-backup innobackupex option.
no-lock = yes | no (default: no) — Whether to enable the --no-lock innobackupex option.
tmpdir = <path> (default: ${backup_directory}) — The path for the innobackupex --tmpdir option.
additional-options = <option>[, <option>...] — A list of additional options to pass to innobackupex. This is a comma separated list of options.
pre-command = <command-string> — A command to run prior to running this mariabackup run. This can be used, for instance, to generate a mysqldump schema dump prior to running mariabackup. Instances of ${backup_directory} and ${backupdir} will be replaced with the current holland backup directory where the mariabackup data will be stored.

🎀 `[compression]` 🎀

Specify various compression settings, such as compression utility, compression level, etc.

method = gzip| gzip-rsyncable | pigz | bzip2 | pbzip2 | lzop | lzma | gpg | zstd — Define which compression method to use. Note that some methods may not be available by default on every system and may need to be compiled or installed.

For gpg compression, a key should already exist(gpg --gen-key) and default-recipient must be configured in ~/.gnupg/gpg.conf.

inline = yes | no — Whether or not to pipe the output of the backup command into the compression utility. Enabling this is recommended since it usually only marginally impacts performance, particularly when using a lower compression level.
level = 0-9 — Specify the compression ratio. The lower the number, the lower the compression ratio, but the faster the backup will take. Generally, setting the level to 1 or 2 results in favorable compression of textual data and is noticeably faster than the higher levels. Setting the level to 0 effectively disables compression.
bin-path = <full path to utility> — This only needs to be defined if the compression utility is not in the usual places or not in the system path.
options = <string> — Add commandline options to the configuration compression command.

options = "-Q4"

split = yes | no — The default is no. If set, the backup will be piped through the split command. This may be useful for users with large databases, as some backup systems perform better with many smaller files instead of 1 large one. This defaults to 1GB file size, so this option isn’t helpful if your dumps are smaller than that.

For python2.6, this option will be disabled if the subprocess32 module isn’t available.

New in version 1.1.13.

🌈 MySQL connection info [mysql:client] 🌈

These are optional and, if left undefined, Holland will try to login using the standard .my.cnf conventions.

user = <user> — The user to connect to MySQL as.
password = <password> — The password for the MySQL user.
socket = <socket> — The socket file to connect to MySQL with.
host = <host> — This would be used for connecting to MySQL remotely.
port = <port> — Used if MySQL is running on a port other than 3306.

🌸 mariadb-dump Provider Configuration [mariadb-dump] 🌸

Backs up a MariaDB database using the mariadb-dump tool.

🫶 `[mariadb-dump]` 🫶

extra-defaults = yes | no (default: no) — This option controls whether mariadb-dump will only read options as set by holland or if additional options from global config files are read. By default, the plugin only uses options as set in the backupset config and includes authentication credentials only from the [client] section in ~/.my.cnf.
executable = "mariadb-dump" — Override the path where we can find mariadb command line utilities.
lock-method = flush-lock | lock-tables | single-transaction | auto-detect | none (default: auto-detect) — One of: flush-lock, lock-tables, single-transaction, auto-detect, none.
- flush-lock — flush-lock will place a global lock on all tables involved in the backup regardless of whether or not they are in the backup-set. If file-per-database is enabled, then flush-lock will lock all tables for every database being backed up. In other words, this option may not make much sense when using file-per-database.
- lock-tables — lock-tables will lock all tables involved in the backup. If file-per-database is enabled, then lock-tables will only lock all the tables associated with that database.
- single-transaction — single-transaction will force running a backup within a transaction. This allows backing up of transactional tables without imposing a lock however will NOT properly backup non-transactional tables.
- auto-detect — Auto-detect will choose single-transaction unless Holland finds non-transactional tables in the backup-set.
- none — None will completely disable locking. This is generally only viable on a MariaDB slave and only after traffic has been diverted, or slave services suspended.
databases = "*" — List of comma-delimited glob patterns for matching databases. Only databases matching these patterns will be backed up. default: include everything.
exclude-databases = — List of comma-delimited glob patterns to exclude particular databases.
tables = "*" — List of comma-delimited tables to include.
exclude-tables = "" — List of comma-delimited tables to exclude.
engines = "*" — List of comma-delimited glob patterns for matching table engines. Only tables matching these patterns will be backed up. default: include everything.
exclude-engines = — List of comma-delimited glob patterns to exclude particular table engines.
exclude-invalid-views = yes | no (default: no) — Whether to automate exclusion of invalid views that would otherwise cause mariadb-dump to fail. This adds additional overhead so this option is not enabled by default.
flush-logs = yes | no (default: no) — Whether to run FLUSH LOGS in MariaDB with the backup. When FLUSH LOGS is actually executed depends on which if database filtering is being used and whether or not file-per-database is enabled. Generally speaking, it does not make sense to use flush-logs with file-per-database since the binary logs will not be consistent with the backup.
flush-privileges = yes | no (default: yes) — Whether to emit a FLUSH PRIVILEGES statement after dumping the mysql database. This ensures a proper restore when a dump contains the mysql database.
dump-routines = yes | no (default: yes) — Whether to dump routines explicitly. (routines are implicitly included in the mariadb database)
dump-events = yes | no (default: no) — Whether to dump events explicitly.
dump-history = yes | no (default: no) — Whether to dump history explicitly. Requires MariaDB 10.11.0 or later.
order-by-size = yes | no (default: no) — Whether to dump tables in the order of their size, smaller first. Requires MariaDB 10.9.1 or later.
stop-slave = yes | no (default: no) — Whether to stop the slave before commencing with the backup.
bin-log-position = yes | no (default: no) — Whether to record the binary log name and position at the time of the backup.
max-allowed-packet = 128M — Maximum packet length to send/receive from the server.
file-per-database = yes | no (default: yes) — Whether to run a separate mariadb-dump for each database. Note that while this may initially sound like a good idea, it is far simpler to backup all databases in one file, although that makes the restore process more difficult when only certain data needs to be restored.
arg-per-database = {} — The args-per-database option is only used if file-per-database is enabled. It takes a JSON string in the format {"table1": "--arg", "table2": "--arg"}.
additional-options = "" — Any additional options to pass to the mariadb-dump command-line utility. These should show up exactly as they are on the command line. e.g.: --flush-privileges --reset-master.

🦋 Database and Table filtering 🦋

💅 `[compression]` 💅

Specify various compression settings, such as compression utility, compression level, etc.

method = gzip| gzip-rsyncable | pigz | bzip2 | pbzip2 | lzop | lzma | gpg | zstd — Define which compression method to use. Note that some methods may not be available by default on every system and may need to be compiled or installed.

For gpg compression, a key should already exist(gpg --gen-key) and default-recipient must be configured in ~/.gnupg/gpg.conf.

inline = yes | no — the "should we pipe the output of the backup command straight into the compression utility" switch. Turning this on is highly recommended since it usually only marginally impacts performance, particularly when you're running a lower compression level. Free wins only 💅
level = 0-9 — the compression ratio dial. Lower number = lower compression ratio, but the backup will be faster. Generally, setting the level to 1 or 2 results in favorable compression of textual data and is noticeably faster than the higher levels. And setting the level to 0? Effectively disables compression. periodt. 🫶
bin-path = <full path to utility> — you only need to define this if the compression utility isn't in the usual places or isn't in the system path.
options = <string> — adds commandline options to the configuration compression command, bestie. Like this:

options = "-Q4"

split = yes | no — defaults to no. If you set it, the backup gets piped through the split command. This may be useful for users with large databases, since some backup systems perform better with many smaller files instead of 1 large one. It defaults to 1GB file size, so this option isn't helpful if your dumps are smaller than that. For python2.6, this option will be disabled if the subprocess32 module isn't available. New in version 1.1.13. ✨

💖 MySQL connection info `[mysql:client]`

These are optional and, if left undefined, Holland will try to login using the standard .my.cnf conventions. iykyk 🎀

user = <user> — the user to connect to MySQL as.
password = <password> — the password for the MySQL user.
socket = <socket> — the socket file to connect to MySQL with.
host = <host> — this would be used for connecting to MySQL remotely.
port = <port> — used if MySQL is running on a port other than 3306.

🦋 mysqlsh-dump-instance Provider Configuration `[mysqlsh-dump-instance]`

Backs up a MySQL instance using the mysqlsh dump-instance utility. main character provider energy 👑

`[mysqlsh-dump-instance]`

executable = mysqlsh — override the path where we can find the mysqlsh binary.
bin-log-position = yes | no (default: no) — whether to record the binary log name and position at the time of the backup.
estimate-method = plugin — the method to use to estimate the size of the backup.
extra-defaults = yes | no (default: no) — this option controls whether mysqlsh will only read options as set by holland or if additional options from global config files are read. By default, the plugin only uses options as set in the backupset config and includes authentication credentials only from the [client] section in ~/.my.cnf.
log-level = 5 — the log level used for the mysqlsh application log (mysqlsh.log). 1=none, 2=internal, 3=error, 4=warning, 5=info, 6=debug, 7=debug2, or 8=debug3.
stop-slave = yes | no (default: no) — whether to stop the slave before commencing with the backup.
additional-options = , — additional options to pass to the mysqlsh command. When specifying an additional named argument that takes a list of values, you'll want to define the key repeatedly for each item in the list. e.g. --compatibility=strip_definers, --compatibility=strip_restricted_grants
threads = 4 — the number of parallel threads to use to dump chunks of data from the MySQL instance.
max-rate = 0 — the maximum number of bytes per second per thread for data read throughput during the dump. The unit suffixes k for kilobytes, M for megabytes, and G for gigabytes can be used. Setting this to 0 will disable rate limiting. 🏎️
consistent = yes | no (default: yes) — whether to enable consistent data dumps by locking the instance for backup during the dump.
skip-consistency-checks = yes | no (default: no) — whether to skip consistency checks.
tz-utc = yes | no (default: yes) — whether to include a statement at the start of the dump to set the time zone to UTC.
compression = zstd — the compression type to use when writing data files for the dump.
chunking = yes | no (default: yes) — whether to enable chunking of table data.
bytes-per-chunk = 64M — the approximate size of each chunk when chunking is enabled. Requires chunking to be enabled in the backupset config. This option is always specified when holland executes mysqlsh and chunking is enabled.
ddl-only = yes | no (default: no) — whether to only dump the DDL files and exclude the data.
data-only = yes | no (default: no) — whether to only dump the data and exclude the DDL files.
exclude-tables = , — a list of tables to exclude from the dump. Table names must be qualified with a valid schema name and quoted with backticks if needed.
include-tables = , — a list of tables to include in the dump. Table names must be qualified with a valid schema name and quoted with backticks if needed.
events = yes | no (default: yes) — whether to dump events.
exclude-events = , — a list of events to exclude from the dump. Events must be qualified with a valid schema name and quoted with backticks if needed.
include-events = , — a list of events to include in the dump. Events must be qualified with a valid schema name and quoted with backticks if needed.
routines = yes | no (default: yes) — whether to dump routines.
exclude-routines = , — a list of routines to exclude from the dump. Routines must be qualified with a valid schema name and quoted with backticks if needed.
include-routines = , — a list of routines to include in the dump. Routines must be qualified with a valid schema name and quoted with backticks if needed.
triggers = yes | no (default: yes) — whether to dump triggers.
exclude-triggers = , — a list of triggers to exclude from the dump. Triggers must be qualified with a valid schema name and quoted with backticks if needed.
include-triggers = , — a list of triggers to include in the dump. Triggers must be qualified with a valid schema name and quoted with backticks if needed.
users = yes | no (default: yes) — whether to include users and their roles and grants in the dump.
exclude-users = , — a list of users to exclude from the dump.
include-users = , — a list of users to include in the dump.
exclude-schemas = , — a list of schemas to exclude from the dump.
include-schemas = , — a specific list of schemas to include in the dump. You cannot include the information_schema, mysql, ndbinfo, performance_schema, or sys schemas by naming them here. Use the dump-schemas plugin instead. 💀
strip-definers = yes | no (default: no) — whether to enable the strip_definers HeatWave compatibility requirement.
create-invisible-pks = yes | no (default: no) — whether to enable the create_invisible_pks HeatWave compatibility requirement.

💖 MySQL connection info `[mysql:client]`

These are optional and, if left undefined, Holland will try to login using the standard .my.cnf conventions. (yes, same deal as before, she's consistent 💅)

user = <user> — the user to connect to MySQL as.
password = <password> — the password for the MySQL user.
socket = <socket> — the socket file to connect to MySQL with.
host = <host> — this would be used for connecting to MySQL remotely.
port = <port> — used if MySQL is running on a port other than 3306.

🌸 mysqlsh-dump-schemas Provider Configuration `[mysqlsh-dump-schemas]`

Backs up MySQL schemas using the mysqlsh dump-schemas utility. 🎀

`[mysqlsh-dump-schemas]`

Same energy, different provider — but bestie, still every single option:

executable = mysqlsh — override the path where we can find the mysqlsh binary.
bin-log-position = yes | no (default: no) — whether to record the binary log name and position at the time of the backup.
estimate-method = plugin — the method to use to estimate the size of the backup.
extra-defaults = yes | no (default: no) — this option controls whether mysqlsh will only read options as set by holland or if additional options from global config files are read. By default, the plugin only uses options as set in the backupset config and includes authentication credentials only from the [client] section in ~/.my.cnf.
log-level = 5 — the log level used for the mysqlsh application log (mysqlsh.log). 1=none, 2=internal, 3=error, 4=warning, 5=info, 6=debug, 7=debug2, or 8=debug3.
stop-slave = yes | no (default: no) — whether to stop the slave before commencing with the backup.
additional-options = , — additional options to pass to the mysqlsh command. When specifying an additional named argument that takes a list of values, you'll want to define the key repeatedly for each item in the list. e.g. --compatibility=strip_definers, --compatibility=strip_restricted_grants
threads = 4 — the number of parallel threads to use to dump chunks of data from the MySQL instance.
max-rate = 0 — the maximum number of bytes per second per thread for data read throughput during the dump. The unit suffixes k for kilobytes, M for megabytes, and G for gigabytes can be used. Setting this to 0 will disable rate limiting.
consistent = yes | no (default: yes) — whether to enable consistent data dumps by locking the instance for backup during the dump.
skip-consistency-checks = yes | no (default: no) — whether to skip consistency checks.
tz-utc = yes | no (default: yes) — whether to include a statement at the start of the dump to set the time zone to UTC.
compression = zstd — the compression type to use when writing data files for the dump.
chunking = yes | no (default: yes) — whether to enable chunking of table data.
bytes-per-chunk = 64M — the approximate size of each chunk when chunking is enabled. Requires chunking to be enabled in the backupset config. This option is always specified when holland executes mysqlsh and chunking is enabled.
ddl-only = yes | no (default: no) — whether to only dump the DDL files and exclude the data.
data-only = yes | no (default: no) — whether to only dump the data and exclude the DDL files.
exclude-tables = , — a list of tables to exclude from the dump. Table names must be qualified with a valid schema name and quoted with backticks if needed.
include-tables = , — a list of tables to include in the dump. Table names must be qualified with a valid schema name and quoted with backticks if needed.
events = yes | no (default: yes) — whether to dump events.
exclude-events = , — a list of events to exclude from the dump. Events must be qualified with a valid schema name and quoted with backticks if needed.
include-events — a list of events you wanna include in the dump ✨. Every event has to be qualified with a legit schema name, and quoted with backticks if it needs it. no cap.
routines = yes | no (default: yes) — whether to dump routines. that's it, that's the option 💅
exclude-routines — a list of routines to leave out of the dump. Routines must be qualified with a valid schema name and quoted with backticks if needed. bye bestie 👋
include-routines — a list of routines to pull into the dump. Same deal: qualified with a valid schema name, quoted with backticks when needed. 🎀
triggers = yes | no (default: yes) — whether to dump triggers. lowkey important, don't skip it 🔥
exclude-triggers — a list of triggers to exclude from the dump. Qualified with a valid schema name, backticks if needed. 🦋
include-triggers — a list of triggers to include in the dump. Qualified with a valid schema name, backticks if needed. 🫶
schemas — a list of schemas to include in the dump. heads up: this one is required for the dump-schemas provider. like, mandatory mandatory 💀

🌸 MySQL connection info [mysql:client] 🌸

These are optional, and if you leave them undefined, Holland will just try to log in using the standard .my.cnf conventions. comfy defaults, we love to see it 💖

user = <user> — the user to connect to MySQL as.
password = <password> — the password for the MySQL user. yes it's literally called that. keep it secret, keep it safe 🙈
socket = <socket> — the socket file to connect to MySQL with.
host = <host> — this one's for connecting to MySQL remotely. long distance relationship core 🌈
port = <port> — used if MySQL is running on a port other than 3306.

⚡ command Provider Configuration [command] ⚡

Executes custom backup commands. you're the main character here, you write the command 👑

[command]

command = "" (no default) — the command to execute for backing up data. You can inject the Holland backup data directory path by using the {backup_data_dir} placeholder inside the command. That placeholder gets replaced with the actual backup directory path at runtime. Using the placeholder is not required, tho. The backup will fail if the command exits with a non-zero status. Also!! if you're using the before-backup-command, after-backup-command, or failed-backup-command options in your holland:backup section, the backup will also fail if those commands exit with a non-zero status. so many ways to fail, stay vigilant 😭

Examples:

command = "rsync -av /var/lib/mysql/ {backup_data_dir}/"
command = "tar -czf {backup_data_dir}/backup.tar.gz /var/lib/mysql"
command = "cp -r /var/lib/mysql {backup_data_dir}/"

create-backup-data-dir = yes | no (default: no) — whether to create the "backup_data" subdirectory inside the backup directory. If you're using the {backup_data_dir} placeholder in your command, some commands may or may not automatically create this directory (rude, honestly). This option is here as a convenience so the directory definitely exists before the command runs. girl scout promise 🎀

🎀 Backup-Set Configs 🎀

Backup-Set config files largely inherit the config options of whatever provider you specified. To define a provider for the backup set, you gotta put this at the top of the backup set config file:

[holland:backup]
plugin = <plugin>
backups-to-keep = #
estimated-size-factor = #
historic-size = <yes|no>
historic-size-factor = #
historic-estimated-size-factor = #

💖 Configuration Options 💖

plugin = <plugin> — the name of the provider used for the backup-set. This is required for the backup-set to function at all. no plugin, no vibes ✨
backups-to-keep = # — how many backups to keep for a backup-set. Defaults to retaining 1 backup.
estimated-size-factor = # — the scale factor Holland uses when deciding if there's enough free space to perform a backup. Default is 1.0, and this number gets multiplied against whatever each individual plugin reports as its estimated backup size when Holland is verifying there's enough free space for the backupset.

As of Holland 1.1.1, the 'historic' backup size will be used instead. If Holland can't determine that size, it defaults back to this. plan B slay 💅

auto-purge-failures = yes | no — whether to keep a failed backup or automatically remove the backup directory. By default this is on, with the intention that whatever process is calling holland will retry when a backup fails. You can disable this behavior by setting auto-purge-failures = no when partial backups might be useful or when you're troubleshooting a backup failure. 🔍
purge-policy = manual | before-backup | after-backup — when to run the purge routine on a backupset. By default it runs after a new successful backup completes. Up to backups-to-keep backups will be retained, including the most recent.

purge-policy = before-backup runs the purge routine just before a new backup starts. This retains up to backups-to-keep backups before the new backup is even started, letting it purge all previous backups if backups-to-keep is set to 0. Useful when some other process is retaining backups off-server and disk space is at a premium. 💸

purge-policy = manual never runs the purge routine automatically. Either holland purge has to be run externally, or you explicitly remove the desired backup directories at some later time. you're on your own bestie 🫡

before-backup-command = string — run a shell command before a backup starts. This lets a command do something before the backup kicks off, like setting up an iptables rule (taking a mysql slave out of a load balancer) or aborting the backup based on some external condition.

The backup will fail if this command exits with a non-zero status. ⚠️

New in version 1.0.7.

after-backup-command = string — run a shell command after a backup completes. This lets a command do something when a backup completes successfully, like sending out a success notification. 🎉

The backup will fail if this command exits with a non-zero status. ⚠️

New in version 1.0.7.

failed-backup-command = string — run a shell command if a backup fails. This lets some command do something when a backup fails, like sending out a failure notification. 💀

The backup will fail if this command exits with a non-zero status. ⚠️

New in version 1.0.7.

historic-size = yes | no — defaults to yes. Checks for the 'backup.conf' file in the 'newest' spooled folder for the running "backupset". If the config file exists and contains 'estimated-size' and 'on-disk-size', those values get used to decide if holland has enough free space for a backupset. Basically Holland uses the previous backup's values to estimate the next backup's size. time travel but make it storage 📦

New in version 1.1.1.

historic-size-factor = # — defaults to '1.5'. If the estimated size of the database has changed by more than this multiple, the 'estimated-size-factor' value gets used to determine if there's sufficient free space for the backupset.

New in version 1.1.1.

historic-estimated-size-factor = # — defaults to '1.1'. Specifies the scale factor when Holland decides if there's enough free space to perform a backup. Holland will throw an error if the system has less free space than the last backup size multiplied by this value. math girlies rise 😤

New in version 1.1.1.

create-symlinks = yes | no — defaults to yes. Enables creation of the "newest" and "oldest" symlinks in the backupset directory. Disabling the symlink creation process can be helpful on filesystems that don't support symlinks. 🦋

New in version 1.2.7.

$ ls -l /var/spool/holland/default/
total 0
drwxrwx---. 3 root root 58 Aug 18 16:18 20210818_161856
lrwxrwxrwx. 1 root root 42 Aug 18 16:18 newest -> /var/spool/holland/default/20210818_161856
lrwxrwxrwx. 1 root root 42 Aug 18 16:18 oldest -> /var/spool/holland/default/20210818_161856

For all hook commands, Holland performs simple text substitution on these three parameters:

hook — name of the hook being called (one of: before-backup-command, after-backup-command, failed-backup-command)
backupdir — path to the current backup directory (e.g. /var/spool/holland/mysqldump/YYYYmmdd_HHMMSS)
backupset — name of the backupset being run (e.g. 'mysql-lvm')

For example:

[holland:backup]
plugin = mysqldump
before-backup-command = /usr/local/bin/my-custom-script --hook ${hook} --backupset ${backupset} --backupdir ${backupdir}
after-backup-command = echo ${backupset} completed successfully.  Files are in ${backupdir}

[mysqldump]
...

Backup-Set files live in the "backupsets" directory, which by default is /etc/holland/backupsets. The name of the backup-set is defined by its configuration filename and can really be almost anything — which means backup-sets can be organized in any arbitrary way you want, as long as the files end in .conf. The file extension is not part of the backup-set's name. 🎀

As noted above, for a backup-set to actually be active, it has to be listed in the backupsets variable. no listing, no backup, periodt 💅

Backups get placed under the directory defined in the backup_directory section of the main configuration file. Each backup lives under a directory corresponding to the backup-set name, followed by a date-encoded directory. 📁✨

👑 AUTHOR 👑

Holland Core Team. icons only 💜

🎀 COPYRIGHT 🎀

2025

and that's a wrap bestie!! you just read the whole thing, i'm so proud of you 🥹 this was Holland 1.3.1, dated Sep 08, 2025, and it's HOLLAND(1). go forth and back up your databases, mwah 💋✨

📦 where this page comes from

epel 9: holland 1.3.1-2.el9 · BSD
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

HOLLAND(1)

💖 NAME 💖

🌸 TABLE OF CONTENTS 🌸

💖 Introduction to Holland 💖

🦋 Dependencies 🦋

👑 Holland Command-Line Reference 👑

✨ help (h) ✨

✨ backup (bk) ✨

✨ list-backups (lb) ✨

✨ list-plugins (lp) ✨

✨ mk-config (mc) ✨

✨ purge (pg) ✨

🌈 Usage and Implementation Overview 🌈

🎀 Backup-Sets 🎀

💅 Providers 💅

🧚 Holland Config Files 🧚

🍓 holland.conf - main config 🍓

💖 [holland] 💖

🌸 [logging] 🌸

💜 Provider Configs 💜

🎀 mysqldump Provider Configuration [mysqldump] 🎀

🦋 [mysqldump] 🦋

🗂️ Database and Table filtering

🗜️ [compression]

🔌 MySQL connection info [mysql:client]

🧚 MySQL LVM Provider Configuration [mysql-lvm]

💾 [mysql-lvm]

📦 [tar]

✨ [compression]

🐬 MySQL connection info [mysql:client]

🌈 mysqldump LVM Provider Configuration [mysqldump-lvm]

🦋 [mysql-lvm]

🌸 [mysqld]

🎀 [mysqldump]

💜 [compression]

🫶 [mysql:client]

🔥 Xtrabackup Provider Configuration [xtrabackup]

🌟 [xtrabackup]

[compression] 🎀

MySQL connection info [mysql:client] 🦋

pgdump Provider Configuration [pgdump] 🐘

[pgdump]

[compression] 🎀

[pgauth] 🔐

pg_basebackup Provider Configuration [pg_basebackup] 🐘✨

[pg_basebackup]

[compression] 🎀

[pgauth] 🔐

mongodump Provider Configuration [mongodump] 🍃

[mongodump]

[compression] 🎀

🦋 Mariabackup Provider Configuration [mariabackup] 🦋

💜 [mariabackup] 💜

🎀 [compression] 🎀

🌈 MySQL connection info [mysql:client] 🌈

🌸 mariadb-dump Provider Configuration [mariadb-dump] 🌸

🫶 [mariadb-dump] 🫶

🦋 Database and Table filtering 🦋

💅 [compression] 💅

💖 MySQL connection info [mysql:client]

🦋 mysqlsh-dump-instance Provider Configuration [mysqlsh-dump-instance]

[mysqlsh-dump-instance]

💖 MySQL connection info [mysql:client]

🌸 mysqlsh-dump-schemas Provider Configuration [mysqlsh-dump-schemas]

[mysqlsh-dump-schemas]

🌸 MySQL connection info [mysql:client] 🌸

⚡ command Provider Configuration [command] ⚡

[command]

🎀 Backup-Set Configs 🎀

💖 Configuration Options 💖

👑 AUTHOR 👑

🎀 COPYRIGHT 🎀

✨ `[compression]`

🐬 MySQL connection info `[mysql:client]`

🌈 mysqldump LVM Provider Configuration `[mysqldump-lvm]`

🦋 `[mysql-lvm]`

🌸 `[mysqld]`

🎀 `[mysqldump]`

💜 `[compression]`

🫶 `[mysql:client]`

🔥 Xtrabackup Provider Configuration `[xtrabackup]`

🌟 `[xtrabackup]`

💜 `[mariabackup]` 💜

🎀 `[compression]` 🎀

🫶 `[mariadb-dump]` 🫶

💅 `[compression]` 💅

💖 MySQL connection info `[mysql:client]`

🦋 mysqlsh-dump-instance Provider Configuration `[mysqlsh-dump-instance]`

`[mysqlsh-dump-instance]`

💖 MySQL connection info `[mysql:client]`

🌸 mysqlsh-dump-schemas Provider Configuration `[mysqlsh-dump-schemas]`

`[mysqlsh-dump-schemas]`