note how to connect to psql

howto/gitlab.md

@@ -535,6 +535,27 @@ If your repository relies on Transifex for translations, make sure to
 update the Transifex config to pull from the new branch. To do so,
 [open a l10n ticket](https://gitlab.torproject.org/tpo/community/l10n/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=) with the new branch name changes.
 
+## Connect to the PostgreSQL server
+
+The GitLab Omnibus setup is special: it ships its own embedded
+PostgreSQL server (!), which means the regular `sudo -u postgres psql`
+command doesn't work.
+
+To get access to the PostgreSQL server, you need to [follow the
+upstream instructions](https://docs.gitlab.com/omnibus/maintenance/#starting-a-postgresql-superuser-psql-session) which are, at the time of writing:
+
+    sudo gitlab-psql -d gitlabhq_production
+
+This actually expands to the following command:
+
+    sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -p 5432 -h /var/opt/gitlab/postgresql -d gitlabhq_production -d gitlabhq_production
+
+An emergency dump, therefore, could be taken with:
+
+    cd /tmp ; sudo -u gitlab-psql /opt/gitlab/embedded/bin/pg_dump -p 5432 -h /var/opt/gitlab/postgresql -d gitlabhq_production -d gitlabhq_production | pv -s 2G > /srv/gitlab-backup/db/db-$(date '+%Y-%m-%d').sql
+
+Yes, that is silly. See also [issue 20][].
+
 ## Pager playbook
 
 <!-- information about common errors from the monitoring system and -->
@@ -579,6 +600,12 @@ we bumped it to 1024MB at the time of writing. Note that GitLab CI/CD
 also have a similar setting which might (or might not?) affect such
 problems.
 
+### PostgreSQL debugging
+
+The PostgreSQL configuration in GitLab is [particular][issue 20]. See the
+[connect to the PostgreSQL server](#connect-to-the-postgresql-server) section above on how to connect
+to it.
+
 ## Disaster recovery
 
 In case the entire GitLab machine is destroyed, a new server should be
@@ -642,12 +669,14 @@ elements which configure:
  * `profile::gitlab::mail`: dovecot and postfix configuration, for
    email replies
  * `profile::gitlab::database`: postgresql configuration, possibly not
-   used by the Omnibus package, see [issue 20](https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/20)
+   used by the Omnibus package, see [issue 20][]
  * `profile::gitlab::app`: the core of the configuration of gitlab
    itself, uses the [puppet/gitlab](https://forge.puppet.com/puppet/gitlab) module from the Forge, with
    Prometheus, Grafana, and Nginx support disabled, but Redis,
    PostgreSQL, and Prometheus exporters enabled
 
+[issue 20]: https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/20
+
 This installs the [GitLab Omnibus](https://docs.gitlab.com/omnibus/) distribution which duplicates a
 lot of resources we would otherwise manage elsewhere in Puppet,
 including (but possibly not limited to):