From 1f415a24b878f08aff161ceb9261a6e3f61b3593 Mon Sep 17 00:00:00 2001 From: Divyansh Singh Date: Sat, 15 Jul 2023 12:27:54 +0530 Subject: [PATCH 1/3] add docs for database restore params and config bootstrap --- docs/how-to/backup-your-databases.md | 23 +++++++++++++++++++++++ docs/how-to/extract-a-backup.md | 16 ++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index f1f00878..2eaa1d0f 100644 --- a/docs/how-to/backup-your-databases.md +++ b/docs/how-to/backup-your-databases.md @@ -338,6 +338,29 @@ within the database dump: borgmatic restore --archive latest --database users --schema tentant1 ``` +### Restore to an alternate host +New in version 1.7.15 You +can restore a database dump to a host other than the one from which it was +originally dumped. You can also change other connection parameters like the +username, password, and port. This can be done from the command line: + +```bash +borgmatic restore --archive latest --database users --hostname database2.example.org --port 5433 --username postgres --password trustsome1 +``` + +Or from the configuration file: + +```yaml +hooks: + postgresql_databases: + - name: users + hostname: database1.example.org + restore_hostname: database1.example.org + restore_port: 5433 + restore_username: postgres + restore_password: trustsome1 +``` + ### Limitations diff --git a/docs/how-to/extract-a-backup.md b/docs/how-to/extract-a-backup.md index 5a4aa6fa..97515701 100644 --- a/docs/how-to/extract-a-backup.md +++ b/docs/how-to/extract-a-backup.md @@ -45,6 +45,22 @@ in the right place before running the command—or see below about the `--destination` flag. +## Extract the configuration file used to create an archive + +New in version 1.7.15 Borgmatic +also stores the configuration file used to create an archive, inside the +archive itself. This is useful in cases where you've lost your configuration +file, or you want to see what configuration was used to create a particular +archive. + +To extract the configuration file from an archive, use the `config bootstrap` action: + +```bash +borgmatic config bootstrap --repository repo.borg --destination /tmp +``` + +This extracts the configuration file from the latest archive in the repository `repo.borg` to `/tmp/config.yaml`. + ## Repository selection If you have a single repository in your borgmatic configuration file(s), no From adfb89ee65835d3fc969759df97eb79ee2758fe1 Mon Sep 17 00:00:00 2001 From: Divyansh Singh Date: Sat, 29 Jul 2023 00:16:04 +0530 Subject: [PATCH 2/3] improve docs - wittens suggestions --- docs/how-to/backup-your-databases.md | 23 +++++++-------- docs/how-to/extract-a-backup.md | 43 +++++++++++++++++----------- 2 files changed, 37 insertions(+), 29 deletions(-) diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index 2eaa1d0f..25a664e4 100644 --- a/docs/how-to/backup-your-databases.md +++ b/docs/how-to/backup-your-databases.md @@ -339,10 +339,10 @@ borgmatic restore --archive latest --database users --schema tentant1 ``` ### Restore to an alternate host -New in version 1.7.15 You -can restore a database dump to a host other than the one from which it was -originally dumped. You can also change other connection parameters like the -username, password, and port. This can be done from the command line: +New in version 1.7.15 +A database dump can be restored to a host other than the one from which it was +originally dumped. The connection parameters like the username, password, and +port can also be changed. This can be done from the command line: ```bash borgmatic restore --archive latest --database users --hostname database2.example.org --port 5433 --username postgres --password trustsome1 @@ -351,14 +351,13 @@ borgmatic restore --archive latest --database users --hostname database2.example Or from the configuration file: ```yaml -hooks: - postgresql_databases: - - name: users - hostname: database1.example.org - restore_hostname: database1.example.org - restore_port: 5433 - restore_username: postgres - restore_password: trustsome1 +postgresql_databases: + - name: users + hostname: database1.example.org + restore_hostname: database1.example.org + restore_port: 5433 + restore_username: postgres + restore_password: trustsome1 ``` diff --git a/docs/how-to/extract-a-backup.md b/docs/how-to/extract-a-backup.md index 97515701..4d447677 100644 --- a/docs/how-to/extract-a-backup.md +++ b/docs/how-to/extract-a-backup.md @@ -44,23 +44,6 @@ entire contents of the archive to the current directory, so make sure you're in the right place before running the command—or see below about the `--destination` flag. - -## Extract the configuration file used to create an archive - -New in version 1.7.15 Borgmatic -also stores the configuration file used to create an archive, inside the -archive itself. This is useful in cases where you've lost your configuration -file, or you want to see what configuration was used to create a particular -archive. - -To extract the configuration file from an archive, use the `config bootstrap` action: - -```bash -borgmatic config bootstrap --repository repo.borg --destination /tmp -``` - -This extracts the configuration file from the latest archive in the repository `repo.borg` to `/tmp/config.yaml`. - ## Repository selection If you have a single repository in your borgmatic configuration file(s), no @@ -161,3 +144,29 @@ When you're all done exploring your files, unmount your mount point. No ```bash borgmatic umount --mount-point /mnt ``` + +## Extract the configuration files used to create an archive + +New in version 1.7.15 borgmatic +automatically stores all the configuration files used to create an archive inside the +archive itself. This is useful in cases where you've lost a configuration +file, or you want to see what configurations were used to create a particular +archive. + +To extract the configuration files from an archive, use the `config bootstrap` action. For example: + +```bash +borgmatic config bootstrap --repository repo.borg --destination /tmp +``` + +This extracts the configuration file from the latest archive in the repository `repo.borg` to `/tmp/etc/borgmatic/config.yaml`, assuming that the only configuration file used to create this archive was located at `/etc/borgmatic/config.yaml` when the archive was created. + +Note that to run the `config bootstrap` action, you don't need to have a borgmatic configuration file. You only need to specify the repository to use via the `--repository` flag, borgmatic will figure out the rest. + +If a destination directory is not specified, the configuration files will be extracted to their original locations, silently **overwriting** any configuration files that may already exist. For example, if a configuration file was located at `/etc/borgmatic/config.yaml` when the archive was created, it will be extracted to `/etc/borgmatic/config.yaml` too. This is in line with the `extract` action, which extracts files to their original locations by default. + +If you want to extract the configuration file from a specific archive, use the `--archive` flag: + +```bash +borgmatic config bootstrap --repository repo.borg --archive host-2023-01-02T04:06:07.080910 --destination /tmp +``` From 59465b256dcd64cd997cc6ab5400f4c9fe16e27d Mon Sep 17 00:00:00 2001 From: Divyansh Singh Date: Mon, 31 Jul 2023 23:50:46 +0530 Subject: [PATCH 3/3] Apply suggestions from code review --- docs/how-to/extract-a-backup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/extract-a-backup.md b/docs/how-to/extract-a-backup.md index 4d447677..2622c763 100644 --- a/docs/how-to/extract-a-backup.md +++ b/docs/how-to/extract-a-backup.md @@ -150,7 +150,7 @@ borgmatic umount --mount-point /mnt New in version 1.7.15 borgmatic automatically stores all the configuration files used to create an archive inside the archive itself. This is useful in cases where you've lost a configuration -file, or you want to see what configurations were used to create a particular +file or you want to see what configurations were used to create a particular archive. To extract the configuration files from an archive, use the `config bootstrap` action. For example: @@ -161,9 +161,9 @@ borgmatic config bootstrap --repository repo.borg --destination /tmp This extracts the configuration file from the latest archive in the repository `repo.borg` to `/tmp/etc/borgmatic/config.yaml`, assuming that the only configuration file used to create this archive was located at `/etc/borgmatic/config.yaml` when the archive was created. -Note that to run the `config bootstrap` action, you don't need to have a borgmatic configuration file. You only need to specify the repository to use via the `--repository` flag, borgmatic will figure out the rest. +Note that to run the `config bootstrap` action, you don't need to have a borgmatic configuration file. You only need to specify the repository to use via the `--repository` flag; borgmatic will figure out the rest. -If a destination directory is not specified, the configuration files will be extracted to their original locations, silently **overwriting** any configuration files that may already exist. For example, if a configuration file was located at `/etc/borgmatic/config.yaml` when the archive was created, it will be extracted to `/etc/borgmatic/config.yaml` too. This is in line with the `extract` action, which extracts files to their original locations by default. +If a destination directory is not specified, the configuration files will be extracted to their original locations, silently **overwriting** any configuration files that may already exist. For example, if a configuration file was located at `/etc/borgmatic/config.yaml` when the archive was created, it will be extracted to `/etc/borgmatic/config.yaml` too. If you want to extract the configuration file from a specific archive, use the `--archive` flag: