improved comments

pg_backup.sh

@@ -1,18 +1,6 @@
 #!/bin/bash
 
-# Postgres backup/restore hook for the discourse `db` service. Invoked by backupbot-two via:
-#   backupbot.backup.pre-hook                     = "/pg_backup.sh backup"
-#   backupbot.backup.volumes.postgresql_data.path = "backup.sql"
-#   backupbot.restore.post-hook                   = "/pg_backup.sh restore"
-# Backup dumps the DB to backup.sql (gzip) inside the postgresql_data volume; backupbot archives it.
-# Restore reimports it. Discourse (the rails app + sidekiq) keeps many TCP connections open to the DB
-# and reconnects within milliseconds, so a one-shot pg_terminate_backend is NOT enough: restore must
-# first block all non-local connections at the pg_hba level (so the app cannot reconnect and interfere
-# mid-reimport), then FORCE-drop, recreate, and deterministically reimport the dump, then restore
-# pg_hba. (Mirrors the proven matrix-synapse restore hook.) The previous recipe shipped a pg_dump
-# backup but NO restore hook — a file-level restore did not reload into the running postgres, so a
-# restored backup silently kept the live (un-restored) state. cc-ci caught this: a seeded ci_marker row
-# was gone after restore. Same pattern as the immich / mattermost-lts / ghost recipe-PRs.
+# Postgres backup/restore hook for the discourse `db` service.
 
 set -e
 
@@ -29,8 +17,7 @@ function restore {
   cd /var/lib/postgresql/data/
 
   # Block all non-local connections so the running discourse app + sidekiq cannot reconnect and
-  # interfere with the drop/recreate/reimport (a one-shot pg_terminate_backend is not enough — the
-  # app reconnects within ms over TCP). Restored on exit.
+  # interfere with the drop/recreate/reimport. Restored on exit.
   restore_hba() {
     cat pg_hba.conf.bak > pg_hba.conf
     rm -f pg_hba.conf.bak
@@ -41,11 +28,16 @@ function restore {
   su postgres -c 'pg_ctl reload'
   trap restore_hba EXIT INT TERM
 
-  # Terminate lingering local sessions, then FORCE-drop + recreate + deterministic reimport.
+  # terminate any lingering local sessions before recreate
+  # see https://stackoverflow.com/questions/5108876/kill-a-postgresql-session-connection
   psql -U "$DB_USER" -d postgres -c \
     "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname='${DB_NAME}' AND pid<>pg_backend_pid();"
+
+  # drop database and then recreate it
   psql -U "$DB_USER" -d postgres -c "DROP DATABASE ${DB_NAME} WITH (FORCE);"
   createdb -U "$DB_USER" "$DB_NAME"
+
+  # reimport data 
   gunzip -c "$BACKUP_FILE" | psql -U "$DB_USER" -d "$DB_NAME" -1 -v ON_ERROR_STOP=1 -f -
 }