From b52339652f23ca60d4b627fe21f81f5541cae156 Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Sun, 9 Mar 2025 09:57:13 -0700 Subject: [PATCH] Initial command hooks documentation work (#1019). --- borgmatic/config/schema.yaml | 8 +- ...reparation-and-cleanup-steps-to-backups.md | 92 ++++++++++++++++++- 2 files changed, 95 insertions(+), 5 deletions(-) diff --git a/borgmatic/config/schema.yaml b/borgmatic/config/schema.yaml index 24609f40..31129af2 100644 --- a/borgmatic/config/schema.yaml +++ b/borgmatic/config/schema.yaml @@ -961,8 +961,8 @@ properties: - everything - dump_data_sources description: | - Name for the point in borgmatic's execution before - which the commands should be run (required if + Name for the point in borgmatic's execution that + the commands should be run before (required if "after" isn't set): * "action" runs before each action for each repository. @@ -1039,8 +1039,8 @@ properties: - error - dump_data_sources description: | - Name for the point in borgmatic's execution after - which the commands should be run (required if + Name for the point in borgmatic's execution that + the commands should be run after (required if "before" isn't set): * "action" runs after each action for each repository. diff --git a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md index aa0fbcfb..d6ea1e06 100644 --- a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md +++ b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md @@ -17,7 +17,97 @@ But if you're looking to backup a database, it's probably easier to use the feature](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/) instead. -You can specify `before_backup` hooks to perform preparation steps before +New in version 1.9.14 You can +configure command hooks via a list of `commands:` in your borgmatic +configuration file. For example: + +```yaml +commands: + - before: action + when: + - create + run: + - echo "Before create!" + - after: action + when: + - create + - prune + run: + - echo "After create and/or prune!" +``` + +If A `run:` command contains a special YAML character such as a colon, you may +need to quote the entire string (or use a [multiline +string](https://yaml-multiline.info/)) to avoid an error: + +```yaml +commands: + - before: action + when: + - create + run: + - "echo Backup: start" +``` + +Each command has the following options: + + * `before` or `after`: Name for the point in borgmatic's execution that the commands should be run before/after, one of: + * `action` runs before each action for each repository. (Replaces the deprecated `before_create`, `after_prune`, etc.) + * `repository` runs before/after all actions for each repository. (Replaces the deprecated `before_actions`/`after_actions`.) + * `configuration` runs before/after all actions and repositories in the current configuration file. + * `everything` runs before/after all configuration files. (Replaces the deprecated `before_everything`/`after_everything`.) + * `when`: List of actions for which the commands will be run. Defaults to running for all actions. + * `run`: List of one or more shell commands or scripts to run when this command hook is triggered. + +There's also another command hook that works a little differently: + +```yaml +commands: + - before: dump_data_sources + hooks: + - postgresql + run: + - echo "Right before the PostgreSQL database dump!" +``` + +This command hook has the following options: + + * `before` or `after`: `dump_data_sources` + * `hooks`: List of names of other hooks that this command hook applies to. Defaults to all hooks of the relevant type. + * `run`: List of one or more shell commands or scripts to run when this command hook is triggered. + + +### Order of execution + +Here's a way of visualizing how all of these command hooks slot into borgmatic's +execution. + +Let's say you've got a borgmatic configuration file with a configured +repository. And suppose you configure several command hooks and then run +borgmatic for the `create` and `prune` actions. Here's the order of execution: + + * Trigger `before: everything` (from all configuration files). + * Trigger `before: configuration` (from the first configuration file). + * Trigger `before: repository` (for the first repository). + * Trigger `before: action` for `create`. + * Run the `create` action. + * Trigger `after: action` for `create`. + * Trigger `before: action` for `prune`. + * Run the `prune` action. + * Trigger `after: action` for `prune`. + * Trigger `after: repository` (for the first repository). + * Trigger `after: configuration` (from the first configuration file). + * Trigger `after: everything` (from all configuration files). + +You can imagine how this would be extended to multiple repositories and/or +configuration files. + + +### Deprecated command hooks + +Prior to version 1.9.14 The +command hooks worked a little differently. In these older versions of borgmatic, +you can specify `before_backup` hooks to perform preparation steps before running backups and specify `after_backup` hooks to perform cleanup steps afterwards. Here's an example: