Merge pull request #580 from bertiebaggio/importing-postgres-table-ownership-workaround

importing-postgres.md: Add 'Troubleshooting' w/workaround for ownership

docs/importing-postgres.md

@@ -24,3 +24,54 @@ To import, run this command (make sure to replace `<server-path-to-postgres-dump
 	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_postgres_dump=<server-path-to-postgres-dump.sql>' --tags=import-postgres
 
 **Note**: `<server-path-to-postgres-dump.sql>` must be a file path to a Postgres dump file on the server (not on your local machine!).
+
+## Troubleshooting
+
+A table ownership issue can occur if you are importing from a Synapse installation which was both:
+
+ - migrated from SQLite to Postgres, and
+ - used a username other than 'synapse'
+
+In this case you may run into the following error during the import task:
+
+```
+"ERROR:  role \"synapse_user\" does not exist"
+```
+
+where `synapse_user` is the database username from the previous Synapse installation.
+
+This can be verified by examining the dump for ALTER TABLE statements which set OWNER TO that username:
+
+```Shell
+$ grep "ALTER TABLE" homeserver.sql"
+ALTER TABLE public.access_tokens OWNER TO synapse_user;
+ALTER TABLE public.account_data OWNER TO synapse_user;
+ALTER TABLE public.account_data_max_stream_id OWNER TO synapse_user;
+ALTER TABLE public.account_validity OWNER TO synapse_user;
+ALTER TABLE public.application_services_state OWNER TO synapse_user;
+...
+```
+
+It can be worked around by changing the username to `synapse`, for example by using `sed`:
+
+```Shell
+$ sed -i "s/synapse_user/synapse/g" homeserver.sql"
+```
+
+This uses sed to perform an 'in-place' (`-i`) replacement globally (`/g`), searching for `synapse user` and replacing with `synapse` (`s/synapse_user/synapse`). If your database username was different, change `synapse_user` to that username instead.
+
+Note that if the previous import failed with an error it may have made changes which are incompatible with re-running the import task right away; if you do so it may fail with an error such as:
+
+```
+ERROR:  relation \"access_tokens\" already exists
+```
+
+In this case you can use the command suggested in the import task to clear the database before retrying the import:
+
+```Shell
+# systemctl stop matrix-postgres
+# rm -rf /matrix/postgres/data/*
+# systemctl start matrix-postgres
+```
+
+Once the database is clear and the ownership of the tables has been fixed in the SQL file, the import task should succeed.