PgBouncer - going direct to master

doc/administration/postgresql/pgbouncer.md

@@ -148,6 +148,35 @@ ote_pid | tls
 (1 row)
 ```
 
+## Procedure for bypassing PgBouncer
+
+Some database changes have to be done directly, and not through PgBouncer. This includes database restores and GitLab upgrades (because of the database migrations).
+
+1. To find the primary node, run the following on a database node:
+
+   ```shell
+   sudo gitlab-ctl repmgr cluster show
+   ```
+
+1. Edit `/etc/gitlab/gitlab.rb` on the application node you're performing the task on, and update
+   `gitlab_rails['db_host']` and `gitlab_rails['db_port']` with the database
+   primary's host and port.
+
+1. Run reconfigure:
+
+   ```shell
+   sudo gitlab-ctl reconfigure
+   ```
+
+Once you've performed the tasks or procedure, switch back to using PgBouncer:
+
+1. Change back `/etc/gitlab/gitlab.rb` to point to PgBouncer.
+1. Run reconfigure:
+
+   ```shell
+   sudo gitlab-ctl reconfigure
+   ```
+
 ## Troubleshooting
 
 In case you are experiencing any issues connecting through PgBouncer, the first

doc/raketasks/backup_restore.md

@@ -939,12 +939,10 @@ installed version of GitLab, the restore command aborts with an error
 message. Install the [correct GitLab version](https://packages.gitlab.com/gitlab/),
 and then try again.
 
-There is a [known issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3470)
-for restore not working with `pgbouncer`. To work around the issue, the Rails
-node must bypass `pgbouncer` and connect directly to the primary
-database node. You can do this by setting `gitlab_rails['db_host']` and
-`gitlab_rails['port']` to connect to the primary database node and
-[reconfiguring GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure).
+NOTE: **Note:**
+There is a known issue with restore not working with `pgbouncer`. The [workaround is to bypass
+`pgbouncer` and connect directly to the primary database node](../administration/postgresql/pgbouncer.md#procedure-for-bypassing-pgbouncer).
+[Read more about backup and restore with `pgbouncer`](#backup-and-restore-for-installations-using-pgbouncer).
 
 ### Restore for Docker image and GitLab Helm chart installations
 
@@ -1039,6 +1037,29 @@ VM snapshots of the entire GitLab server. It's not uncommon however for a VM
 snapshot to require you to power down the server, which limits this solution's
 practical use.
 
+## Backup and restore for installations using PgBouncer
+
+PgBouncer can cause the following errors when performing backups and restores:
+
+```ruby
+ActiveRecord::StatementInvalid: PG::UndefinedTable
+```
+
+There is a [known issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3470) for restore not working
+with `pgbouncer`.
+
+To workaround this issue, the GitLab server will need to bypass `pgbouncer` and
+[connect directly to the primary database node](../administration/postgresql/pgbouncer.md#procedure-for-bypassing-pgbouncer)
+to perform the database restore.
+
+There is also a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/23211)
+with PostgreSQL 9 and running a database backup through PgBouncer that can cause
+an outage to GitLab. If you're still on PostgreSQL 9 and upgrading PostgreSQL isn't
+an option, workarounds include having a dedicated application node just for backups,
+configured to connect directly the primary database node as noted above. You're
+advised to upgrade your PostgreSQL version though, GitLab 11.11 shipped with PostgreSQL
+10.7, and that is the recommended version for GitLab 12+.
+
 ## Additional notes
 
 This documentation is for GitLab Community and Enterprise Edition. We back up