Documentation for database restores (#229).
This commit is contained in:
Dan Helfman
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
|
||||
* #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
|
||||
|
||||
|
|
|
|||
|
|
@ -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/)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -165,6 +165,7 @@ ul {
|
|||
}
|
||||
li {
|
||||
padding: .25em 0;
|
||||
line-height: 1.5;
|
||||
}
|
||||
li ul {
|
||||
margin: .5em 0;
|
||||
|
|
|
|||
|
|
@ -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/)
|
||||
|
|
|
|||
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
|
||||
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/)
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
2
setup.py
2
setup.py
|
|
@ -1,6 +1,6 @@
|
|||
from setuptools import find_packages, setup
|
||||
|
||||
VERSION = '1.4.1.dev0'
|
||||
VERSION = '1.4.1'
|
||||
|
||||
|
||||
setup(
|
||||
|
|
|
|||
Loading…
Reference in a new issue