Add PostgreSQL backup information

This commit is contained in:
Slavi Pantaleev 2019-02-09 14:36:47 +02:00
parent 42c4de348c
commit 70b2f07fec
6 changed files with 65 additions and 28 deletions

View file

@ -294,7 +294,7 @@ Note: Currently the dockerized nginx doesn't support TLSv1.3. See https://github
The playbook now installs [Postgres 11](https://www.postgresql.org/about/news/1894/) by default.
If you have have an existing setup, it's likely running on an older Postgres version (9.x or 10.x). You can easily upgrade by following the [Maintenance / upgrading PostgreSQL](docs/maintenance-upgrading-postgres.md) guide.
If you have have an existing setup, it's likely running on an older Postgres version (9.x or 10.x). You can easily upgrade by following the [upgrading PostgreSQL guide](docs/maintenance-postgres.md#upgrading-postgresql).
## (BC Break) Renaming playbook variables

View file

@ -16,7 +16,7 @@
- [Maintenance / upgrading services](maintenance-upgrading-services.md)
- [Maintenance / upgrading PostgreSQL](maintenance-upgrading-postgres.md)
- [Maintenance / PostgreSQL](maintenance-postgres.md)
- [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)

View file

@ -18,6 +18,4 @@ sudo journalctl -fu matrix-synapse
## Postgres
You can access the Postgres command line interface using the script installed on your server at `/usr/local/bin/matrix-postgres-cli`.
This playbook attempts to preserve the Postgres version it starts with. When you are ready to upgrade to a new Postgres version, read through the [guide for upgrading PostgreSQL](maintenance-upgrading-postgres.md).
See the dedicated [PostgreSQL Maintenance](maintenances-postgres.md) documentation page.

View file

@ -0,0 +1,61 @@
# PostgreSQL maintenance
This document shows you how to perform various maintenance tasks related to the Postgres database server used by Matrix.
Table of contents:
- [Getting a database terminal](#getting-a-database-terminal), for when you wish to execute SQL queries
- [Backing up PostgreSQL](#backing-up-postgresql), for when you wish to make a backup
- [Upgrading PostgreSQL](#upgrading-postgresql), for upgrading to new major versions of PostgreSQL. Such **manual upgrades are sometimes required**.
## Getting a database terminal
You can use the `/usr/local/bin/matrix-postgres-cli` tool to get interactive terminal access ([psql](https://www.postgresql.org/docs/11/app-psql.html)) to the PostgreSQL server.
If you are using an [external Postgres server](configuring-playbook-external-postgres.md), the above tool will not be available.
## Backing up PostgreSQL
To make a back up of the current PostgreSQL database, make sure it's running and then execute a command like this on the server:
```bash
docker run \
--rm \
--network matrix \
--env-file=/matrix/postgres/env-postgres-psql \
postgres:11.1-alpine \
pg_dump -h matrix-postgres \
| gzip -c \
> /postgres.sql.gz
```
If you are using an [external Postgres server](configuring-playbook-external-postgres.md), the above command will not work, because the credentials file (`/matrix/postgres/env-postgres-psql`) is not available.
## Upgrading PostgreSQL
Unless you are using an [external Postgres server](configuring-playbook-external-postgres.md), this playbook initially installs Postgres for you.
Once installed, the playbook attempts to preserve the Postgres version it starts with.
This is because newer Postgres versions cannot start with data generated by older Postgres versions.
Upgrades must be performed manually.
This playbook can upgrade your existing Postgres setup with the following command:
ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres
**The old Postgres data directory is backed up** automatically, by renaming to `/matrix/postgres-auto-upgrade-backup`.
To rename to a different path, pass some extra flags to the command above, like this: `--extra-vars="postgres_auto_upgrade_backup_data_path=/another/disk/matrix-postgres-before-upgrade"`
The auto-upgrade-backup directory stays around forever, until you **manually decide to delete it**.
As part of the upgrade, the database is dumped to `/tmp`, an upgraded and empty Postgres server is started, and then the dump is restored into the new server.
To use a different directory for the dump, pass some extra flags to the command above, like this: `--extra-vars="postgres_dump_dir=/directory/to/dump/here"`
**ONLY one database is migrated** (the one specified in `matrix_postgres_db_name`, named `homeserver` by default).
If you've created other databases in that database instance (something this playbook never does and never advises), data will be lost.

View file

@ -1,22 +0,0 @@
# Upgrading PostgreSQL
If you're not using an external Postgres server, this playbook initially installs Postgres for you.
Once installed like that, this playbook attempts to preserve the Postgres version it starts with.
This is because newer Postgres versions cannot start with data generated by older Postgres versions.
An upgrade must be performed.
This playbook can upgrade your existing Postgres setup with the following command:
ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres
**The old Postgres data directory is backed up** by renaming to `/matrix/postgres-auto-upgrade-backup`, by default.
To rename to a different path, pass some extra flags to the command above, like this: `--extra-vars="postgres_auto_upgrade_backup_data_path=/another/disk/matrix-postgres-before-upgrade"`
The auto-upgrade-backup directory stays around forever, until you **manually decide to delete it**.
As part of the upgrade, the database is dumped to `/tmp`, upgraded and then restored from that dump.
To use a different directory, pass some extra flags to the command above, like this: `--extra-vars="postgres_dump_dir=/directory/to/dump/here"`
**ONLY one database is migrated** (the one specified in `matrix_postgres_db_name`, named `homeserver` by default).
If you've created other databases in that database instance (something this playbook never does and never advises), data will be lost.

View file

@ -14,4 +14,4 @@ To upgrade the services:
- restart the services: `ansible-playbook -i inventory/hosts setup.yml --tags=start`
**Note**: major version upgrades are not done to the internal PostgreSQL database. To upgrade that one, refer to the [upgrading PostgreSQL document](maintenance-upgrading-postgres.md).
**Note**: major version upgrades are not done to the internal PostgreSQL database. To upgrade that one, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).