sync with previous repo

roles/matrix-postgres/defaults/main.yml

@@ -0,0 +1,95 @@
+matrix_postgres_enabled: true
+
+matrix_postgres_connection_hostname: "matrix-postgres"
+matrix_postgres_connection_port: 5432
+matrix_postgres_connection_username: "matrix"
+matrix_postgres_connection_password: ""
+matrix_postgres_db_name: "matrix"
+
+matrix_postgres_base_path: "{{ matrix_base_data_path }}/postgres"
+matrix_postgres_data_path: "{{ matrix_postgres_base_path }}/data"
+
+matrix_postgres_architecture: amd64
+
+# matrix_postgres_docker_image_suffix controls whether we use Alpine-based images (`-alpine`) or the normal Debian-based images.
+# Alpine-based Postgres images are smaller and we usually prefer them, but they don't work on ARM32 (tested on a Raspberry Pi 3 running Raspbian 10.7).
+# On ARM32, `-alpine` images fail with the following error:
+# > LOG:  startup process (PID 37) was terminated by signal 11: Segmentation fault
+matrix_postgres_docker_image_suffix: "{{ '-alpine' if matrix_postgres_architecture in ['amd64', 'arm64'] else '' }}"
+
+matrix_postgres_docker_image_v9: "{{ matrix_container_global_registry_prefix }}postgres:9.6.22{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_v10: "{{ matrix_container_global_registry_prefix }}postgres:10.17{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_v11: "{{ matrix_container_global_registry_prefix }}postgres:11.12{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_v12: "{{ matrix_container_global_registry_prefix }}postgres:12.7{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_v13: "{{ matrix_container_global_registry_prefix }}postgres:13.3{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_latest: "{{ matrix_postgres_docker_image_v13 }}"
+
+# This variable is assigned at runtime. Overriding its value has no effect.
+matrix_postgres_docker_image_to_use: '{{ matrix_postgres_docker_image_latest }}'
+
+matrix_postgres_docker_image_force_pull: "{{ matrix_postgres_docker_image_to_use.endswith(':latest') }}"
+
+# A list of extra arguments to pass to the container
+matrix_postgres_container_extra_arguments: []
+
+# A list of extra arguments to pass to the postgres process
+# e.g. "-c 'max_connections=200'"
+matrix_postgres_process_extra_arguments: []
+
+# Controls whether the matrix-postgres container exposes a port (tcp/5432 in the
+# container) that can be used to access the database from outside the container (e.g. with psql)
+#
+# psql postgresql://username:password@localhost:<port>/database_name
+#
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:5432"), or empty string to not expose.
+matrix_postgres_container_postgres_bind_port: ""
+
+# A list of additional (databases and their credentials) to create.
+#
+# Example:
+# matrix_postgres_additional_databases:
+#   - name: matrix_appservice_discord
+#     username: matrix_appservice_discord
+#     password: some_password
+#   - name: matrix_appservice_slack
+#     username: matrix_appservice_slack
+#     password: some_password
+matrix_postgres_additional_databases: []
+
+# A list of roles/users to avoid creating when importing (or upgrading) the database.
+# If a dump file contains the roles and they've also been created beforehand (see `matrix_postgres_additional_databases`),
+# importing would fail.
+# We either need to not create them or to ignore the `CREATE ROLE` statements in the dump.
+matrix_postgres_import_roles_to_ignore: [matrix_postgres_connection_username]
+
+matrix_postgres_import_roles_ignore_regex: "^CREATE ROLE ({{ matrix_postgres_import_roles_to_ignore|join('|') }});"
+
+# A list of databases to avoid creating when importing (or upgrading) the database.
+# If a dump file contains the databases and they've also been created beforehand (see `matrix_postgres_additional_databases`),
+# importing would fail.
+# We either need to not create them or to ignore the `CREATE DATABASE` statements in the dump.
+matrix_postgres_import_databases_to_ignore: [matrix_postgres_db_name]
+
+matrix_postgres_import_databases_ignore_regex: "^CREATE DATABASE ({{ matrix_postgres_import_databases_to_ignore|join('|') }})\\s"
+
+# The number of seconds to wait after starting `matrix-postgres.service`
+# and before trying to run queries for creating additional databases/users against it.
+#
+# For most (subsequent) runs, Postgres would already be running, so no waiting will be happening at all.
+#
+# On ARM, we wait some more. ARM32 devices are especially known for being slow.
+# ARM64 likely don't need such a long delay, but it doesn't hurt too much having it.
+matrix_postgres_additional_databases_postgres_start_wait_timeout_seconds: "{{ 45 if matrix_postgres_architecture in ['arm32', 'arm64'] else 15 }}"
+
+
+matrix_postgres_pgloader_container_image_self_build: false
+matrix_postgres_pgloader_container_image_self_build_repo: "https://github.com/illagrenan/pgloader-docker.git"
+matrix_postgres_pgloader_container_image_self_build_repo_branch: "v{{ matrix_postgres_pgloader_docker_image_tag }}"
+matrix_postgres_pgloader_container_image_self_build_src_path: "{{ matrix_postgres_base_path }}/pgloader-container-src"
+
+# We use illagrenan/pgloader, instead of the more official dimitri/pgloader image,
+# because the official one only provides a `latest` tag.
+matrix_postgres_pgloader_docker_image: "{{ matrix_postgres_pgloader_docker_image_name_prefix }}illagrenan/pgloader:{{ matrix_postgres_pgloader_docker_image_tag }}"
+matrix_postgres_pgloader_docker_image_name_prefix: "{{ 'localhost/' if matrix_postgres_pgloader_container_image_self_build else matrix_container_global_registry_prefix }}"
+matrix_postgres_pgloader_docker_image_tag: "3.6.2"
+matrix_postgres_pgloader_docker_image_force_pull: "{{ matrix_postgres_pgloader_docker_image.endswith(':latest') }}"

roles/matrix-postgres/tasks/import_generic_sqlite_db.yml

@@ -0,0 +1,97 @@
+---
+
+# Pre-checks
+
+- name: Fail if Postgres not enabled
+  fail:
+    msg: "Postgres via the matrix-postgres role is not enabled (`matrix_postgres_enabled`). Cannot import."
+  when: "not matrix_postgres_enabled|bool"
+
+- name: Fail if playbook called incorrectly
+  fail:
+    msg: "The `sqlite_database_path` variable needs to be provided to this playbook, via --extra-vars"
+  when: "sqlite_database_path is not defined or sqlite_database_path.startswith('<')"
+
+- name: Check if the provided SQLite database file exists
+  stat:
+    path: "{{ sqlite_database_path }}"
+  register: sqlite_database_path_stat_result
+
+- name: Fail if provided SQLite database file doesn't exist
+  fail:
+    msg: "File cannot be found on the server at {{ sqlite_database_path }}"
+  when: "not sqlite_database_path_stat_result.stat.exists"
+
+# We either expect `postgres_db_connection_string` specifying a full Postgres database connection string,
+# or `postgres_connection_string_variable_name`, specifying a name of a variable, which contains a valid connection string.
+
+- block:
+    - name: Fail if postgres_connection_string_variable_name points to an undefined variable
+      fail: msg="postgres_connection_string_variable_name is defined, but there is no variable with the name `{{ postgres_connection_string_variable_name }}`"
+      when: "postgres_connection_string_variable_name not in vars"
+
+    - name: Get Postgres connection string from variable
+      set_fact:
+        postgres_db_connection_string: "{{ lookup('vars', postgres_connection_string_variable_name) }}"
+  when: 'postgres_connection_string_variable_name is defined'
+
+- name: Fail if playbook called incorrectly
+  fail:
+    msg: >-
+      Either a `postgres_db_connection_string` variable or a `postgres_connection_string_variable_name` needs to be provided to this playbook, via `--extra-vars`.
+      Example: `--extra-vars="postgres_db_connection_string=postgresql://username:password@localhost:<port>/database_name"` or `--extra-vars="postgres_connection_string_variable_name=matrix_appservice_discord_database_connString"`
+  when: "postgres_db_connection_string is not defined or not postgres_db_connection_string.startswith('postgresql://')"
+
+
+# Defaults
+
+- name: Set postgres_start_wait_time, if not provided
+  set_fact:
+    postgres_start_wait_time: 15
+  when: "postgres_start_wait_time|default('') == ''"
+
+
+# Actual import work
+
+- name: Ensure matrix-postgres is started
+  service:
+    name: matrix-postgres
+    state: started
+    daemon_reload: yes
+  register: matrix_postgres_service_start_result
+
+- name: Wait a bit, so that Postgres can start
+  wait_for:
+    timeout: "{{ postgres_start_wait_time }}"
+  delegate_to: 127.0.0.1
+  become: false
+  when: "matrix_postgres_service_start_result.changed|bool"
+
+- name: Import SQLite database from {{ sqlite_database_path }} into Postgres
+  command:
+    cmd: >-
+      {{ matrix_host_command_docker }} run
+      --rm
+      --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+      --cap-drop=ALL
+      --network={{ matrix_docker_network }}
+      --mount type=bind,src={{ sqlite_database_path }},dst=/in.db,ro
+      --entrypoint=/bin/sh
+      {{ matrix_postgres_pgloader_docker_image }}
+      -c
+      'pgloader /in.db {{ postgres_db_connection_string }}'
+
+- name: Archive SQLite database ({{ sqlite_database_path }} -> {{ sqlite_database_path }}.backup)
+  command:
+    cmd: "mv {{ sqlite_database_path }} {{ sqlite_database_path }}.backup"
+
+- name: Inject result
+  set_fact:
+    matrix_playbook_runtime_results: |
+      {{
+        matrix_playbook_runtime_results|default([])
+        +
+        [
+          "NOTE: Your SQLite database file has been imported into Postgres. The original file has been moved from `{{ sqlite_database_path }}` to `{{ sqlite_database_path }}.backup`. When you've confirmed that the import went well and everything works, you should be able to safely delete this file."
+        ]
+      }}

roles/matrix-postgres/tasks/import_postgres.yml

@@ -0,0 +1,106 @@
+---
+
+# Pre-checks
+
+- name: Fail if Postgres not enabled
+  fail:
+    msg: "Postgres via the matrix-postgres role is not enabled (`matrix_postgres_enabled`). Cannot import."
+  when: "not matrix_postgres_enabled|bool"
+
+- name: Fail if playbook called incorrectly
+  fail:
+    msg: "The `server_path_postgres_dump` variable needs to be provided to this playbook, via --extra-vars"
+  when: "server_path_postgres_dump is not defined or server_path_postgres_dump.startswith('<')"
+
+- name: Check if the provided Postgres dump file exists
+  stat:
+    path: "{{ server_path_postgres_dump }}"
+  register: result_server_path_postgres_dump_stat
+
+- name: Fail if provided Postgres dump file doesn't exists
+  fail:
+    msg: "File cannot be found on the server at {{ server_path_postgres_dump }}"
+  when: "not result_server_path_postgres_dump_stat.stat.exists"
+
+
+# Defaults
+
+- name: Set postgres_start_wait_time, if not provided
+  set_fact:
+    postgres_start_wait_time: 15
+  when: "postgres_start_wait_time|default('') == ''"
+
+- name: Set postgres_import_wait_time, if not provided
+  set_fact:
+    postgres_import_wait_time: "{{ 7 * 86400 }}"
+  when: "postgres_import_wait_time|default('') == ''"
+
+# By default, we connect and import into the main (`matrix`) database.
+# Single-database dumps for Synapse may wish to import into `synapse` instead.
+- name: Set postgres_default_import_database, if not provided
+  set_fact:
+    postgres_default_import_database: "{{ matrix_postgres_db_name }}"
+  when: "postgres_default_import_database|default('') == ''"
+
+# Actual import work
+
+- name: Ensure matrix-postgres is started
+  service:
+    name: matrix-postgres
+    state: started
+    daemon_reload: yes
+
+- name: Wait a bit, so that Postgres can start
+  wait_for:
+    timeout: "{{ postgres_start_wait_time }}"
+  delegate_to: 127.0.0.1
+  become: false
+
+- import_tasks: tasks/util/detect_existing_postgres_version.yml
+
+- name: Abort, if no existing Postgres version detected
+  fail:
+    msg: "Could not find existing Postgres installation"
+  when: "not matrix_postgres_detected_existing|bool"
+
+# Starting the database container had automatically created the default
+# role (`matrix_postgres_connection_username`) and database (`matrix_postgres_db_name`).
+# The dump most likely contains those same entries and would try to re-create them, leading to errors.
+# We need to skip over those lines.
+- name: Generate Postgres database import command
+  set_fact:
+    matrix_postgres_import_command: >-
+      {{ matrix_host_command_docker }} run --rm --name matrix-postgres-import
+      --log-driver=none
+      --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+      --cap-drop=ALL
+      --network={{ matrix_docker_network }}
+      --env-file={{ matrix_postgres_base_path }}/env-postgres-psql
+      --mount type=bind,src={{ server_path_postgres_dump }},dst=/{{ server_path_postgres_dump|basename }},ro
+      --entrypoint=/bin/sh
+      {{ matrix_postgres_docker_image_latest }}
+      -c "cat /{{ server_path_postgres_dump|basename }} |
+      {{ 'gunzip |' if server_path_postgres_dump.endswith('.gz') else '' }}
+      grep -vE '{{ matrix_postgres_import_roles_ignore_regex }}' |
+      grep -vE '{{ matrix_postgres_import_databases_ignore_regex }}' |
+      psql -v ON_ERROR_STOP=1 -h matrix-postgres --dbname={{ postgres_default_import_database }}"
+
+# This is a hack.
+# See: https://ansibledaily.com/print-to-standard-output-without-escaping/
+#
+# We want to run `debug: msg=".."`, but that dumps it as JSON and escapes double quotes within it,
+# which ruins the command (`matrix_postgres_import_command`)
+- name: Note about Postgres importing alternative
+  set_fact:
+    dummy: true
+  with_items:
+    - >-
+        Importing Postgres database using the following command: `{{ matrix_postgres_import_command }}`.
+        If this crashes, you can stop Postgres (`systemctl stop matrix-postgres`),
+        delete its existing data (`rm -rf {{ matrix_postgres_data_path }}/*`), start it again (`systemctl start matrix-postgres`)
+        and manually run the above import command directly on the server.
+
+- name: Perform Postgres database import
+  command: "{{ matrix_postgres_import_command }}"
+  async: "{{ postgres_import_wait_time }}"
+  poll: 10

roles/matrix-postgres/tasks/import_synapse_sqlite_db.yml

@@ -0,0 +1,86 @@
+---
+
+# Pre-checks
+
+- name: Fail if Postgres not enabled
+  fail:
+    msg: "Postgres via the matrix-postgres role is not enabled (`matrix_postgres_enabled`). Cannot import."
+  when: "not matrix_postgres_enabled|bool"
+
+- name: Fail if playbook called incorrectly
+  fail:
+    msg: "The `server_path_homeserver_db` variable needs to be provided to this playbook, via --extra-vars"
+  when: "server_path_homeserver_db is not defined or server_path_homeserver_db.startswith('<')"
+
+- name: Check if the provided SQLite homeserver.db file exists
+  stat:
+    path: "{{ server_path_homeserver_db }}"
+  register: result_server_path_homeserver_db_stat
+
+- name: Fail if provided SQLite homeserver.db file doesn't exist
+  fail:
+    msg: "File cannot be found on the server at {{ server_path_homeserver_db }}"
+  when: "not result_server_path_homeserver_db_stat.stat.exists"
+
+
+# Defaults
+
+- name: Set postgres_start_wait_time, if not provided
+  set_fact:
+    postgres_start_wait_time: 15
+  when: "postgres_start_wait_time|default('') == ''"
+
+
+# Actual import work
+
+- name: Ensure matrix-postgres is stopped
+  service:
+    name: matrix-postgres
+    state: stopped
+    daemon_reload: yes
+
+- name: Ensure postgres data is wiped out
+  file:
+    path: "{{ matrix_postgres_data_path }}"
+    state: absent
+
+- name: Ensure postgres data path exists
+  file:
+    path: "{{ matrix_postgres_data_path }}"
+    state: directory
+    mode: 0700
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
+- name: Ensure matrix-postgres is started
+  service:
+    name: matrix-postgres
+    state: restarted
+    daemon_reload: yes
+
+- name: Wait a bit, so that Postgres can start
+  wait_for:
+    timeout: "{{ postgres_start_wait_time }}"
+  delegate_to: 127.0.0.1
+  become: false
+
+# We don't use the `docker_container` module, because using it with `cap_drop` requires
+# a very recent version, which is not available for a lot of people yet.
+#
+# Also, some old `docker_container` versions were buggy and would leave containers behind
+# on failure, which we had to work around to allow retries (by re-running the playbook).
+- name: Import SQLite database into Postgres
+  command: |
+    docker run
+    --rm
+    --name=matrix-synapse-migrate
+    --log-driver=none
+    --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+    --cap-drop=ALL
+    --network={{ matrix_docker_network }}
+    --entrypoint=python
+    --mount type=bind,src={{ matrix_synapse_config_dir_path }},dst=/data
+    --mount type=bind,src={{ matrix_synapse_config_dir_path }},dst=/matrix-media-store-parent/media-store
+    --mount type=bind,src={{ server_path_homeserver_db }},dst=/{{ server_path_homeserver_db|basename }}
+    {{ matrix_synapse_docker_image }}
+    /usr/local/bin/synapse_port_db --sqlite-database /{{ server_path_homeserver_db|basename }} --postgres-config /data/homeserver.yaml

roles/matrix-postgres/tasks/init.yml

@@ -0,0 +1,3 @@
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-postgres.service'] }}"
+  when: matrix_postgres_enabled|bool

roles/matrix-postgres/tasks/main.yml

@@ -0,0 +1,43 @@
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- import_tasks: "{{ role_path }}/tasks/validate_config.yml"
+  when: "run_setup|bool and matrix_postgres_enabled|bool"
+  tags:
+    - setup-all
+    - setup-postgres
+
+- import_tasks: "{{ role_path }}/tasks/setup_postgres.yml"
+  when: run_setup|bool
+  tags:
+    - setup-all
+    - setup-postgres
+
+- import_tasks: "{{ role_path }}/tasks/import_postgres.yml"
+  when: run_postgres_import|bool
+  tags:
+    - import-postgres
+
+# The `run_postgres_import_sqlite_db` variable had better be renamed to be consistent,
+# but that's a breaking change which may cause trouble for people.
+- import_tasks: "{{ role_path }}/tasks/import_synapse_sqlite_db.yml"
+  when: run_postgres_import_sqlite_db|bool
+  tags:
+    - import-synapse-sqlite-db
+
+# Perhaps we need a new variable here, instead of `run_postgres_import_sqlite_db`.
+- import_tasks: "{{ role_path }}/tasks/import_generic_sqlite_db.yml"
+  when: run_postgres_import_sqlite_db|bool
+  tags:
+    - import-generic-sqlite-db
+
+- import_tasks: "{{ role_path }}/tasks/upgrade_postgres.yml"
+  when: run_postgres_upgrade|bool
+  tags:
+    - upgrade-postgres
+
+- import_tasks: "{{ role_path }}/tasks/run_vacuum.yml"
+  when: run_postgres_vacuum|bool
+  tags:
+    - run-postgres-vacuum

roles/matrix-postgres/tasks/migrate_postgres_data_directory.yml

@@ -0,0 +1,72 @@
+---
+
+# We used to store Postgres data directly under `/matrix/postgres` (what is now considered `matrix_postgres_base_path`).
+#
+# From now on, we expect to store Postgres data one directory below now (`/matrix/postgres/data` - `matrix_postgres_data_path`).
+# We wish to use the base directory for other purposes (storing environment variable files, etc.).
+# Mixing those with the Postgres data is no good and it leads to Postgres's `initdb` complaining to initialize
+# a database in a non-empty directory.
+#
+# For this reason, we store the Postgres data in `/matrix/postgres/data` and need to relocate any installations
+# which still store it in the parent directory (`/matrix/postgres`).
+
+- name: Check if old Postgres data directory is used
+  stat:
+    path: "{{ matrix_postgres_base_path }}/PG_VERSION"
+  register: result_pg_old_data_dir_stat
+
+- name: Warn if old Postgres data directory detected
+  debug:
+    msg: >
+      Found that you have Postgres data in `{{ matrix_postgres_base_path }}`.
+      From now on, Postgres data is supposed to be stored in `{{ matrix_postgres_data_path }}` instead.
+      We'll stop Postgres and relocate the files there for you.
+  when: "result_pg_old_data_dir_stat.stat.exists"
+
+# We should stop Postgres first, before building a list of files,
+# as to ignore any `postmaster.pid` files, etc.
+- name: Ensure matrix-postgres is stopped
+  service:
+    name: matrix-postgres
+    state: stopped
+    daemon_reload: yes
+  when: "result_pg_old_data_dir_stat.stat.exists"
+
+- name: Find files and directories in old Postgres data path
+  find:
+    paths: "{{ matrix_postgres_base_path }}"
+    file_type: any
+    excludes: ["data"]
+  register: "result_pg_old_data_dir_find"
+  when: "result_pg_old_data_dir_stat.stat.exists"
+
+- name: Ensure new Postgres data path exists
+  file:
+    path: "{{ matrix_postgres_data_path }}"
+    state: directory
+    mode: 0700
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  when: "result_pg_old_data_dir_stat.stat.exists"
+
+- block:
+    - name: Relocate Postgres data files from old directory to new
+      command: "mv {{ item.path }} {{ matrix_postgres_data_path }}/{{ item.path|basename }}"
+      with_items: "{{ result_pg_old_data_dir_find.files }}"
+  when: "result_pg_old_data_dir_stat.stat.exists"
+
+# Intentionally not starting matrix-postgres here.
+# It likely needs to be updated to point to the new directory.
+# In fact, let's even get rid of the outdated service, to ensure no one will start it
+# and have it initialize a new database.
+
+- name: Ensure outdated matrix-postgres.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-postgres.service"
+    state: absent
+  when: "result_pg_old_data_dir_stat.stat.exists"
+
+- name: Ensure systemd reloaded after getting rid of outdated matrix-postgres.service
+  service:
+    daemon_reload: yes
+  when: "result_pg_old_data_dir_stat.stat.exists"

roles/matrix-postgres/tasks/run_vacuum.yml

@@ -0,0 +1,90 @@
+---
+
+# Pre-checks
+
+- name: Fail if Postgres not enabled
+  fail:
+    msg: "Postgres via the matrix-postgres role is not enabled (`matrix_postgres_enabled`). Cannot run vacuum."
+  when: "not matrix_postgres_enabled|bool"
+
+
+# Defaults
+
+- name: Set postgres_start_wait_time, if not provided
+  set_fact:
+    postgres_start_wait_time: 15
+  when: "postgres_start_wait_time|default('') == ''"
+
+- name: Set postgres_vacuum_wait_time, if not provided
+  set_fact:
+    postgres_vacuum_wait_time: "{{ 7 * 86400 }}"
+  when: "postgres_vacuum_wait_time|default('') == ''"
+
+
+# Actual vacuuming work
+
+- name: Ensure matrix-postgres is started
+  service:
+    name: matrix-postgres
+    state: started
+    daemon_reload: yes
+
+- name: Wait a bit, so that Postgres can start
+  wait_for:
+    timeout: "{{ postgres_start_wait_time }}"
+  delegate_to: 127.0.0.1
+  become: false
+
+- import_tasks: tasks/util/detect_existing_postgres_version.yml
+
+- name: Abort, if no existing Postgres version detected
+  fail:
+    msg: "Could not find existing Postgres installation"
+  when: "not matrix_postgres_detected_existing|bool"
+
+- name: Generate Postgres database vacuum command
+  set_fact:
+    matrix_postgres_vacuum_command: >-
+      {{ matrix_host_command_docker }} run --rm --name matrix-postgres-synapse-vacuum
+      --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+      --cap-drop=ALL
+      --network={{ matrix_docker_network }}
+      --env-file={{ matrix_postgres_base_path }}/env-postgres-psql
+      {{ matrix_postgres_docker_image_latest }}
+      psql -v ON_ERROR_STOP=1 -h matrix-postgres {{ matrix_synapse_database_database }} -c 'VACUUM FULL VERBOSE'
+
+- name: Note about Postgres vacuum alternative
+  debug:
+    msg: >-
+      Running vacuum with the following Postgres command: `{{ matrix_postgres_vacuum_command }}`.
+      If this crashes, you can stop all processes (`systemctl stop matrix-*`),
+      start Postgres only (`systemctl start matrix-postgres`)
+      and manually run the above command directly on the server.
+
+- name: Populate service facts
+  service_facts:
+
+- set_fact:
+    matrix_postgres_synapse_was_running: "{{ ansible_facts.services['matrix-synapse.service']|default(none) is not none and ansible_facts.services['matrix-synapse.service'].state == 'running' }}"
+
+- name: Ensure matrix-synapse is stopped
+  service:
+    name: matrix-synapse
+    state: stopped
+    daemon_reload: yes
+
+- name: Run Postgres vacuum command
+  command: "{{ matrix_postgres_vacuum_command }}"
+  async: "{{ postgres_vacuum_wait_time }}"
+  poll: 10
+  register: matrix_postgres_synapse_vacuum_result
+
+# Intentionally show the results
+- debug: var="matrix_postgres_synapse_vacuum_result"
+
+- name: Ensure matrix-synapse is started, if it previously was
+  service:
+    name: matrix-synapse
+    state: started
+    daemon_reload: yes
+  when: "matrix_postgres_synapse_was_running|bool"

roles/matrix-postgres/tasks/setup_postgres.yml

@@ -0,0 +1,197 @@
+---
+
+#
+# Tasks related to setting up an internal postgres server
+#
+
+- import_tasks: "{{ role_path }}/tasks/migrate_postgres_data_directory.yml"
+  when: matrix_postgres_enabled|bool
+
+- import_tasks: "{{ role_path }}/tasks/util/detect_existing_postgres_version.yml"
+  when: matrix_postgres_enabled|bool
+
+# If we have found an existing version (installed from before), we use its corresponding Docker image.
+# If not, we install using the latest Postgres.
+#
+# Upgrading is supposed to be performed separately and explicitly (see `upgrade_postgres.yml`).
+- set_fact:
+    matrix_postgres_docker_image_to_use: "{{ matrix_postgres_docker_image_latest if matrix_postgres_detected_version_corresponding_docker_image == '' else matrix_postgres_detected_version_corresponding_docker_image }}"
+  when: matrix_postgres_enabled|bool
+
+- name: Inject warning if on an old version of Postgres
+  set_fact:
+    matrix_playbook_runtime_results: |
+      {{
+        matrix_playbook_runtime_results|default([])
+        +
+        [
+          "NOTE: Your setup is on an old Postgres version ({{ matrix_postgres_docker_image_to_use }}), while {{ matrix_postgres_docker_image_latest }} is supported. You can upgrade using --tags=upgrade-postgres"
+        ]
+      }}
+  when: "matrix_postgres_enabled|bool and matrix_postgres_docker_image_to_use != matrix_postgres_docker_image_latest"
+
+# Even if we don't run the internal server, we still need this for running the CLI
+- name: Ensure postgres Docker image is pulled
+  docker_image:
+    name: "{{ matrix_postgres_docker_image_to_use }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_postgres_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_postgres_docker_image_force_pull }}"
+  when: matrix_postgres_enabled|bool
+
+- name: Ensure Postgres paths exist
+  file:
+    path: "{{ item }}"
+    state: directory
+    mode: 0700
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - "{{ matrix_postgres_base_path }}"
+    - "{{ matrix_postgres_data_path }}"
+  when: matrix_postgres_enabled|bool
+
+# We do this as a separate task, because:
+# - we'd like to do it for the data path only, not for the base path (which contains root-owned environment variable files we'd like to leave as-is)
+# - we need to do it without `mode`, or we risk making certain `.conf` and other files's executable bit to flip to true
+- name: Ensure Postgres data path ownership is correct
+  file:
+    path: "{{ matrix_postgres_data_path }}"
+    state: directory
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+    recurse: yes
+  when: matrix_postgres_enabled|bool
+
+- name: Ensure Postgres environment variables file created
+  template:
+    src: "{{ role_path }}/templates/{{ item }}.j2"
+    dest: "{{ matrix_postgres_base_path }}/{{ item }}"
+    mode: 0640
+  with_items:
+    - "env-postgres-psql"
+    - "env-postgres-server"
+  when: matrix_postgres_enabled|bool
+
+- name: Ensure matrix-postgres-cli script created
+  template:
+    src: "{{ role_path }}/templates/usr-local-bin/matrix-postgres-cli.j2"
+    dest: "{{ matrix_local_bin_path }}/matrix-postgres-cli"
+    mode: 0755
+  when: matrix_postgres_enabled|bool
+
+- name: Ensure matrix-change-user-admin-status script created
+  template:
+    src: "{{ role_path }}/templates/usr-local-bin/matrix-change-user-admin-status.j2"
+    dest: "{{ matrix_local_bin_path }}/matrix-change-user-admin-status"
+    mode: 0755
+  when: matrix_postgres_enabled|bool
+
+- name: (Migration) Ensure old matrix-make-user-admin script deleted
+  file:
+    path: "{{ matrix_local_bin_path }}/matrix-make-user-admin"
+    state: absent
+  when: matrix_postgres_enabled|bool
+
+- name: Ensure matrix-postgres-update-user-password-hash script created
+  template:
+    src: "{{ role_path }}/templates/usr-local-bin/matrix-postgres-update-user-password-hash.j2"
+    dest: "{{ matrix_local_bin_path }}/matrix-postgres-update-user-password-hash"
+    mode: 0755
+  when: matrix_postgres_enabled|bool
+
+- name: Ensure matrix-postgres.service installed
+  template:
+    src: "{{ role_path }}/templates/systemd/matrix-postgres.service.j2"
+    dest: "{{ matrix_systemd_path }}/matrix-postgres.service"
+    mode: 0644
+  register: matrix_postgres_systemd_service_result
+  when: matrix_postgres_enabled|bool
+
+- name: Ensure systemd reloaded after matrix-postgres.service installation
+  service:
+    daemon_reload: yes
+  when: "matrix_postgres_enabled|bool and matrix_postgres_systemd_service_result.changed"
+
+- include_tasks:
+    file: "{{ role_path }}/tasks/util/create_additional_databases.yml"
+    apply:
+      tags:
+        - always
+  when: "matrix_postgres_enabled|bool and matrix_postgres_additional_databases|length > 0"
+
+- name: Check existence of matrix-postgres backup data path
+  stat:
+    path: "{{ matrix_postgres_data_path }}-auto-upgrade-backup"
+  register: matrix_postgres_data_backup_path_stat
+  when: "matrix_postgres_enabled|bool"
+
+- name: Inject warning if backup data remains
+  set_fact:
+    matrix_playbook_runtime_results: |
+      {{
+        matrix_playbook_runtime_results|default([])
+        +
+        [
+          "NOTE: You have some Postgres backup data in `{{ matrix_postgres_data_path }}-auto-upgrade-backup`, which was created during the last major Postgres update you ran. If your setup works well after this upgrade, feel free to delete this whole directory."
+        ]
+      }}
+  when: "matrix_postgres_enabled|bool and matrix_postgres_data_backup_path_stat.stat.exists"
+
+
+#
+# Tasks related to getting rid of the internal postgres server (if it was previously enabled)
+#
+
+- name: Check existence of matrix-postgres service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-postgres.service"
+  register: matrix_postgres_service_stat
+  when: "not matrix_postgres_enabled|bool"
+
+- name: Ensure matrix-postgres is stopped
+  service:
+    name: matrix-postgres
+    state: stopped
+    daemon_reload: yes
+  when: "not matrix_postgres_enabled|bool and matrix_postgres_service_stat.stat.exists"
+
+- name: Ensure matrix-postgres.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-postgres.service"
+    state: absent
+  when: "not matrix_postgres_enabled|bool and matrix_postgres_service_stat.stat.exists"
+
+- name: Ensure systemd reloaded after matrix-postgres.service removal
+  service:
+    daemon_reload: yes
+  when: "not matrix_postgres_enabled|bool and matrix_postgres_service_stat.stat.exists"
+
+- name: Check existence of matrix-postgres local data path
+  stat:
+    path: "{{ matrix_postgres_data_path }}"
+  register: matrix_postgres_data_path_stat
+  when: "not matrix_postgres_enabled|bool"
+
+# We just want to notify the user. Deleting data is too destructive.
+- name: Inject warning if matrix-postgres local data remains
+  set_fact:
+    matrix_playbook_runtime_results: |
+      {{
+        matrix_playbook_runtime_results|default([])
+        +
+        [
+          "NOTE: You are not using a local PostgreSQL database, but some old data remains from before in `{{ matrix_postgres_data_path }}`. Feel free to delete it."
+        ]
+      }}
+  when: "not matrix_postgres_enabled|bool and matrix_postgres_data_path_stat.stat.exists"
+
+- name: Remove Postgres scripts
+  file:
+    path: "{{ matrix_local_bin_path }}/{{ item }}"
+    state: absent
+  with_items:
+    - matrix-postgres-cli
+    - matrix-change-user-admin-status
+    - matrix-postgres-update-user-password-hash
+  when: "not matrix_postgres_enabled|bool"

roles/matrix-postgres/tasks/upgrade_postgres.yml

@@ -0,0 +1,172 @@
+---
+
+- name: Set default postgres_dump_dir, if not provided
+  set_fact:
+    postgres_dump_dir: "/tmp"
+  when: "postgres_dump_dir|default('') == ''"
+
+- name: Set postgres_dump_name, if not provided
+  set_fact:
+    postgres_dump_name: "matrix-postgres-dump.sql.gz"
+  when: "postgres_dump_name|default('') == ''"
+
+- name: Set postgres_auto_upgrade_backup_data_path, if not provided
+  set_fact:
+    postgres_auto_upgrade_backup_data_path: "{{ matrix_postgres_data_path }}-auto-upgrade-backup"
+  when: "postgres_auto_upgrade_backup_data_path|default('') == ''"
+
+- name: Set postgres_start_wait_time, if not provided
+  set_fact:
+    postgres_start_wait_time: 15
+  when: "postgres_start_wait_time|default('') == ''"
+
+- name: Set postgres_force_upgrade, if not provided
+  set_fact:
+    postgres_force_upgrade: false
+  when: "postgres_force_upgrade|default('') == ''"
+
+- name: Fail, if trying to upgrade external Postgres database
+  fail:
+    msg: "Your configuration indicates that you're not using Postgres from this role. There is nothing to upgrade."
+  when: "not matrix_postgres_enabled|bool"
+
+- name: Check Postgres auto-upgrade backup data directory
+  stat:
+    path: "{{ postgres_auto_upgrade_backup_data_path }}"
+  register: result_auto_upgrade_path
+
+- name: Abort, if existing Postgres auto-upgrade data path detected
+  fail:
+    msg: "Detected that a left-over {{ postgres_auto_upgrade_backup_data_path }} exists. You should rename it to {{ matrix_postgres_data_path }} if the previous upgrade went wrong, or delete it if it went well."
+  when: "result_auto_upgrade_path.stat.exists"
+
+- import_tasks: tasks/util/detect_existing_postgres_version.yml
+
+- name: Abort, if no existing Postgres version detected
+  fail:
+    msg: "Could not find existing Postgres installation"
+  when: "not matrix_postgres_detected_existing|bool"
+
+- name: Abort, if already at latest Postgres version
+  fail:
+    msg: "You are already running the latest Postgres version supported ({{ matrix_postgres_docker_image_latest }}). Nothing to do"
+  when: "matrix_postgres_detected_version_corresponding_docker_image == matrix_postgres_docker_image_latest and not postgres_force_upgrade"
+
+- debug:
+    msg: "Upgrading database from {{ matrix_postgres_detected_version_corresponding_docker_image }} to {{ matrix_postgres_docker_image_latest }}"
+
+- name: Ensure matrix-synapse is stopped
+  service:
+    name: matrix-synapse
+    state: stopped
+
+- name: Ensure matrix-postgres is started
+  service:
+    name: matrix-postgres
+    state: started
+    daemon_reload: yes
+
+- name: Wait a bit, so that Postgres can start
+  wait_for:
+    timeout: "{{ postgres_start_wait_time }}"
+  delegate_to: 127.0.0.1
+  become: false
+
+# We dump all databases, roles, etc.
+#
+# Because we'll be importing into a new container which initializes the default
+# role (`matrix_postgres_connection_username`) and database (`matrix_postgres_db_name`) by itself on startup,
+# we need to remove these from the dump, or we'll get errors saying these already exist.
+- name: Perform Postgres database dump
+  command: >-
+    {{ matrix_host_command_docker }} run --rm --name matrix-postgres-dump
+    --log-driver=none
+    --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+    --network={{ matrix_docker_network }}
+    --env-file={{ matrix_postgres_base_path }}/env-postgres-psql
+    --entrypoint=/bin/sh
+    --mount type=bind,src={{ postgres_dump_dir }},dst=/out
+    {{ matrix_postgres_detected_version_corresponding_docker_image }}
+    -c "pg_dumpall -h matrix-postgres
+    {{ '| gzip -c ' if postgres_dump_name.endswith('.gz') else '' }}
+    > /out/{{ postgres_dump_name }}"
+
+- name: Ensure matrix-postgres is stopped
+  service:
+    name: matrix-postgres
+    state: stopped
+
+- name: Rename existing Postgres data directory
+  command: "mv {{ matrix_postgres_data_path }} {{ postgres_auto_upgrade_backup_data_path }}"
+
+- debug:
+    msg: "NOTE: Your Postgres data directory has been moved from `{{ matrix_postgres_data_path }}` to `{{ postgres_auto_upgrade_backup_data_path }}`. In the event of failure, you can move it back and run the playbook with --tags=setup-postgres to restore operation."
+
+- import_tasks: tasks/setup_postgres.yml
+
+- name: Ensure matrix-postgres autoruns and is restarted
+  service:
+    name: matrix-postgres
+    enabled: yes
+    state: restarted
+    daemon_reload: yes
+
+- name: Wait a bit, so that Postgres can start
+  wait_for:
+    timeout: "{{ postgres_start_wait_time }}"
+  delegate_to: 127.0.0.1
+  become: false
+
+# Starting the database container had automatically created the default
+# role (`matrix_postgres_connection_username`) and database (`matrix_postgres_db_name`).
+# The dump most likely contains those same entries and would try to re-create them, leading to errors.
+# We need to skip over those lines.
+- name: Generate Postgres database import command
+  set_fact:
+    matrix_postgres_import_command: >-
+      {{ matrix_host_command_docker }} run --rm --name matrix-postgres-import
+      --log-driver=none
+      --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+      --cap-drop=ALL
+      --network={{ matrix_docker_network }}
+      --env-file={{ matrix_postgres_base_path }}/env-postgres-psql
+      --entrypoint=/bin/sh
+      --mount type=bind,src={{ postgres_dump_dir }},dst=/in,ro
+      {{ matrix_postgres_docker_image_latest }}
+      -c "cat /in/{{ postgres_dump_name }} |
+      {{ 'gunzip |' if postgres_dump_name.endswith('.gz') else '' }}
+      grep -vE '{{ matrix_postgres_import_roles_ignore_regex }}' |
+      grep -vE '{{ matrix_postgres_import_databases_ignore_regex }}' |
+      psql -v ON_ERROR_STOP=1 -h matrix-postgres"
+
+# This is a hack.
+# See: https://ansibledaily.com/print-to-standard-output-without-escaping/
+#
+# We want to run `debug: msg=".."`, but that dumps it as JSON and escapes double quotes within it,
+# which ruins the command (`matrix_postgres_import_command`)
+- name: Note about Postgres importing
+  set_fact:
+    dummy: true
+  with_items:
+    - >-
+        Importing Postgres database using the following command: `{{ matrix_postgres_import_command }}`.
+        If this crashes, you can stop Postgres (`systemctl stop matrix-postgres`),
+        delete the new database data (`rm -rf {{ matrix_postgres_data_path }}`)
+        and restore the automatically-made backup (`mv {{ postgres_auto_upgrade_backup_data_path }} {{ matrix_postgres_data_path }}`).
+
+- name: Perform Postgres database import
+  command: "{{ matrix_postgres_import_command }}"
+
+- name: Delete Postgres database dump file
+  file:
+    path: "{{ postgres_dump_dir }}/{{ postgres_dump_name }}"
+    state: absent
+
+- name: Ensure matrix-synapse is started
+  service:
+    name: matrix-synapse
+    state: started
+    daemon_reload: yes
+
+- debug:
+    msg: "NOTE: Your old Postgres data directory is preserved at `{{ postgres_auto_upgrade_backup_data_path }}`. You might want to get rid of it once you've confirmed that all is well."

roles/matrix-postgres/tasks/util/create_additional_database.yml

@@ -0,0 +1,40 @@
+---
+
+# It'd be better if this is belonged to `validate_config.yml`, but it would have to be some loop-within-a-loop there,
+# and that's ugly. We also don't expect this to catch errors often. It's more of a defensive last-minute check.
+- name: Fail if additional database data appears invalid
+  fail:
+    msg: "Additional database definition ({{ additional_db }} lacks a required key: {{ item }}"
+  when: "item not in additional_db"
+  with_items: "{{ ['name', 'username', 'password'] }}"
+
+# The SQL statements that we'll run against Postgres are stored in a file that others can't read.
+# This file will be mounted into the container and fed to Postgres.
+# This way, we avoid passing sensitive data around in CLI commands that other users on the system can see.
+- name: Create additional database initialization SQL file for {{ additional_db.name }}
+  template:
+    src: "{{ role_path }}/templates/sql/init-additional-db-user-and-role.sql.j2"
+    dest: "/tmp/matrix-postgres-init-additional-db-user-and-role.sql"
+    mode: 0600
+    owner: "{{ matrix_user_uid }}"
+    group: "{{ matrix_user_gid }}"
+
+- name: Execute Postgres additional database initialization SQL file for {{ additional_db.name }}
+  command:
+    cmd: >-
+      {{ matrix_host_command_docker }} run
+      --rm
+      --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+      --cap-drop=ALL
+      --env-file={{ matrix_postgres_base_path }}/env-postgres-psql
+      --network {{ matrix_docker_network }}
+      --mount type=bind,src=/tmp/matrix-postgres-init-additional-db-user-and-role.sql,dst=/matrix-postgres-init-additional-db-user-and-role.sql,ro
+      --entrypoint=/bin/sh
+      {{ matrix_postgres_docker_image_to_use }}
+      -c
+      'psql -h {{ matrix_postgres_connection_hostname }} --file=/matrix-postgres-init-additional-db-user-and-role.sql'
+
+- name: Delete additional database initialization SQL file for {{ additional_db.name }}
+  file:
+    path: /tmp/matrix-postgres-init-additional-db-user-and-role.sql
+    state: absent

roles/matrix-postgres/tasks/util/create_additional_databases.yml

@@ -0,0 +1,23 @@
+---
+
+- name: Ensure matrix-postgres is started
+  service:
+    name: matrix-postgres
+    state: started
+    daemon_reload: yes
+  register: matrix_postgres_service_start_result
+
+- name: Wait a bit, so that Postgres can start
+  wait_for:
+    timeout: "{{ matrix_postgres_additional_databases_postgres_start_wait_timeout_seconds }}"
+  delegate_to: 127.0.0.1
+  become: false
+  when: "matrix_postgres_service_start_result.changed|bool"
+
+- name: Create additional Postgres user and database
+  include_tasks: "{{ role_path }}/tasks/util/create_additional_database.yml"
+  with_items: "{{ matrix_postgres_additional_databases }}"
+  loop_control:
+    loop_var: additional_db
+  # Suppress logging to avoid dumping the credentials to the shell
+  no_log: true

roles/matrix-postgres/tasks/util/detect_existing_postgres_version.yml

@@ -0,0 +1,56 @@
+---
+
+# This utility aims to determine if there is some existing Postgres version in use or not.
+# If there is, it also tries to detect the Docker image that corresponds to that version.
+
+- name: Initialize Postgres version determination variables (default to empty)
+  set_fact:
+    matrix_postgres_detection_pg_version_path: "{{ matrix_postgres_data_path }}/PG_VERSION"
+    matrix_postgres_detected_existing: false
+    matrix_postgres_detected_version: ""
+    matrix_postgres_detected_version_corresponding_docker_image: ""
+
+- name: Determine existing Postgres version (check PG_VERSION file)
+  stat:
+    path: "{{ matrix_postgres_detection_pg_version_path }}"
+  register: result_pg_version_stat
+
+- set_fact:
+    matrix_postgres_detected_existing: true
+  when: "result_pg_version_stat.stat.exists"
+
+- name: Determine existing Postgres version (read PG_VERSION file)
+  slurp:
+    src: "{{ matrix_postgres_detection_pg_version_path }}"
+  register: result_pg_version
+  when: matrix_postgres_detected_existing|bool
+
+- name: Determine existing Postgres version (make sense of PG_VERSION file)
+  set_fact:
+    matrix_postgres_detected_version: "{{ result_pg_version['content']|b64decode|replace('\n', '') }}"
+  when: matrix_postgres_detected_existing|bool
+
+- name: Determine corresponding Docker image to detected version (assume default of latest)
+  set_fact:
+    matrix_postgres_detected_version_corresponding_docker_image: "{{ matrix_postgres_docker_image_latest }}"
+  when: "matrix_postgres_detected_version != ''"
+
+- name: Determine corresponding Docker image to detected version (use 9.x, if detected)
+  set_fact:
+    matrix_postgres_detected_version_corresponding_docker_image: "{{ matrix_postgres_docker_image_v9 }}"
+  when: "matrix_postgres_detected_version.startswith('9.')"
+
+- name: Determine corresponding Docker image to detected version (use 10.x, if detected)
+  set_fact:
+    matrix_postgres_detected_version_corresponding_docker_image: "{{ matrix_postgres_docker_image_v10 }}"
+  when: "matrix_postgres_detected_version == '10' or matrix_postgres_detected_version.startswith('10.')"
+
+- name: Determine corresponding Docker image to detected version (use 11.x, if detected)
+  set_fact:
+    matrix_postgres_detected_version_corresponding_docker_image: "{{ matrix_postgres_docker_image_v11 }}"
+  when: "matrix_postgres_detected_version == '11' or matrix_postgres_detected_version.startswith('11.')"
+
+- name: Determine corresponding Docker image to detected version (use 12.x, if detected)
+  set_fact:
+    matrix_postgres_detected_version_corresponding_docker_image: "{{ matrix_postgres_docker_image_v12 }}"
+  when: "matrix_postgres_detected_version == '12' or matrix_postgres_detected_version.startswith('12.')"

roles/matrix-postgres/tasks/util/migrate_db_to_postgres.yml

@@ -0,0 +1,169 @@
+---
+
+- name: Fail if Postgres not enabled
+  fail:
+    msg: "Postgres via the matrix-postgres role is not enabled (`matrix_postgres_enabled`). Cannot migrate."
+  when: "not matrix_postgres_enabled|bool"
+
+- name: Fail if util called incorrectly (missing matrix_postgres_db_migration_request)
+  fail:
+    msg: "The `matrix_postgres_db_migration_request` variable needs to be provided to this util."
+  when: "matrix_postgres_db_migration_request is not defined"
+
+- name: Fail if util called incorrectly (invalid matrix_postgres_db_migration_request)
+  fail:
+    msg: "The `matrix_postgres_db_migration_request` variable needs to contain `{{ item }}`."
+  with_items:
+    - src
+    - dst
+    - caller
+    - engine_variable_name
+    - systemd_services_to_stop
+  when: "item not in matrix_postgres_db_migration_request"
+
+- name: Check if the provided source database file exists
+  stat:
+    path: "{{ matrix_postgres_db_migration_request.src }}"
+  register: matrix_postgres_db_migration_request_src_stat_result
+
+- name: Fail if provided source database file doesn't exist
+  fail:
+    msg: "File cannot be found on the server at {{ matrix_postgres_db_migration_request.src }}"
+  when: "not matrix_postgres_db_migration_request_src_stat_result.stat.exists"
+
+- block:
+    - name: Ensure pgloader repository is present on self-build
+      git:
+        repo: "{{ matrix_postgres_pgloader_container_image_self_build_repo }}"
+        dest: "{{ matrix_postgres_pgloader_container_image_self_build_src_path }}"
+        version: "{{ matrix_postgres_pgloader_container_image_self_build_repo_branch }}"
+        force: "yes"
+      register: matrix_postgres_pgloader_git_pull_results
+
+    # If `stable` is used, we hit an error when processing /opt/src/pgloader/build/quicklisp/dists/quicklisp/software/uax-15-20201220-git/data/CompositionExclusions.txt:
+    # > the octet sequence #(194) cannot be decoded
+    #
+    # The issue is described here and is not getting fixed for months: https://github.com/dimitri/pgloader/pull/1179
+    #
+    # Although we're not using the dimitri/pgloader image, the one we're using suffers from the same problem.
+    - name: Switch pgloader base image from Debian stable (likely 10.x/Buster) to Bullseye
+      lineinfile:
+        path: "{{ matrix_postgres_pgloader_container_image_self_build_src_path }}/Dockerfile"
+        regexp: "{{ item.match }}"
+        line: "{{ item.replace }}"
+      with_items:
+        - match: '^FROM debian:stable-slim as builder$'
+          replace: 'FROM debian:bullseye-slim as builder'
+        - match: '^FROM debian:stable-slim$'
+          replace: 'FROM debian:bullseye-slim'
+
+    - name: Ensure pgloader Docker image is built
+      docker_image:
+        name: "{{ matrix_postgres_pgloader_docker_image }}"
+        source: build
+        force_source: "{{ matrix_postgres_pgloader_git_pull_results.changed if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+        force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_postgres_pgloader_git_pull_results.changed }}"
+        build:
+          dockerfile: Dockerfile
+          path: "{{ matrix_postgres_pgloader_container_image_self_build_src_path }}"
+          pull: yes
+  when: "matrix_postgres_pgloader_container_image_self_build|bool"
+
+- name: Ensure pgloader Docker image is pulled
+  docker_image:
+    name: "{{ matrix_postgres_pgloader_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_postgres_pgloader_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_postgres_pgloader_docker_image_force_pull }}"
+  when: "not matrix_postgres_pgloader_container_image_self_build"
+
+# Defaults
+
+- name: Set postgres_start_wait_time, if not provided
+  set_fact:
+    postgres_start_wait_time: 15
+  when: "postgres_start_wait_time|default('') == ''"
+
+# Actual import work
+
+# matrix-postgres is most likely started already
+- name: Ensure matrix-postgres is started
+  service:
+    name: matrix-postgres
+    state: started
+    daemon_reload: yes
+  register: matrix_postgres_service_start_result
+
+- name: Wait a bit, so that Postgres can start
+  wait_for:
+    timeout: "{{ postgres_start_wait_time }}"
+  delegate_to: 127.0.0.1
+  become: false
+  when: "matrix_postgres_service_start_result.changed|bool"
+
+# We only stop services here, leaving it to the caller to start them later.
+#
+# We can't start them, because they probably need to be reconfigured too (changing the configuration from using SQLite to Postgres, etc.),
+# before starting.
+#
+# Since the caller will be starting them, it might make sense to leave stopping to it as well.
+# However, we don't do it, because it's simpler having it here, and it also gets to happen only if we'll be doing an import.
+# If we bailed out (somewhere above), nothing would have gotten stopped. It's nice to leave this running in such cases.
+- name: Ensure systemd services blocking the database import are stopped
+  service:
+    name: "{{ item }}"
+    state: stopped
+  failed_when: false
+  with_items: "{{ matrix_postgres_db_migration_request.systemd_services_to_stop }}"
+
+- name: Import {{ matrix_postgres_db_migration_request.engine_old }} database from {{ matrix_postgres_db_migration_request.src }} into Postgres
+  command:
+    cmd: >-
+      {{ matrix_host_command_docker }} run
+      --rm
+      --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+      --cap-drop=ALL
+      --network={{ matrix_docker_network }}
+      --mount type=bind,src={{ matrix_postgres_db_migration_request.src }},dst=/in.db,ro
+      --entrypoint=/bin/sh
+      {{ matrix_postgres_pgloader_docker_image }}
+      -c
+      'pgloader {{ matrix_postgres_db_migration_request.pgloader_options|default([])|join(' ') }} /in.db {{ matrix_postgres_db_migration_request.dst }}'
+
+- block:
+    # We can't use `{{ role_path }}` here, neither with `import_tasks`, nor with `include_tasks`,
+    # because it refers to the role that included this util, and not to the role this file belongs to.
+    - import_tasks: "{{ role_path }}/../matrix-postgres/tasks/util/detect_existing_postgres_version.yml"
+
+    - set_fact:
+        matrix_postgres_docker_image_to_use: "{{ matrix_postgres_docker_image_latest if matrix_postgres_detected_version_corresponding_docker_image == '' else matrix_postgres_detected_version_corresponding_docker_image }}"
+
+    - name: Execute additional Postgres SQL migration statements
+      command:
+        cmd: >-
+          {{ matrix_host_command_docker }} run
+          --rm
+          --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+          --cap-drop=ALL
+          --env-file={{ matrix_postgres_base_path }}/env-postgres-psql
+          --network={{ matrix_docker_network }}
+          {{ matrix_postgres_docker_image_to_use }}
+          psql --host=matrix-postgres --dbname={{ matrix_postgres_db_migration_request.additional_psql_statements_db_name }} --command='{{ item }}'
+      with_items: "{{ matrix_postgres_db_migration_request.additional_psql_statements_list }}"
+
+  when: "matrix_postgres_db_migration_request.additional_psql_statements_list|default([])|length > 0"
+
+- name: Archive {{ matrix_postgres_db_migration_request.engine_old }} database ({{ matrix_postgres_db_migration_request.src }} -> {{ matrix_postgres_db_migration_request.src }}.backup)
+  command:
+    cmd: "mv {{ matrix_postgres_db_migration_request.src }} {{ matrix_postgres_db_migration_request.src }}.backup"
+
+- name: Inject result
+  set_fact:
+    matrix_playbook_runtime_results: |
+      {{
+        matrix_playbook_runtime_results|default([])
+        +
+        [
+          "NOTE: Your {{ matrix_postgres_db_migration_request.engine_old }} database file has been imported into Postgres. The original database file has been moved from `{{ matrix_postgres_db_migration_request.src }}` to `{{ matrix_postgres_db_migration_request.src }}.backup`. When you've confirmed that the import went well and everything works, you should be able to safely delete this file."
+        ]
+      }}

roles/matrix-postgres/tasks/validate_config.yml

@@ -0,0 +1,39 @@
+---
+
+- name: (Deprecation) Warn about matrix_postgres_use_external usage
+  fail:
+    msg: >
+      The `matrix_postgres_use_external` variable defined in your configuration is not used by this playbook anymore!
+      You'll need to adapt to the new way of using an external Postgres server.
+      It's a combination of `matrix_postgres_enabled: false` and specifying Postgres connection
+      details in a few `matrix_postgres_connection_` variables.
+      See the "Using an external PostgreSQL server (optional)" documentation page.
+  when: "'matrix_postgres_use_external' in vars"
+
+# This is separate (from the other required variables below),
+# because we'd like to have a friendlier message for our existing users.
+- name: Fail if matrix_postgres_connection_password not defined
+  fail:
+    msg: >-
+      The playbook no longer has a default Postgres password defined in the `matrix_postgres_connection_password` variable, among lots of other Postgres changes.
+      You need to perform multiple manual steps to resolve this.
+      See our changelog for more details:
+      https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md#breaking-change-postgres-changes-that-require-manual-intervention
+  when: "matrix_postgres_connection_password == ''"
+
+- name: Fail if required Postgres settings not defined
+  fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item }}`).
+  when: "vars[item] == ''"
+  with_items:
+    - "matrix_postgres_connection_hostname"
+    - "matrix_postgres_connection_port"
+    - "matrix_postgres_connection_username"
+    - "matrix_postgres_connection_password"
+    - "matrix_postgres_db_name"
+
+- name: Fail if Postgres password length exceeded
+  fail:
+    msg: "The maximum `matrix_postgres_connection_password` length is 99 characters"
+  when: "matrix_postgres_connection_password|length > 99"

roles/matrix-postgres/templates/env-postgres-psql.j2

@@ -0,0 +1,4 @@
+#jinja2: lstrip_blocks: "True"
+PGUSER={{ matrix_postgres_connection_username }}
+PGPASSWORD={{ matrix_postgres_connection_password }}
+PGDATABASE={{ matrix_postgres_db_name }}

roles/matrix-postgres/templates/env-postgres-server.j2

@@ -0,0 +1,7 @@
+#jinja2: lstrip_blocks: "True"
+POSTGRES_USER={{ matrix_postgres_connection_username }}
+POSTGRES_PASSWORD={{ matrix_postgres_connection_password }}
+POSTGRES_DB={{ matrix_postgres_db_name }}
+# Synapse refuses to run if collation is not C.
+# See https://github.com/matrix-org/synapse/issues/6722
+POSTGRES_INITDB_ARGS=--lc-collate C --lc-ctype C --encoding UTF8

roles/matrix-postgres/templates/sql/init-additional-db-user-and-role.sql.j2

@@ -0,0 +1,19 @@
+-- `CREATE USER` does not support `IF NOT EXISTS`, so we use this workaround to prevent an error and raise a notice instead.
+-- Seen here: https://stackoverflow.com/a/49858797
+DO $$
+BEGIN
+  CREATE USER "{{ additional_db.username }}";
+  EXCEPTION WHEN DUPLICATE_OBJECT THEN
+  RAISE NOTICE 'not creating user "{{ additional_db.username }}", since it already exists';
+END
+$$;
+
+-- This is useful for initial user creation (since we don't assign a password above) and for handling subsequent password changes
+-- TODO - we should escape quotes in the password.
+ALTER ROLE "{{ additional_db.username }}" PASSWORD '{{ additional_db.password }}';
+
+-- This will generate an error on subsequent execution
+CREATE DATABASE "{{ additional_db.name }}" WITH LC_CTYPE 'C' LC_COLLATE 'C' OWNER "{{ additional_db.username }}";
+
+-- This is useful for changing the database owner subsequently
+ALTER DATABASE "{{ additional_db.name }}" OWNER TO "{{ additional_db.username }}";

roles/matrix-postgres/templates/systemd/matrix-postgres.service.j2

@@ -0,0 +1,41 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=Matrix Postgres server
+After=docker.service
+Requires=docker.service
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-postgres 2>/dev/null'
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-postgres 2>/dev/null'
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-postgres \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--read-only \
+			--tmpfs=/tmp:rw,noexec,nosuid,size=100m \
+			--tmpfs=/run/postgresql:rw,noexec,nosuid,size=100m \
+			--network={{ matrix_docker_network }} \
+			{% if matrix_postgres_container_postgres_bind_port %}
+			-p {{ matrix_postgres_container_postgres_bind_port }}:5432 \
+			{% endif %}
+			--env-file={{ matrix_postgres_base_path }}/env-postgres-server \
+			--mount type=bind,src={{ matrix_postgres_data_path }},dst=/var/lib/postgresql/data \
+			--mount type=bind,src=/etc/passwd,dst=/etc/passwd,ro \
+			{% for arg in matrix_postgres_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_postgres_docker_image_to_use }} \
+			postgres {{ matrix_postgres_process_extra_arguments|join(' ') }}
+
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-postgres 2>/dev/null'
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-postgres 2>/dev/null'
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-postgres
+
+[Install]
+WantedBy=multi-user.target

roles/matrix-postgres/templates/usr-local-bin/matrix-change-user-admin-status.j2

@@ -0,0 +1,19 @@
+#jinja2: lstrip_blocks: "True"
+#!/bin/bash
+
+if [ $# -ne 2 ]; then
+	echo "Usage: "$0" <username> <0/1>"
+	echo "Usage: 0 = non-admin"
+	echo "Usage: 1 = admin"
+	exit 1
+fi
+
+docker run \
+	-it \
+	--rm \
+	--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+	--cap-drop=ALL \
+	--env-file={{ matrix_postgres_base_path }}/env-postgres-psql \
+	--network {{ matrix_docker_network }} \
+	{{ matrix_postgres_docker_image_to_use }} \
+	psql -h {{ matrix_postgres_connection_hostname }} --dbname={{ matrix_synapse_database_database }} -c "UPDATE users set admin=$2 WHERE name like '@$1:{{ matrix_domain }}'"

roles/matrix-postgres/templates/usr-local-bin/matrix-postgres-cli.j2

@@ -0,0 +1,13 @@
+#jinja2: lstrip_blocks: "True"
+#!/bin/bash
+
+docker run \
+	-it \
+	--rm \
+	--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+	--cap-drop=ALL \
+	--env-file={{ matrix_postgres_base_path }}/env-postgres-psql \
+	--network {{ matrix_docker_network }} \
+	{{ matrix_postgres_docker_image_to_use }} \
+	psql -h {{ matrix_postgres_connection_hostname }} \
+	"$@"

roles/matrix-postgres/templates/usr-local-bin/matrix-postgres-update-user-password-hash.j2

@@ -0,0 +1,16 @@
+#jinja2: lstrip_blocks: "True"
+#!/bin/bash
+
+if [ $# -ne 2 ]; then
+	echo "Usage: "$0" <username> <password_hash>"
+	exit 1
+fi
+
+docker run \
+	--rm \
+	--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+	--cap-drop=ALL \
+	--env-file={{ matrix_postgres_base_path }}/env-postgres-psql \
+	--network {{ matrix_docker_network }} \
+	{{ matrix_postgres_docker_image_to_use }} \
+	psql -h {{ matrix_postgres_connection_hostname }} --dbname={{ matrix_synapse_database_database }} -c "UPDATE users set password_hash='$2' WHERE name = '@$1:{{ matrix_domain }}'"