From 70b2f07fecca7c61a9921f9404a8efa549076c53 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Sat, 9 Feb 2019 14:36:47 +0200 Subject: [PATCH] Add PostgreSQL backup information --- CHANGELOG.md | 2 +- docs/README.md | 2 +- docs/maintenance-and-troubleshooting.md | 4 +- docs/maintenance-postgres.md | 61 +++++++++++++++++++++++++ docs/maintenance-upgrading-postgres.md | 22 --------- docs/maintenance-upgrading-services.md | 2 +- 6 files changed, 65 insertions(+), 28 deletions(-) create mode 100644 docs/maintenance-postgres.md delete mode 100644 docs/maintenance-upgrading-postgres.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b2083d6e..29781be6c 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index 53ac53983..35ba609a8 100644 --- a/docs/README.md +++ b/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) diff --git a/docs/maintenance-and-troubleshooting.md b/docs/maintenance-and-troubleshooting.md index 9ef9d70b4..ad0babc94 100644 --- a/docs/maintenance-and-troubleshooting.md +++ b/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`. - -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. diff --git a/docs/maintenance-postgres.md b/docs/maintenance-postgres.md new file mode 100644 index 000000000..4be26a805 --- /dev/null +++ b/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. diff --git a/docs/maintenance-upgrading-postgres.md b/docs/maintenance-upgrading-postgres.md deleted file mode 100644 index c41712f37..000000000 --- a/docs/maintenance-upgrading-postgres.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/docs/maintenance-upgrading-services.md b/docs/maintenance-upgrading-services.md index 2ab8799b1..8530d8bc9 100644 --- a/docs/maintenance-upgrading-services.md +++ b/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).