77 lines
3.5 KiB
Markdown
77 lines
3.5 KiB
Markdown
# 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
|
|
|
|
- [Vacuuming PostgreSQL](#vacuuming-postgresql), for when you wish to run a Postgres [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html) (optimizing disk space)
|
|
|
|
- [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.
|
|
|
|
|
|
## Vacuuming PostgreSQL
|
|
|
|
To perform a `FULL` Postgres [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html), run the playbook with `--tags=run-postgres-vacuum`.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
ansible-playbook -i inventory/hosts setup.yml --tags=run-postgres-vacuum
|
|
```
|
|
|
|
**Note**: this will automatically stop Synapse temporarily and restart it later. You'll also need plenty of available disk space in your Postgres data directory (usually `/matrix/postgres/data`).
|
|
|
|
|
|
## 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.
|