diff --git a/CHANGES.md b/CHANGES.md
index 342768c8c8..a8a45e49ad 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -58,12 +58,19 @@ Bugfixes
Synapse 1.12.0 (2020-03-23)
===========================
-No significant changes since 1.12.0rc1.
-
Debian packages and Docker images are rebuilt using the latest versions of
dependency libraries, including Twisted 20.3.0. **Please see security advisory
below**.
+Potential slow database update during upgrade
+---------------------------------------------
+
+Synapse 1.12.0 includes a database update which is run as part of the upgrade,
+and which may take some time (several hours in the case of a large
+server). Synapse will not respond to HTTP requests while this update is taking
+place. For imformation on seeing if you are affected, and workaround if you
+are, see the [upgrade notes](UPGRADE.rst#upgrading-to-v1120).
+
Security advisory
-----------------
diff --git a/INSTALL.md b/INSTALL.md
index c0926ba590..8ded6e9092 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -36,7 +36,7 @@ that your email address is probably `user@example.com` rather than
System requirements:
- POSIX-compliant system (tested on Linux & OS X)
-- Python 3.5, 3.6, 3.7 or 3.8.
+- Python 3.5.2 or later, up to Python 3.8.
- At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org
Synapse is written in Python but some of the libraries it uses are written in
@@ -427,8 +427,8 @@ so, you will need to edit `homeserver.yaml`, as follows:
for having Synapse automatically provision and renew federation
certificates through ACME can be found at [ACME.md](docs/ACME.md).
Note that, as pointed out in that document, this feature will not
- work with installs set up after November 2019.
-
+ work with installs set up after November 2019.
+
If you are using your own certificate, be sure to use a `.pem` file that
includes the full certificate chain including any intermediate certificates
(for instance, if using certbot, use `fullchain.pem` as your certificate, not
diff --git a/UPGRADE.rst b/UPGRADE.rst
index 3cad8c2837..768d94a393 100644
--- a/UPGRADE.rst
+++ b/UPGRADE.rst
@@ -75,6 +75,71 @@ for example:
wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb
dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
+Upgrading to v1.12.0
+====================
+
+This version includes a database update which is run as part of the upgrade,
+and which may take some time (several hours in the case of a large
+server). Synapse will not respond to HTTP requests while this update is taking
+place.
+
+This is only likely to be a problem in the case of a server which is
+participating in many rooms.
+
+0. As with all upgrades, it is recommended that you have a recent backup of
+ your database which can be used for recovery in the event of any problems.
+
+1. As an initial check to see if you will be affected, you can try running the
+ following query from the `psql` or `sqlite3` console. It is safe to run it
+ while Synapse is still running.
+
+ .. code:: sql
+
+ SELECT MAX(q.v) FROM (
+ SELECT (
+ SELECT ej.json AS v
+ FROM state_events se INNER JOIN event_json ej USING (event_id)
+ WHERE se.room_id=rooms.room_id AND se.type='m.room.create' AND se.state_key=''
+ LIMIT 1
+ ) FROM rooms WHERE rooms.room_version IS NULL
+ ) q;
+
+ This query will take about the same amount of time as the upgrade process: ie,
+ if it takes 5 minutes, then it is likely that Synapse will be unresponsive for
+ 5 minutes during the upgrade.
+
+ If you consider an outage of this duration to be acceptable, no further
+ action is necessary and you can simply start Synapse 1.12.0.
+
+ If you would prefer to reduce the downtime, continue with the steps below.
+
+2. The easiest workaround for this issue is to manually
+ create a new index before upgrading. On PostgreSQL, his can be done as follows:
+
+ .. code:: sql
+
+ CREATE INDEX CONCURRENTLY tmp_upgrade_1_12_0_index
+ ON state_events(room_id) WHERE type = 'm.room.create';
+
+ The above query may take some time, but is also safe to run while Synapse is
+ running.
+
+ We assume that no SQLite users have databases large enough to be
+ affected. If you *are* affected, you can run a similar query, omitting the
+ ``CONCURRENTLY`` keyword. Note however that this operation may in itself cause
+ Synapse to stop running for some time. Synapse admins are reminded that
+ `SQLite is not recommended for use outside a test
+ environment <https://github.com/matrix-org/synapse/blob/master/README.rst#using-postgresql>`_.
+
+3. Once the index has been created, the ``SELECT`` query in step 1 above should
+ complete quickly. It is therefore safe to upgrade to Synapse 1.12.0.
+
+4. Once Synapse 1.12.0 has successfully started and is responding to HTTP
+ requests, the temporary index can be removed:
+
+ .. code:: sql
+
+ DROP INDEX tmp_upgrade_1_12_0_index;
Upgrading to v1.10.0
====================
diff --git a/docs/postgres.md b/docs/postgres.md
index e0793ecee8..ca7ef1cf3a 100644
--- a/docs/postgres.md
+++ b/docs/postgres.md
@@ -72,8 +72,7 @@ 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 per
-[docs/postgres.md](docs/postgres.md)). It is also possible to change the
+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.
diff --git a/docs/turn-howto.md b/docs/turn-howto.md
index 1bd3943f54..1e121ead6a 100644
--- a/docs/turn-howto.md
+++ b/docs/turn-howto.md
@@ -113,7 +113,7 @@ Your home server configuration file needs the following extra keys:
As an example, here is the relevant section of the config file for matrix.org:
turn_uris: [ "turn:turn.matrix.org:3478?transport=udp", "turn:turn.matrix.org:3478?transport=tcp" ]
- turn_shared_secret: n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons
+ turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons"
turn_user_lifetime: 86400000
turn_allow_guests: True
|
