Documentation for database restores (#229).
This commit is contained in:
parent
2c46f53ef6
commit
bd3c51fc5a
9 changed files with 189 additions and 84 deletions
6
NEWS
6
NEWS
|
@ -1,5 +1,7 @@
|
||||||
1.4.1.dev0
|
1.4.1
|
||||||
* #229: Restore backed up PostgreSQL databases via "borgmatic restore" sub-command.
|
* #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:
|
* Documentation on how to develop borgmatic's documentation:
|
||||||
https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/#documentation-development
|
https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/#documentation-development
|
||||||
|
|
||||||
|
|
|
@ -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/)
|
* [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/)
|
* [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/)
|
* [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/)
|
* [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/)
|
* [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/)
|
* [Upgrade borgmatic](https://torsion.org/borgmatic/docs/how-to/upgrade/)
|
||||||
|
|
|
@ -3,7 +3,7 @@ FROM python:3.7.4-alpine3.10 as borgmatic
|
||||||
COPY . /app
|
COPY . /app
|
||||||
RUN pip install --no-cache /app && generate-borgmatic-config && chmod +r /etc/borgmatic/config.yaml
|
RUN pip install --no-cache /app && generate-borgmatic-config && chmod +r /etc/borgmatic/config.yaml
|
||||||
RUN borgmatic --help > /command-line.txt \
|
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 \
|
echo -e "\n--------------------------------------------------------------------------------\n" >> /command-line.txt \
|
||||||
&& borgmatic "$action" --help >> /command-line.txt; done
|
&& borgmatic "$action" --help >> /command-line.txt; done
|
||||||
|
|
||||||
|
|
|
@ -165,6 +165,7 @@ ul {
|
||||||
}
|
}
|
||||||
li {
|
li {
|
||||||
padding: .25em 0;
|
padding: .25em 0;
|
||||||
|
line-height: 1.5;
|
||||||
}
|
}
|
||||||
li ul {
|
li ul {
|
||||||
margin: .5em 0;
|
margin: .5em 0;
|
||||||
|
|
|
@ -49,6 +49,16 @@ hooks:
|
||||||
Note that you may need to use a `username` of the `postgres` superuser for
|
Note that you may need to use a `username` of the `postgres` superuser for
|
||||||
this to work.
|
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
|
## Supported databases
|
||||||
|
|
||||||
As of now, borgmatic only supports PostgreSQL databases directly. But see
|
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
|
ticket](https://torsion.org/borgmatic/#issues) for additional database systems
|
||||||
that you'd like supported.
|
that you'd like supported.
|
||||||
|
|
||||||
|
|
||||||
## Database restoration
|
## Database restoration
|
||||||
|
|
||||||
borgmatic does not yet perform integrated database restoration when you
|
To restore a database dump from an archive, use the `borgmatic restore`
|
||||||
[restore a backup](http://localhost:8080/docs/how-to/restore-a-backup/), but
|
action. But the first step is to figure out which archive to restore from. A
|
||||||
that feature is coming in a future release. In the meantime, you can restore
|
good way to do that is to use the `list` action:
|
||||||
a database manually after restoring a dump file in the `~/.borgmatic` path.
|
|
||||||
|
```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
|
## 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
|
after backups. So if necessary, you can use these hooks to create database
|
||||||
dumps with any database system.
|
dumps with any database system.
|
||||||
|
|
||||||
|
|
||||||
## Related documentation
|
## Related documentation
|
||||||
|
|
||||||
* [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)
|
* [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/)
|
* [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/)
|
* [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/)
|
||||||
|
|
82
docs/how-to/extract-a-backup.md
Normal file
82
docs/how-to/extract-a-backup.md
Normal file
|
@ -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/)
|
|
@ -47,8 +47,8 @@ from borgmatic for a configured interval.
|
||||||
really want confidence that your backups are not only running but are
|
really want confidence that your backups are not only running but are
|
||||||
restorable as well, you can configure particular [consistency
|
restorable as well, you can configure particular [consistency
|
||||||
checks](https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#consistency-check-configuration)
|
checks](https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#consistency-check-configuration)
|
||||||
or even script full [restore
|
or even script full [extract
|
||||||
tests](https://torsion.org/borgmatic/docs/how-to/restore-a-backup/).
|
tests](https://torsion.org/borgmatic/docs/how-to/extract-a-backup/).
|
||||||
|
|
||||||
|
|
||||||
## Error hooks
|
## 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/)
|
* [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/)
|
* [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/)
|
* [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/)
|
* [Develop on borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/)
|
||||||
|
|
|
@ -1,71 +1,3 @@
|
||||||
---
|
<head>
|
||||||
title: How to restore a backup
|
<meta http-equiv='refresh' content='0; URL=https://torsion.org/borgmatic/docs/how-to/extract-a-backup/'>
|
||||||
---
|
</head>
|
||||||
## 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/)
|
|
||||||
|
|
2
setup.py
2
setup.py
|
@ -1,6 +1,6 @@
|
||||||
from setuptools import find_packages, setup
|
from setuptools import find_packages, setup
|
||||||
|
|
||||||
VERSION = '1.4.1.dev0'
|
VERSION = '1.4.1'
|
||||||
|
|
||||||
|
|
||||||
setup(
|
setup(
|
||||||
|
|
Loading…
Reference in a new issue