postgres: add support for restoring backups

Only the "custom" format of pg_restore is supported, and the backup file
must be located on the host where the ansible playbook is executed.

The intended use cases are:

* Migrating to new PostgreSQL/Ubuntu versions in production (the former
  notoriously requires downtime and either restoring a database backup,
  or running the migration tool to update the storage format offline).
* Testing of database backups that we create today.

.github/workflows/ci.yaml

@@ -60,6 +60,14 @@ jobs:
           popd
 
   ansible:
+    strategy:
+      matrix:
+        db_backup:
+          # Clean install
+          - ''
+          # Restore a database backup
+          - 'testdata/xsnippet-api_20241003-030004.pgc'
+
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -96,8 +104,28 @@ jobs:
 
       - name: Run the playbook
         run: |
+          read -r -d '' extra_vars << 'EOF' || true
+          {
+            "volume_device": "${{ steps.volume-device.outputs.uri }}",
+            "postgres_users": [
+              {
+                "database": "{{ xsnippet_api_user }}",
+                "username": "{{ xsnippet_api_user }}",
+                "backup_schedule": "*-*-* 3:00:00",
+                "backup_restore": "${{ matrix.db_backup }}"
+              }
+            ]
+          }
+          EOF
+
           ansible-playbook \
             -vvv \
-            -e volume_device="${{ steps.volume-device.outputs.uri }}" \
+            -e "${extra_vars}" \
             --inventory inventories/ci \
             site.yml
+
+      - name: Verify that the database backup has been restored correctly
+        if: matrix.db_backup != ''
+        run: |
+          # Expect at least one full page of results
+          test "$(curl http://127.0.0.1:8080/v1/snippets | jq length)" == "20"

roles/postgres/meta/main.yml

@@ -28,6 +28,11 @@ argument_specs:
             description: |
               The time of when database backups should be triggered. Uses the systemd calendar event expression syntax (see man 7 systemd.time).
               If not set, backups will not be created.
+          backup_restore:
+            type: str
+            required: false
+            description: |
+              Path to a database backup to be restored.
         default: []
         description: |
           The list of database/username pairs to create.

roles/postgres/tasks/main.yml

@@ -57,6 +57,12 @@
   become: true
   become_user: postgres
 
+- name: Restore database backups if necessary
+  ansible.builtin.include_tasks:
+    file: restore.yml
+  with_items: "{{ postgres_users }}"
+  when: item.backup_restore is defined and item.backup_restore
+
 - name: Install the script for backup rotation
   ansible.builtin.copy:
     src: 'rotate.py'

roles/postgres/tasks/restore.yml

@@ -0,0 +1,33 @@
+- name: Restore database backups if necessary
+  block:
+    - name: Check if we need to restore a database backup
+      community.postgresql.postgresql_query:
+        db: "{{ item.database }}"
+        query: "SELECT * FROM pg_catalog.pg_tables WHERE tableowner = %s"
+        positional_args:
+          - "{{ item.username }}"
+      register: existing_tables
+
+    - name: Copy and restore a database backup
+      when: existing_tables.rowcount == 0
+      block:
+        - name: Create a temporary backup directory
+          ansible.builtin.tempfile:
+            state: directory
+            suffix: backup
+          register: backup_tmp_dir
+
+        - name: Copy the database backup
+          ansible.builtin.copy:
+            src: "{{ item.backup_restore }}"
+            dest: "{{ [backup_tmp_dir.path, item.backup_restore | basename] | path_join }}"
+            mode: 'u=rw,g=r,o='
+
+        - name: Restore the database backup
+          community.postgresql.postgresql_db:
+            name: "{{ item.database }}"
+            state: "restore"
+            target: "{{ [backup_tmp_dir.path, item.backup_restore | basename] | path_join }}"
+            target_opts: "--single-transaction --exit-on-error"
+  become: true
+  become_user: postgres