Add PostgreSQL backup information

CHANGELOG.md

@@ -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

docs/README.md

@@ -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)
 

docs/maintenance-and-troubleshooting.md

@@ -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`.
+See the dedicated [PostgreSQL Maintenance](maintenances-postgres.md) documentation page.
-
-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).

docs/maintenance-postgres.md

@@ -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.

docs/maintenance-upgrading-postgres.md

@@ -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.

docs/maintenance-upgrading-services.md

@@ -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).