Backup Hooks

Relica can excecute commands for you when it runs backups. This is useful, for example, if you wanted to do a database dump before a scheduled backup. You can even control whether the backup proceeds or not based on the result of the command.

Creating a Hook

To create a backup hook, go to the Edit Backup screen for an existing backup. You will be given the option to add hooks.

A hook consists of a command to run, the timing relative to the backup operation, the behavior related to a hook error, and an optional description purely for your convenience.

Hook Command

The hook command is the command that is invoked as a child process. Commands are parsed roughly as they are by your system's shell or command line; however, Relica's hook system is not a shell, and no interpretation or expansion of the input is performed. This means that environment variables, pipes, redirections, sub-shells, and other bash-isms (or PowerShell/command prompt features) present in your command string will not be treated like they are with your shell: Relica takes the command input very literally.

Despite this, commands can have arguments much like they do in your shell. For example, you can use quotes to group multiple space-separated tokens into a single argument. Ultimately, Relica parses the command string into its individual arguments similarly to how your shell does.

An example of a valid backup hook command:

pg_dump -U backups --file=dump.sql mydatabase

Note that the command must be in the PATH as seen by the Relica process for this to work; you may need to use the full path to the command otherwise.

Commands block until they finish.

If you need to do any of these things normally provided by a shell (pipes, running in background, expanding environment variables, etc), you can make a hook command that executes a shell, for example (Linux):

bash /Users/demo/backups/hook.bash

Where the contents of hook.bash might be a simple or complex bash script:

#!/usr/bin/env bash set -e ...

This allows you to take full advantage of your system's shell. You are not limited to just shell commands, either: you can run any executable file using backup hooks.

Avoid putting anything sensitive in the hook command (passwords, for example). Hook commands may be logged on your system. To use credentials with your command, we recommend passing relevant file names as arguments instead, or keeping credentials in a shell script that is properly permissioned.

Timing

A hook can be timed to run in one of four configurations:

Keep in mind that a backup runs for as many times as it has destinations associated with it. Thus, timing a hook to run before will run the hook command before the backup begins to each individual destination in turn. Conversely, timing a hook to run at beginning will run the hook only once, no matter how many destinations there are.

An example: suppose you're backing up your database with Relica. You need to perform a database dump before each scheduled backup. No problem; but you're backing up to 3 destinations, and you only want to do the dump once at each scheduled backup. You should time the hook for beginning so it will only run once per scheduled backup, regardless of how many destinations are configured.

Note: By default, Relica will attempt to run a missed, scheduled backup at the soonest opportunity. When this happens, hooks timed for "beginning" and "end" will NOT be run. ("Before" and "after" hooks will still be run.) Technically, missed backups only run to the destinations that were missed: not necessarily all of them. If some destinations succeeded but others were missed during a scheduled run (because, say, the power went off), only the missed destinations will be caught up. If your backups are frequently missed and the hooks are important and inexpensive/idempotent, consider using "before" and "after" timings for more granular executions.

Be aware that the order the hooks are executed at a given timing is NOT guaranteed; if ordering is very important to your backup process, consider wrapping the execution of the commands in a shell script or some other program, then execute only that program as the hook command.

Depending on the timing, the command may have certain environment variables available to it.

Error Behavior

A hook can be configured to either stop or continue on error. An error (or "failure") is when the hook command exits with a non-zero status.

If stop is chosen, a failed hook command will cause the error to be logged, and the backup will terminate without executing any other hooks or backing up to any remaining destinations.

If continue is chosen, a failed hook command will cause the error to be logged, but all hooks and backups will continue to proceed.

Environment Variables

Backup hooks are run with a few special environment variables set.