From f3eb798b69bab68ab00e0224bfd2bfe2ab03b88b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@debian.org>
Date: Tue, 24 Aug 2021 15:01:04 -0400
Subject: [PATCH] note how to connect to psql
---
howto/gitlab.md | 31 ++++++++++++++++++++++++++++++-
1 file changed, 30 insertions(+), 1 deletion(-)
diff --git a/howto/gitlab.md b/howto/gitlab.md
index 9678b4d3..2e7c2a48 100644
--- a/howto/gitlab.md
+++ b/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):
--
GitLab