Documentation for database restores (#229).

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
 

README.md

@@ -72,7 +72,7 @@ href="https://asciinema.org/a/203761" target="_blank">screencast</a>.
  * [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/)

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
 

docs/_includes/index.css

@@ -165,6 +165,7 @@ ul {
 }
 li {
 	padding: .25em 0;
+	line-height: 1.5;
 }
 li ul {
 	margin: .5em 0;

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/)

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/)

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/)

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/)
+<head>
+    <meta http-equiv='refresh' content='0; URL=https://torsion.org/borgmatic/docs/how-to/extract-a-backup/'>
+</head>

setup.py

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.4.1.dev0'
+VERSION = '1.4.1'
 
 
 setup(