From 36bcbd05927f2156caa2fbe579792bdd976e696f Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Tue, 17 Dec 2024 08:51:04 -0800 Subject: [PATCH] Documentation about restoring datebases with the same name (#418). --- docs/how-to/backup-your-databases.md | 137 +++++++++++++++++---------- 1 file changed, 85 insertions(+), 52 deletions(-) diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index 76b8e4f7..f908a10a 100644 --- a/docs/how-to/backup-your-databases.md +++ b/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 ``` New in version 1.7.6 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 + +New in version 1.9.5 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. - New in version 1.7.6 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,50 +500,6 @@ postgresql_databases: restore_password: trustsome1 ``` - -### Limitations - -There are a few important limitations with borgmatic's current database -restoration feature 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 -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 -special files (and symlinks to them) that Borg may get stuck on. Even so, -there are still potential edge cases in which applications on your system -create new special files *after* borgmatic constructs its exclude list, -resulting in Borg hangs. If that occurs, you can resort to manually excluding -those files. And if you explicitly set the `read_special` option to `true`, -borgmatic will opt you out of the auto-exclude feature entirely, but will -still instruct Borg to consume special files—and you will be on your own to -exclude them. Prior to version -1.7.3Special 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. -3. Prior to version 1.9.0 -Database hooks also implicitly enabled the `one_file_system` option, which -meant Borg wouldn't cross filesystem boundaries when looking for files to -backup. When borgmatic was running in a container, this often required a -work-around to explicitly add each mounted backup volume to -`source_directories` instead of relying on Borg to include them implicitly via -a parent directory. But as of borgmatic 1.9.0, `one_file_system` is no longer -auto-enabled and such work-arounds aren't necessary. -4. Prior to version 1.9.0 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. -5. Prior to version 1.7.15 As -mentioned above, borgmatic can only restore a database that's defined in -borgmatic's own configuration file. So include your configuration files in -backups to avoid getting caught without a way to restore a database. But -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 @@ -533,6 +523,49 @@ Also see the documentation on [listing database dumps](https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/#listing-database-dumps). +## Limitations + +There are a few important limitations with borgmatic's current database +hooks that you should know about: + +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 +special files (and symlinks to them) that Borg may get stuck on. Even so, +there are still potential edge cases in which applications on your system +create new special files *after* borgmatic constructs its exclude list, +resulting in Borg hangs. If that occurs, you can resort to manually excluding +those files. And if you explicitly set the `read_special` option to `true`, +borgmatic will opt you out of the auto-exclude feature entirely, but will +still instruct Borg to consume special files—and you will be on your own to +exclude them. Prior to version +1.7.3Special 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. Prior to version 1.9.5 +borgmatic did not support backing up or restoring multiple databases that +shared the exact same name on different hosts or with different ports. +3. Prior to version 1.9.0 +Database hooks also implicitly enabled the `one_file_system` option, which +meant Borg wouldn't cross filesystem boundaries when looking for files to +backup. When borgmatic was running in a container, this often required a +work-around to explicitly add each mounted backup volume to +`source_directories` instead of relying on Borg to include them implicitly via +a parent directory. But as of borgmatic 1.9.0, `one_file_system` is no longer +auto-enabled and such work-arounds aren't necessary. +4. Prior to version 1.9.0 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. +5. Prior to version 1.7.15 As +mentioned above, borgmatic can only restore a database that's defined in +borgmatic's own configuration file. So include your configuration files in +backups to avoid getting caught without a way to restore a database. But +starting from version 1.7.15, borgmatic includes your configuration files +automatically. + + ## Preparation and cleanup hooks If this database integration is too limited for needs, borgmatic also supports