diff --git a/NEWS b/NEWS index 1d2c516be..379278623 100644 --- a/NEWS +++ b/NEWS @@ -1,5 +1,7 @@ -1.4.1.dev0 - * #229: Restore backed up PostgreSQL databases via "borgmatic restore" sub-command. +1.4.1 + * #229: Restore backed up PostgreSQL databases via "borgmatic restore" action. See the + documentation for more information: + https://torsion.org/borgmatic/docs/how-to/backup-your-databases/ * Documentation on how to develop borgmatic's documentation: https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/#documentation-development diff --git a/README.md b/README.md index 87faaef39..e1ec7f80e 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ href="https://asciinema.org/a/203761" target="_blank">screencast. * [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/) * [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/) + * [Extract a backup](https://torsion.org/borgmatic/docs/how-to/extract-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/) * [Upgrade borgmatic](https://torsion.org/borgmatic/docs/how-to/upgrade/) diff --git a/docs/Dockerfile b/docs/Dockerfile index 777d8d913..829098fd4 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -3,7 +3,7 @@ FROM python:3.7.4-alpine3.10 as borgmatic COPY . /app RUN pip install --no-cache /app && generate-borgmatic-config && chmod +r /etc/borgmatic/config.yaml RUN borgmatic --help > /command-line.txt \ - && for action in init prune create check extract list info; do \ + && for action in init prune create check extract restore list info; do \ echo -e "\n--------------------------------------------------------------------------------\n" >> /command-line.txt \ && borgmatic "$action" --help >> /command-line.txt; done diff --git a/docs/_includes/index.css b/docs/_includes/index.css index a40dc90b0..78e816c0a 100644 --- a/docs/_includes/index.css +++ b/docs/_includes/index.css @@ -165,6 +165,7 @@ ul { } li { padding: .25em 0; + line-height: 1.5; } li ul { margin: .5em 0; diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index 446e5a73c..21504b2f4 100644 --- a/docs/how-to/backup-your-databases.md +++ b/docs/how-to/backup-your-databases.md @@ -49,6 +49,16 @@ hooks: Note that you may need to use a `username` of the `postgres` superuser for this to work. + +### Configuration backups + +An important note about this database configuration: You'll need the +configuration to be present in order for borgmatic to restore a database. So +to prepare for this situation, it's a good idea to include borgmatic's own +configuration files as part of your regular backups. That way, you can always +bring back any missing configuration files in order to restore a database. + + ## Supported databases As of now, borgmatic only supports PostgreSQL databases directly. But see @@ -57,12 +67,89 @@ 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. +To restore a database dump from an archive, use the `borgmatic restore` +action. But the first step is to figure out which archive to restore from. A +good way to do that is to use the `list` action: + +```bash +borgmatic list +``` + +(No borgmatic `list` action? Try the old-style `--list`, or upgrade +borgmatic!) + +That should yield output looking something like: + +```text +host-2019-01-01T04:05:06.070809 Tue, 2019-01-01 04:05:06 [...] +host-2019-01-02T04:06:07.080910 Wed, 2019-01-02 04:06:07 [...] +``` + +Assuming that you want to restore all database dumps from the archive with the +most up-to-date files and therefore the latest timestamp, run a command like: + +```bash +borgmatic restore --archive host-2019-01-02T04:06:07.080910 +``` + +(No borgmatic `restore` action? Upgrade borgmatic!) + +The `--archive` value is the name of the archive to restore from. This +restores all databases dumps that borgmatic originally backed up to that +archive. + +This is a destructive action! `borgmatic restore` replaces live databases by +restoring dumps from the selected archive. So be very careful when and where +you run it. + + +### Repository selection + +If you have a single repository in your borgmatic configuration file(s), no +problem: the `restore` action figures out which repository to use. + +But if you have multiple repositories configured, then you'll need to specify +the repository path containing the archive to restore. Here's an example: + +```bash +borgmatic restore --repository repo.borg --archive host-2019-... +``` + +### Restore particular databases + +If you've backed up multiple databases into an archive, and you'd only like to +restore one of them, use the `--database` flag to select one or more +databases. For instance: + +```bash +borgmatic restore --archive host-2019-... --database users +``` + +### Limitations + +There are a few important limitations with borgmatic's current database +restoration feature that you should know about: + +1. You must restore as the same Unix user that created the archive containing +the database dump. That's because the user's home directory path is encoded +into the path of the database dump within the archive. +2. As mentioned above, borgmatic can only restore a database that's defined in +borgmatic's own configuration file. So include your configuration file in +backups to avoid getting caught without a way to restore a database. +3. borgmatic does not currently support backing up or restoring multiple +databases that share the exact same name on different hosts. + + +### Manual restoration + +If you prefer to restore a database without the help of borgmatic, first +[extract](https://torsion.org/borgmatic/docs/how-to/extract-a-backup/) an +archive containing a database dump, and then manually restore the dump file +found within the extracted `~/.borgmatic/` path (e.g. with `pg_restore`). + ## Preparation and cleanup hooks @@ -73,9 +160,10 @@ 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/) + * [Extract a backup](https://torsion.org/borgmatic/docs/how-to/extract-a-backup/) diff --git a/docs/how-to/extract-a-backup.md b/docs/how-to/extract-a-backup.md new file mode 100644 index 000000000..7888b1298 --- /dev/null +++ b/docs/how-to/extract-a-backup.md @@ -0,0 +1,82 @@ +--- +title: How to extract a backup +--- +## Extract + +When the worst happens—or you want to test your backups—the first step is +to figure out which archive to extract. A good way to do that is to use the +`list` action: + +```bash +borgmatic list +``` + +(No borgmatic `list` action? Try the old-style `--list`, or upgrade +borgmatic!) + +That should yield output looking something like: + +```text +host-2019-01-01T04:05:06.070809 Tue, 2019-01-01 04:05:06 [...] +host-2019-01-02T04:06:07.080910 Wed, 2019-01-02 04:06:07 [...] +``` + +Assuming that you want to extract the archive with the most up-to-date files +and therefore the latest timestamp, run a command like: + +```bash +borgmatic extract --archive host-2019-01-02T04:06:07.080910 +``` + +(No borgmatic `extract` action? Try the old-style `--extract`, or upgrade +borgmatic!) + +The `--archive` value is the name of the archive to extract. This extracts the +entire contents of the archive to the current directory, so make sure you're +in the right place before running the command. + + +## Repository selection + +If you have a single repository in your borgmatic configuration file(s), no +problem: the `extract` action figures out which repository to use. + +But if you have multiple repositories configured, then you'll need to specify +the repository path containing the archive to extract. Here's an example: + +```bash +borgmatic extract --repository repo.borg --archive host-2019-... +``` + +## Extract particular files + +Sometimes, you want to extract a single deleted file, rather than extracting +everything from an archive. To do that, tack on one or more `--restore-path` +values. For instance: + +```bash +borgmatic extract --archive host-2019-... --restore-path path/1 path/2 +``` + +Note that the specified restore paths should not have a leading slash. Like a +whole-archive extract, this also extracts into the current directory. So for +example, if you happen to be in the directory `/var` and you run the `extract` +command above, borgmatic will extract `/var/path/1` and `/var/path/2`. + + +## Database restoration + +The `borgmatic extract` command only extracts files. To restore a database, +please see the [documentation on database backups and +restores](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/). +borgmatic does not perform database restoration as part of `borgmatic extract` +so that you can extract files from your archive without impacting your live +databases. + + +## Related documentation + + * [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/) + * [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/) + * [Backup your databases](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/) diff --git a/docs/how-to/monitor-your-backups.md b/docs/how-to/monitor-your-backups.md index db84032f2..99cb563e9 100644 --- a/docs/how-to/monitor-your-backups.md +++ b/docs/how-to/monitor-your-backups.md @@ -47,8 +47,8 @@ from borgmatic for a configured interval. really want confidence that your backups are not only running but are restorable as well, you can configure particular [consistency checks](https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#consistency-check-configuration) -or even script full [restore -tests](https://torsion.org/borgmatic/docs/how-to/restore-a-backup/). +or even script full [extract +tests](https://torsion.org/borgmatic/docs/how-to/extract-a-backup/). ## Error hooks @@ -154,5 +154,5 @@ fancier with your archive listing. See `borg list --help` for more flags. * [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/) * [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/) + * [Extract a backup](https://torsion.org/borgmatic/docs/how-to/extract-a-backup/) * [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/) diff --git a/docs/how-to/restore-a-backup.md b/docs/how-to/restore-a-backup.md index ce9e56fe2..30ab4cf91 100644 --- a/docs/how-to/restore-a-backup.md +++ b/docs/how-to/restore-a-backup.md @@ -1,71 +1,3 @@ ---- -title: How to restore a backup ---- -## Extract - -When the worst happens—or you want to test your backups—the first step is -to figure out which archive to restore. A good way to do that is to use the -`list` action: - -```bash -borgmatic list -``` - -(No borgmatic `list` action? Try the old-style `--list`, or upgrade -borgmatic!) - -That should yield output looking something like: - -```text -host-2019-01-01T04:05:06.070809 Tue, 2019-01-01 04:05:06 [...] -host-2019-01-02T04:06:07.080910 Wed, 2019-01-02 04:06:07 [...] -``` - -Assuming that you want to restore the archive with the most up-to-date files -and therefore the latest timestamp, run a command like: - -```bash -borgmatic extract --archive host-2019-01-02T04:06:07.080910 -``` - -(No borgmatic `extract` action? Try the old-style `--extract`, or upgrade -borgmatic!) - -The `--archive` value is the name of the archive to restore. This extracts the -entire contents of the archive to the current directory, so make sure you're -in the right place before running the command. - - -## Repository selection - -If you have a single repository in your borgmatic configuration file(s), no -problem: the `extract` action figures out which repository to use. - -But if you have multiple repositories configured, then you'll need to specify -the repository path containing the archive to extract. Here's an example: - -```bash -borgmatic extract --repository repo.borg --archive host-2019-... -``` - -## Restore particular files - -Sometimes, you want to restore a single deleted file, rather than restoring -everything from an archive. To do that, tack on one or more `--restore-path` -values. For instance: - -```bash -borgmatic extract --archive host-2019-... --restore-path path/1 path/2 -``` - -Note that the specified restore paths should not have a leading slash. Like a -whole-archive restore, this also restores into the current directory. So for -example, if you happen to be in the directory `/var` and you run the `extract` -command above, borgmatic will restore `/var/path/1` and `/var/path/2`. - - -## Related documentation - - * [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/) - * [Monitor your backups](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/) + + + diff --git a/setup.py b/setup.py index d389b333f..79a8211fd 100644 --- a/setup.py +++ b/setup.py @@ -1,6 +1,6 @@ from setuptools import find_packages, setup -VERSION = '1.4.1.dev0' +VERSION = '1.4.1' setup(