mirror of
https://git.anonymousland.org/anonymousland/synapse-product.git
synced 2024-09-09 15:02:09 +00:00
Update postgres docs (#9989)
This commit is contained in:
parent
6482075c95
commit
6660912226
@ -1 +1 @@
|
|||||||
Fix outdated minimum PostgreSQL version in postgres.md.
|
Updates to the PostgreSQL documentation (`postgres.md`).
|
||||||
|
1
changelog.d/9989.doc
Normal file
1
changelog.d/9989.doc
Normal file
@ -0,0 +1 @@
|
|||||||
|
Updates to the PostgreSQL documentation (`postgres.md`).
|
182
docs/postgres.md
182
docs/postgres.md
@ -33,28 +33,15 @@ Assuming your PostgreSQL database user is called `postgres`, first authenticate
|
|||||||
# Or, if your system uses sudo to get administrative rights
|
# Or, if your system uses sudo to get administrative rights
|
||||||
sudo -u postgres bash
|
sudo -u postgres bash
|
||||||
|
|
||||||
Then, create a user ``synapse_user`` with:
|
Then, create a postgres user and a database with:
|
||||||
|
|
||||||
|
# this will prompt for a password for the new user
|
||||||
createuser --pwprompt synapse_user
|
createuser --pwprompt synapse_user
|
||||||
|
|
||||||
Before you can authenticate with the `synapse_user`, you must create a
|
createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse
|
||||||
database that it can access. To create a database, first connect to the
|
|
||||||
database with your database user:
|
|
||||||
|
|
||||||
su - postgres # Or: sudo -u postgres bash
|
The above will create a user called `synapse_user`, and a database called
|
||||||
psql
|
`synapse`.
|
||||||
|
|
||||||
and then run:
|
|
||||||
|
|
||||||
CREATE DATABASE synapse
|
|
||||||
ENCODING 'UTF8'
|
|
||||||
LC_COLLATE='C'
|
|
||||||
LC_CTYPE='C'
|
|
||||||
template=template0
|
|
||||||
OWNER synapse_user;
|
|
||||||
|
|
||||||
This would create an appropriate database named `synapse` owned by the
|
|
||||||
`synapse_user` user (which must already have been created as above).
|
|
||||||
|
|
||||||
Note that the PostgreSQL database *must* have the correct encoding set
|
Note that the PostgreSQL database *must* have the correct encoding set
|
||||||
(as shown above), otherwise it will not be able to store UTF8 strings.
|
(as shown above), otherwise it will not be able to store UTF8 strings.
|
||||||
@ -63,79 +50,6 @@ You may need to enable password authentication so `synapse_user` can
|
|||||||
connect to the database. See
|
connect to the database. See
|
||||||
<https://www.postgresql.org/docs/current/auth-pg-hba-conf.html>.
|
<https://www.postgresql.org/docs/current/auth-pg-hba-conf.html>.
|
||||||
|
|
||||||
If you get an error along the lines of `FATAL: Ident authentication failed for
|
|
||||||
user "synapse_user"`, you may need to use an authentication method other than
|
|
||||||
`ident`:
|
|
||||||
|
|
||||||
* If the `synapse_user` user has a password, add the password to the `database:`
|
|
||||||
section of `homeserver.yaml`. Then add the following to `pg_hba.conf`:
|
|
||||||
|
|
||||||
```
|
|
||||||
host synapse synapse_user ::1/128 md5 # or `scram-sha-256` instead of `md5` if you use that
|
|
||||||
```
|
|
||||||
|
|
||||||
* If the `synapse_user` user does not have a password, then a password doesn't
|
|
||||||
have to be added to `homeserver.yaml`. But the following does need to be added
|
|
||||||
to `pg_hba.conf`:
|
|
||||||
|
|
||||||
```
|
|
||||||
host synapse synapse_user ::1/128 trust
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that line order matters in `pg_hba.conf`, so make sure that if you do add a
|
|
||||||
new line, it is inserted before:
|
|
||||||
|
|
||||||
```
|
|
||||||
host all all ::1/128 ident
|
|
||||||
```
|
|
||||||
|
|
||||||
### Fixing incorrect `COLLATE` or `CTYPE`
|
|
||||||
|
|
||||||
Synapse will refuse to set up a new database if it has the wrong values of
|
|
||||||
`COLLATE` and `CTYPE` set, and will log warnings on existing databases. Using
|
|
||||||
different locales can cause issues if the locale library is updated from
|
|
||||||
underneath the database, or if a different version of the locale is used on any
|
|
||||||
replicas.
|
|
||||||
|
|
||||||
The safest way to fix the issue is to take a dump and recreate the database with
|
|
||||||
the correct `COLLATE` and `CTYPE` parameters (as shown above). It is also possible to change the
|
|
||||||
parameters on a live database and run a `REINDEX` on the entire database,
|
|
||||||
however extreme care must be taken to avoid database corruption.
|
|
||||||
|
|
||||||
Note that the above may fail with an error about duplicate rows if corruption
|
|
||||||
has already occurred, and such duplicate rows will need to be manually removed.
|
|
||||||
|
|
||||||
|
|
||||||
## Fixing inconsistent sequences error
|
|
||||||
|
|
||||||
Synapse uses Postgres sequences to generate IDs for various tables. A sequence
|
|
||||||
and associated table can get out of sync if, for example, Synapse has been
|
|
||||||
downgraded and then upgraded again.
|
|
||||||
|
|
||||||
To fix the issue shut down Synapse (including any and all workers) and run the
|
|
||||||
SQL command included in the error message. Once done Synapse should start
|
|
||||||
successfully.
|
|
||||||
|
|
||||||
|
|
||||||
## Tuning Postgres
|
|
||||||
|
|
||||||
The default settings should be fine for most deployments. For larger
|
|
||||||
scale deployments tuning some of the settings is recommended, details of
|
|
||||||
which can be found at
|
|
||||||
<https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server>.
|
|
||||||
|
|
||||||
In particular, we've found tuning the following values helpful for
|
|
||||||
performance:
|
|
||||||
|
|
||||||
- `shared_buffers`
|
|
||||||
- `effective_cache_size`
|
|
||||||
- `work_mem`
|
|
||||||
- `maintenance_work_mem`
|
|
||||||
- `autovacuum_work_mem`
|
|
||||||
|
|
||||||
Note that the appropriate values for those fields depend on the amount
|
|
||||||
of free memory the database host has available.
|
|
||||||
|
|
||||||
## Synapse config
|
## Synapse config
|
||||||
|
|
||||||
When you are ready to start using PostgreSQL, edit the `database`
|
When you are ready to start using PostgreSQL, edit the `database`
|
||||||
@ -165,6 +79,10 @@ may block for an extended period while it waits for a response from the
|
|||||||
database server. Example values might be:
|
database server. Example values might be:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
database:
|
||||||
|
args:
|
||||||
|
# ... as above
|
||||||
|
|
||||||
# seconds of inactivity after which TCP should send a keepalive message to the server
|
# seconds of inactivity after which TCP should send a keepalive message to the server
|
||||||
keepalives_idle: 10
|
keepalives_idle: 10
|
||||||
|
|
||||||
@ -177,6 +95,26 @@ keepalives_interval: 10
|
|||||||
keepalives_count: 3
|
keepalives_count: 3
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Tuning Postgres
|
||||||
|
|
||||||
|
The default settings should be fine for most deployments. For larger
|
||||||
|
scale deployments tuning some of the settings is recommended, details of
|
||||||
|
which can be found at
|
||||||
|
<https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server>.
|
||||||
|
|
||||||
|
In particular, we've found tuning the following values helpful for
|
||||||
|
performance:
|
||||||
|
|
||||||
|
- `shared_buffers`
|
||||||
|
- `effective_cache_size`
|
||||||
|
- `work_mem`
|
||||||
|
- `maintenance_work_mem`
|
||||||
|
- `autovacuum_work_mem`
|
||||||
|
|
||||||
|
Note that the appropriate values for those fields depend on the amount
|
||||||
|
of free memory the database host has available.
|
||||||
|
|
||||||
|
|
||||||
## Porting from SQLite
|
## Porting from SQLite
|
||||||
|
|
||||||
### Overview
|
### Overview
|
||||||
@ -185,9 +123,8 @@ The script `synapse_port_db` allows porting an existing synapse server
|
|||||||
backed by SQLite to using PostgreSQL. This is done in as a two phase
|
backed by SQLite to using PostgreSQL. This is done in as a two phase
|
||||||
process:
|
process:
|
||||||
|
|
||||||
1. Copy the existing SQLite database to a separate location (while the
|
1. Copy the existing SQLite database to a separate location and run
|
||||||
server is down) and running the port script against that offline
|
the port script against that offline database.
|
||||||
database.
|
|
||||||
2. Shut down the server. Rerun the port script to port any data that
|
2. Shut down the server. Rerun the port script to port any data that
|
||||||
has come in since taking the first snapshot. Restart server against
|
has come in since taking the first snapshot. Restart server against
|
||||||
the PostgreSQL database.
|
the PostgreSQL database.
|
||||||
@ -245,3 +182,60 @@ PostgreSQL database configuration file `homeserver-postgres.yaml`:
|
|||||||
./synctl start
|
./synctl start
|
||||||
|
|
||||||
Synapse should now be running against PostgreSQL.
|
Synapse should now be running against PostgreSQL.
|
||||||
|
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Alternative auth methods
|
||||||
|
|
||||||
|
If you get an error along the lines of `FATAL: Ident authentication failed for
|
||||||
|
user "synapse_user"`, you may need to use an authentication method other than
|
||||||
|
`ident`:
|
||||||
|
|
||||||
|
* If the `synapse_user` user has a password, add the password to the `database:`
|
||||||
|
section of `homeserver.yaml`. Then add the following to `pg_hba.conf`:
|
||||||
|
|
||||||
|
```
|
||||||
|
host synapse synapse_user ::1/128 md5 # or `scram-sha-256` instead of `md5` if you use that
|
||||||
|
```
|
||||||
|
|
||||||
|
* If the `synapse_user` user does not have a password, then a password doesn't
|
||||||
|
have to be added to `homeserver.yaml`. But the following does need to be added
|
||||||
|
to `pg_hba.conf`:
|
||||||
|
|
||||||
|
```
|
||||||
|
host synapse synapse_user ::1/128 trust
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that line order matters in `pg_hba.conf`, so make sure that if you do add a
|
||||||
|
new line, it is inserted before:
|
||||||
|
|
||||||
|
```
|
||||||
|
host all all ::1/128 ident
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fixing incorrect `COLLATE` or `CTYPE`
|
||||||
|
|
||||||
|
Synapse will refuse to set up a new database if it has the wrong values of
|
||||||
|
`COLLATE` and `CTYPE` set, and will log warnings on existing databases. Using
|
||||||
|
different locales can cause issues if the locale library is updated from
|
||||||
|
underneath the database, or if a different version of the locale is used on any
|
||||||
|
replicas.
|
||||||
|
|
||||||
|
The safest way to fix the issue is to dump the database and recreate it with
|
||||||
|
the correct locale parameter (as shown above). It is also possible to change the
|
||||||
|
parameters on a live database and run a `REINDEX` on the entire database,
|
||||||
|
however extreme care must be taken to avoid database corruption.
|
||||||
|
|
||||||
|
Note that the above may fail with an error about duplicate rows if corruption
|
||||||
|
has already occurred, and such duplicate rows will need to be manually removed.
|
||||||
|
|
||||||
|
### Fixing inconsistent sequences error
|
||||||
|
|
||||||
|
Synapse uses Postgres sequences to generate IDs for various tables. A sequence
|
||||||
|
and associated table can get out of sync if, for example, Synapse has been
|
||||||
|
downgraded and then upgraded again.
|
||||||
|
|
||||||
|
To fix the issue shut down Synapse (including any and all workers) and run the
|
||||||
|
SQL command included in the error message. Once done Synapse should start
|
||||||
|
successfully.
|
||||||
|
Loading…
Reference in New Issue
Block a user