Documentation about restoring datebases with the same name (#418).

docs/how-to/backup-your-databases.md

@@ -391,7 +391,7 @@ with the repository's path or its label as configured in your borgmatic
 configuration file.
 
 ```bash
-borgmatic restore --repository repo.borg --archive host-2023-...
+borgmatic restore --repository repo.borg --archive latest
 ```
 
 ### Restore particular databases
@@ -401,7 +401,7 @@ restore one of them, use the `--database` flag to select one or more
 databases. For instance:
 
 ```bash
-borgmatic restore --archive host-2023-... --database users --database orders
+borgmatic restore --archive latest --database users --database orders
 ```
 
 <span class="minilink minilink-addedin">New in version 1.7.6</span> You can
@@ -409,29 +409,63 @@ also restore individual databases even if you dumped them as "all"—as long as
 you dumped them into separate files via use of the "format" option. See above
 for more information.
 
+### Restore databases sharing a name
+
+<span class="minilink minilink-addedin">New in version 1.9.5</span> If you've
+backed up multiple databases that happen to share the same name (e.g. from
+different hostnames or ports), you can include additional flags to disambiguate
+which database you'd like to restore. For instance:
+
+```bash
+borgmatic restore --archive latest --database users --original-hostname myhost.org
+```
+
+This selects a `users` database to restore, but only if it originally came from
+the host `myhost.org`—and doesn't restore `users` databases from any other
+hosts.
+
+Here's another example:
+
+```bash
+borgmatic restore --archive latest --database users --original-port 5433
+```
+
+That restores a `users` database only if it originally came from port 5433.
+
+Finally:
+
+```bash
+borgmatic restore --archive latest --database users --hook postgresql
+```
+
+That restores a `users` database only if it was dumped using the
+`postgresql_databases:` database hook—and doesn't restore `users` databases that
+were dumped using other database hooks.
+
+Note that these flags don't change the hostname or port where the database is
+restored. For that, see below about restoring to an alternate host.
+
 
 ### Restore all databases
 
 To restore all databases:
 
 ```bash
-borgmatic restore --archive host-2023-... --database all
+borgmatic restore --archive latest --database all
 ```
 
 Or omit the `--database` flag entirely:
 
 
 ```bash
-borgmatic restore --archive host-2023-...
+borgmatic restore --archive latest
 ```
 
-Prior to borgmatic version 1.7.6, this restores a combined "all" database
-dump from the archive.
-
 <span class="minilink minilink-addedin">New in version 1.7.6</span> Restoring
 "all" databases restores each database found in the selected archive. That
 includes any combined dump file named "all" and any other individual database
-dumps found in the archive.
+dumps found in the archive. Prior to borgmatic version 1.7.6, restoring "all"
+only restored a combined "all" database dump from the archive.
 
 
 ### Restore particular schemas
@@ -466,16 +500,35 @@ postgresql_databases:
         restore_password: trustsome1
 ```
 
+### 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.
+
+borgmatic extracts the dump file into the `borgmatic/` directory within the
+extraction destination path. For example, if you're extracting to `/tmp`, then
+the dump will be in `/tmp/borgmatic/`.
+
+<span class="minilink minilink-addedin">Prior to version 1.9.0</span> borgmatic
+extracts the dump file into the *`username`*`/.borgmatic/` directory within the
+extraction destination path, where *`username`* is the user that created the
+backup. For example, if you created the backup with the `root` user and you're
+extracting to `/tmp`, then the dump will be in `/tmp/root/.borgmatic`.
+
+After extraction, you can manually restore the dump file using native database
+commands like `pg_restore`, `mysql`, `mongorestore`, `sqlite`, or similar.
+
+Also see the documentation on [listing database
+dumps](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/#listing-database-dumps).
+
 
-### Limitations
+## Limitations
 
 There are a few important limitations with borgmatic's current database
-restoration feature that you should know about:
+hooks that you should know about:
 
-1. borgmatic does not currently support backing up or restoring multiple
-databases that share the exact same name on different hosts or with different
-ports.
-2. When database hooks are enabled, borgmatic instructs Borg to consume
+1. When database hooks are enabled, borgmatic instructs Borg to consume
 special files (via `--read-special`) to support database dump
 streaming—regardless of the value of your `read_special` configuration option.
 And because this can cause Borg to hang, borgmatic also automatically excludes
@@ -490,6 +543,9 @@ exclude them. <span class="minilink minilink-addedin">Prior to version
 1.7.3</span>Special files were not auto-excluded, and you were responsible for
 excluding them yourself. Common directories to exclude are `/dev` and `/run`,
 but that may not be exhaustive.
+2. <span class="minilink minilink-addedin">Prior to version 1.9.5</span>
+borgmatic did not support backing up or restoring multiple databases that
+shared the exact same name on different hosts or with different ports.
 3. <span class="minilink minilink-addedin">Prior to version 1.9.0</span>
 Database hooks also implicitly enabled the `one_file_system` option, which
 meant Borg wouldn't cross filesystem boundaries when looking for files to
@@ -510,29 +566,6 @@ starting from version 1.7.15, borgmatic includes your configuration files
 automatically.
 
 
-### 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.
-
-borgmatic extracts the dump file into the `borgmatic/` directory within the
-extraction destination path. For example, if you're extracting to `/tmp`, then
-the dump will be in `/tmp/borgmatic/`.
-
-<span class="minilink minilink-addedin">Prior to version 1.9.0</span> borgmatic
-extracts the dump file into the *`username`*`/.borgmatic/` directory within the
-extraction destination path, where *`username`* is the user that created the
-backup. For example, if you created the backup with the `root` user and you're
-extracting to `/tmp`, then the dump will be in `/tmp/root/.borgmatic`.
-
-After extraction, you can manually restore the dump file using native database
-commands like `pg_restore`, `mysql`, `mongorestore`, `sqlite`, or similar.
-
-Also see the documentation on [listing database
-dumps](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/#listing-database-dumps).
-
-
 ## Preparation and cleanup hooks
 
 If this database integration is too limited for needs, borgmatic also supports