Database dump hooks documentation (#225).
This commit is contained in:
parent
37dc94bc79
commit
5e3c2da79c
16 changed files with 130 additions and 49 deletions
|
@ -13,11 +13,7 @@ module.exports = function(eleventyConfig) {
|
||||||
html: true,
|
html: true,
|
||||||
breaks: false,
|
breaks: false,
|
||||||
linkify: true,
|
linkify: true,
|
||||||
// Replace links to .md files with links to directories. This allows unparsed Markdown links
|
|
||||||
// to work on GitHub, while rendered links elsewhere also work.
|
|
||||||
replaceLink: function (link, env) {
|
replaceLink: function (link, env) {
|
||||||
link = link.replace(/\.md$/, '/');
|
|
||||||
|
|
||||||
if (process.env.NODE_ENV == "production") {
|
if (process.env.NODE_ENV == "production") {
|
||||||
return link;
|
return link;
|
||||||
}
|
}
|
||||||
|
|
2
NEWS
2
NEWS
|
@ -1,4 +1,4 @@
|
||||||
1.3.27.dev0
|
1.4.0
|
||||||
* #225: Database dump hooks for PostgreSQL, so you can easily dump your databases before backups
|
* #225: Database dump hooks for PostgreSQL, so you can easily dump your databases before backups
|
||||||
run.
|
run.
|
||||||
* #230: Rename "borgmatic list --pattern-from" flag to "--patterns-from" to match Borg.
|
* #230: Rename "borgmatic list --pattern-from" flag to "--patterns-from" to match Borg.
|
||||||
|
|
|
@ -73,6 +73,7 @@ href="https://asciinema.org/a/203761" target="_blank">screencast</a>.
|
||||||
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/)
|
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/)
|
||||||
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
|
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
|
||||||
* [Restore a backup](https://torsion.org/borgmatic/docs/how-to/restore-a-backup/)
|
* [Restore a backup](https://torsion.org/borgmatic/docs/how-to/restore-a-backup/)
|
||||||
|
* [Backup your databases](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)
|
||||||
* [Add preparation and cleanup steps to backups](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/)
|
* [Add preparation and cleanup steps to backups](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/)
|
||||||
* [Upgrade borgmatic](https://torsion.org/borgmatic/docs/how-to/upgrade/)
|
* [Upgrade borgmatic](https://torsion.org/borgmatic/docs/how-to/upgrade/)
|
||||||
* [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/)
|
* [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/)
|
||||||
|
|
|
@ -1,23 +1,26 @@
|
||||||
---
|
---
|
||||||
title: Add preparation and cleanup steps to backups
|
title: How to add preparation and cleanup steps to backups
|
||||||
---
|
---
|
||||||
## Preparation and cleanup hooks
|
## Preparation and cleanup hooks
|
||||||
|
|
||||||
If you find yourself performing prepraration tasks before your backup runs, or
|
If you find yourself performing prepraration tasks before your backup runs, or
|
||||||
cleanup work afterwards, borgmatic hooks may be of interest. Hooks are
|
cleanup work afterwards, borgmatic hooks may be of interest. Hooks are shell
|
||||||
shell commands that borgmatic executes for you at various points, and they're
|
commands that borgmatic executes for you at various points, and they're
|
||||||
configured in the `hooks` section of your configuration file.
|
configured in the `hooks` section of your configuration file. But if you're
|
||||||
|
looking to backup a database, it's probably easier to use the [database backup
|
||||||
|
feature](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)
|
||||||
|
instead.
|
||||||
|
|
||||||
For instance, you can specify `before_backup` hooks to dump a database to file
|
You can specify `before_backup` hooks to perform preparation steps before
|
||||||
before backing it up, and specify `after_backup` hooks to delete the temporary
|
running backups, and specify `after_backup` hooks to perform cleanup steps
|
||||||
file afterwards. Here's an example:
|
afterwards. Here's an example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
hooks:
|
||||||
before_backup:
|
before_backup:
|
||||||
- dump-a-database /to/file.sql
|
- mount /some/filesystem
|
||||||
after_backup:
|
after_backup:
|
||||||
- rm /to/file.sql
|
- umount /some/filesystem
|
||||||
```
|
```
|
||||||
|
|
||||||
The `before_backup` and `after_backup` hooks each run once per configuration
|
The `before_backup` and `after_backup` hooks each run once per configuration
|
||||||
|
@ -49,14 +52,14 @@ a backup or a backup hook, but not if an error occurs during a
|
||||||
|
|
||||||
borgmatic also runs `on_error` hooks if an error occurs, either when creating
|
borgmatic also runs `on_error` hooks if an error occurs, either when creating
|
||||||
a backup or running a backup hook. See the [monitoring and alerting
|
a backup or running a backup hook. See the [monitoring and alerting
|
||||||
documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups.md)
|
documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
|
||||||
for more information.
|
for more information.
|
||||||
|
|
||||||
## Hook output
|
## Hook output
|
||||||
|
|
||||||
Any output produced by your hooks shows up both at the console and in syslog
|
Any output produced by your hooks shows up both at the console and in syslog
|
||||||
(when run in a non-interactive console). For more information, read about <a
|
(when run in a non-interactive console). For more information, read about <a
|
||||||
href="https://torsion.org/borgmatic/docs/how-to/inspect-your-backups.md">inspecting
|
href="https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/">inspecting
|
||||||
your backups</a>.
|
your backups</a>.
|
||||||
|
|
||||||
## Security
|
## Security
|
||||||
|
@ -70,7 +73,7 @@ invoked by hooks.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups.md)
|
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
||||||
* [Make per-application backups](https://torsion.org/borgmatic/docs/how-to/make-per-application-backups.md)
|
* [Backup your databases](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)
|
||||||
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups.md)
|
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/)
|
||||||
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups.md)
|
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
|
||||||
|
|
81
docs/how-to/backup-your-databases.md
Normal file
81
docs/how-to/backup-your-databases.md
Normal file
|
@ -0,0 +1,81 @@
|
||||||
|
---
|
||||||
|
title: How to backup your databases
|
||||||
|
---
|
||||||
|
## Database dump hooks
|
||||||
|
|
||||||
|
If you want to backup a database, it's best practice with most database
|
||||||
|
systems to backup an exported database dump, rather than backing up your
|
||||||
|
database's internal file storage. That's because the internal storage can
|
||||||
|
change while you're reading from it. In contrast, a database dump creates a
|
||||||
|
consistent snapshot that is more suited for backups.
|
||||||
|
|
||||||
|
Fortunately, borgmatic includes built-in support for creating database dumps
|
||||||
|
prior to running backups. For example, here is everything you need to dump and
|
||||||
|
backup a couple of local PostgreSQL databases:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
hooks:
|
||||||
|
postgresql_databases:
|
||||||
|
- name: users
|
||||||
|
- name: orders
|
||||||
|
```
|
||||||
|
|
||||||
|
Prior to each backup, borgmatic dumps each configured database to a file
|
||||||
|
(located in `~/.borgmatic/`) and includes it in the backup. After the backup
|
||||||
|
completes, borgmatic removes the database dump files to recover disk space.
|
||||||
|
|
||||||
|
Here's a more involved example that connects to a remote database:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
hooks:
|
||||||
|
postgresql_databases:
|
||||||
|
- name: users
|
||||||
|
hostname: database.example.org
|
||||||
|
port: 5433
|
||||||
|
username: dbuser
|
||||||
|
password: trustsome1
|
||||||
|
format: tar
|
||||||
|
options: "--role=someone"
|
||||||
|
```
|
||||||
|
|
||||||
|
If you want to dump all databases on a host, use `all` for the database name:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
hooks:
|
||||||
|
postgresql_databases:
|
||||||
|
- name: all
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that you may need to use a `username` of the `postgres` superuser for
|
||||||
|
this to work.
|
||||||
|
|
||||||
|
## Supported databases
|
||||||
|
|
||||||
|
As of now, borgmatic only supports PostgreSQL databases directly. But see
|
||||||
|
below about general-purpose preparation and cleanup hooks as a work-around
|
||||||
|
with other database systems. Also, please [file a
|
||||||
|
ticket](https://torsion.org/borgmatic/#issues) for additional database systems
|
||||||
|
that you'd like supported.
|
||||||
|
|
||||||
|
## Database restoration
|
||||||
|
|
||||||
|
borgmatic does not yet perform integrated database restoration when you
|
||||||
|
[restore a backup](http://localhost:8080/docs/how-to/restore-a-backup/), but
|
||||||
|
that feature is coming in a future release. In the meantime, you can restore
|
||||||
|
a database manually after restoring a dump file in the `~/.borgmatic` path.
|
||||||
|
|
||||||
|
## Preparation and cleanup hooks
|
||||||
|
|
||||||
|
If this database integration is too limited for needs, borgmatic also supports
|
||||||
|
general-purpose [preparation and cleanup
|
||||||
|
hooks](https://torsion.org/borgmatic/docs/how-to/set-up-backups/). These
|
||||||
|
hooks allows you to trigger arbitrary commands or scripts before and after
|
||||||
|
backups. So if necessary, you can use these hooks to create database dumps
|
||||||
|
with any database system.
|
||||||
|
|
||||||
|
## Related documentation
|
||||||
|
|
||||||
|
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
||||||
|
* [Add preparation and cleanup steps to backups](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/)
|
||||||
|
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/)
|
||||||
|
* [Restore a backup](http://localhost:8080/docs/how-to/restore-a-backup/)
|
|
@ -106,4 +106,4 @@ backups.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups.md)
|
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
||||||
|
|
|
@ -109,4 +109,4 @@ also linked from the commits list on each pull request.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups.md)
|
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/)
|
||||||
|
|
|
@ -86,7 +86,7 @@ already has this rate limit disabled.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups.md)
|
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
||||||
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups.md)
|
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
|
||||||
* [Add preparation and cleanup steps to backups](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md)
|
* [Add preparation and cleanup steps to backups](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/)
|
||||||
* [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic.md)
|
* [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/)
|
||||||
|
|
|
@ -112,4 +112,4 @@ directly, please see the section above about standard includes.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups.md)
|
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
||||||
|
|
|
@ -90,7 +90,7 @@ here:
|
||||||
Note that borgmatic does not run `on_error` hooks if an error occurs within a
|
Note that borgmatic does not run `on_error` hooks if an error occurs within a
|
||||||
`before_everything` or `after_everything` hook. For more about hooks, see the
|
`before_everything` or `after_everything` hook. For more about hooks, see the
|
||||||
[borgmatic hooks
|
[borgmatic hooks
|
||||||
documentation](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md),
|
documentation](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/),
|
||||||
especially the security information.
|
especially the security information.
|
||||||
|
|
||||||
|
|
||||||
|
@ -151,8 +151,8 @@ fancier with your archive listing. See `borg list --help` for more flags.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups.md)
|
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
||||||
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups.md)
|
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/)
|
||||||
* [Add preparation and cleanup steps to backups](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md)
|
* [Add preparation and cleanup steps to backups](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/)
|
||||||
* [Restore a backup](https://torsion.org/borgmatic/docs/how-to/restore-a-backup.md)
|
* [Restore a backup](https://torsion.org/borgmatic/docs/how-to/restore-a-backup/)
|
||||||
* [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic.md)
|
* [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/)
|
||||||
|
|
|
@ -63,6 +63,6 @@ Like a whole-archive restore, this also restores into the current directory.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups.md)
|
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
||||||
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups.md)
|
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/)
|
||||||
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups.md)
|
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
|
||||||
|
|
|
@ -77,7 +77,7 @@ else borgmatic won't recognize the option. Also be sure to use spaces rather
|
||||||
than tabs for indentation; YAML does not allow tabs.
|
than tabs for indentation; YAML does not allow tabs.
|
||||||
|
|
||||||
You can also get the same sample configuration file from the [configuration
|
You can also get the same sample configuration file from the [configuration
|
||||||
reference](https://torsion.org/borgmatic/docs/reference/configuration.md), the authoritative set of
|
reference](https://torsion.org/borgmatic/docs/reference/configuration/), the authoritative set of
|
||||||
all configuration options. This is handy if borgmatic has added new options
|
all configuration options. This is handy if borgmatic has added new options
|
||||||
since you originally created your configuration file.
|
since you originally created your configuration file.
|
||||||
|
|
||||||
|
@ -244,9 +244,9 @@ it.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Make per-application backups](https://torsion.org/borgmatic/docs/how-to/make-per-application-backups.md)
|
* [Make per-application backups](https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/)
|
||||||
* [Deal with very large backups](https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups.md)
|
* [Deal with very large backups](https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/)
|
||||||
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups.md)
|
* [Inspect your backups](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/)
|
||||||
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups.md)
|
* [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
|
||||||
* [borgmatic configuration reference](https://torsion.org/borgmatic/docs/reference/configuration.md)
|
* [borgmatic configuration reference](https://torsion.org/borgmatic/docs/reference/configuration/)
|
||||||
* [borgmatic command-line reference](https://torsion.org/borgmatic/docs/reference/command-line.md)
|
* [borgmatic command-line reference](https://torsion.org/borgmatic/docs/reference/command-line/)
|
||||||
|
|
|
@ -76,4 +76,4 @@ files.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic.md)
|
* [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/)
|
||||||
|
|
|
@ -13,5 +13,5 @@ each action sub-command:
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups.md)
|
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
||||||
* [borgmatic configuration reference](https://torsion.org/borgmatic/docs/reference/configuration.md)
|
* [borgmatic configuration reference](https://torsion.org/borgmatic/docs/reference/configuration/)
|
||||||
|
|
|
@ -15,5 +15,5 @@ file](https://torsion.org/borgmatic/docs/reference/config.yaml) for use locally.
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups.md)
|
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
||||||
* [borgmatic command-line reference](https://torsion.org/borgmatic/docs/reference/command-line.md)
|
* [borgmatic command-line reference](https://torsion.org/borgmatic/docs/reference/command-line/)
|
||||||
|
|
2
setup.py
2
setup.py
|
@ -1,6 +1,6 @@
|
||||||
from setuptools import find_packages, setup
|
from setuptools import find_packages, setup
|
||||||
|
|
||||||
VERSION = '1.3.27.dev0'
|
VERSION = '1.4.0'
|
||||||
|
|
||||||
|
|
||||||
setup(
|
setup(
|
||||||
|
|
Loading…
Reference in a new issue