Help us learn about your current experience with the documentation. Take the survey.

PostgreSQL

层级：免费、高级、旗舰
产品：GitLab 自管理版

本页面包含 GitLab 支持团队在故障排除时使用的 PostgreSQL 相关信息。GitLab 将这些信息公开，以便任何人都可以利用支持团队积累的知识。

此处记录的某些程序可能会破坏您的 GitLab 实例。使用风险自负。

如果您使用的是付费层级且不确定如何使用这些命令，请联系支持团队以获取您遇到问题的帮助。

启动数据库控制台

推荐用于：

单节点实例。
扩展或混合环境，在 Patroni 节点上，通常是主节点。
扩展或混合环境，在运行 PostgreSQL 服务的服务器上。

sudo gitlab-psql

在单节点实例或 Web 或 Sidekiq 节点上，您也可以使用 Rails 数据库控制台，但初始化时间较长：

sudo gitlab-rails dbconsole --database main

docker exec -it <container-id> gitlab-psql

使用您的 PostgreSQL 安装中的 psql 命令。

sudo -u git -H psql -d gitlabhq_production

如果您运行混合环境，且 PostgreSQL 在 Linux 软件包安装 (Omnibus) 上运行，推荐的方法是在这些服务器上本地使用数据库控制台。请参考 Linux 软件包的详细信息。
使用外部第三方 PostgreSQL 服务中的控制台。
在 toolbox pod 中运行 gitlab-rails db-console。
- 有关详细信息，请参阅我们的 Kubernetes 速查表。

要退出控制台，请输入：quit。

其他 GitLab PostgreSQL 文档

本部分包含 GitLab 文档中其他信息的链接。

程序

Linux 软件包安装的数据库程序，包括：
- SSL：启用、禁用和验证。
- 启用预写日志 (WAL) 归档。
- 使用外部（非 Omnibus）PostgreSQL 安装；以及备份。
- 在 TCP/IP 上监听，替代或补充套接字。
- 将数据存储在其他位置。
- 破坏性地重新播种 GitLab 数据库。
- 关于更新打包的 PostgreSQL 的指导，包括如何阻止其自动发生。
关于外部 PostgreSQL 的信息。
使用外部 PostgreSQL 运行 Geo。
运行配置为 HA 的 PostgreSQL 时的升级。
从 CI 运行器内使用 PostgreSQL。
从 Linux 软件包开发文档管理 Linux 软件包安装上的 PostgreSQL 版本。
PostgreSQL 扩展
- 包括故障排除 gitlab-ctl patroni check-leader 和 PgBouncer 错误。
开发者数据库文档，其中一些绝对不适用于生产环境。包括：
- 理解 EXPLAIN 计划。

支持主题

数据库死锁

参考：

如果实例被大量推送请求淹没，可能会发生死锁。提供关于 GitLab 代码在异常情况下如何产生此类意外影响的背景信息。

ERROR: deadlock detected

在问题 #30528 中确定了三个适用的超时设置；我们的推荐设置如下：

deadlock_timeout = 5s
statement_timeout = 15s
idle_in_transaction_session_timeout = 60s

引用问题 #30528：

“如果发生死锁，我们在短时间后通过中止事务来解决它，那么我们已经拥有的重试机制将使死锁的工作再次尝试，而且我们不太可能连续多次死锁。”

在支持团队中，我们重新配置超时（也适用于 HTTP 栈）的一般方法是，临时将其作为解决方法是可以接受的。如果它使 GitLab 对客户可用，那么它就为更全面地理解问题、实施热修复或进行其他解决根本原因的更改争取了时间。通常，在根本原因解决后，应将超时设置恢复为合理的默认值。

在这种情况下，我们从开发团队获得的指导是降低 deadlock_timeout 或 statement_timeout，但将第三个设置保留为 60 秒。设置 idle_in_transaction 可以保护数据库免受会话可能挂起数天的影响。在关于在 GitLab.com 上引入此超时的问题中有更多讨论。

PostgreSQL 默认值：

statement_timeout = 0（从不）
idle_in_transaction_session_timeout = 0（从不）

问题 #30528 中的评论表明，对于所有 Linux 软件包安装，这两个值都应该设置为至少几分钟（这样它们就不会无限期挂起）。但是，15 秒的 statement_timeout 非常短，只有当底层基础设施性能非常好时才有效。

使用以下命令查看当前设置：

sudo gitlab-rails runner "c = ApplicationRecord.connection ; puts c.execute('SHOW statement_timeout').to_a ;
puts c.execute('SHOW deadlock_timeout').to_a ;
puts c.execute('SHOW idle_in_transaction_session_timeout').to_a ;"

可能需要一些时间来响应。

{"statement_timeout"=>"1min"}
{"deadlock_timeout"=>"0"}
{"idle_in_transaction_session_timeout"=>"1min"}

这些设置可以在 /etc/gitlab/gitlab.rb 中更新：

postgresql['deadlock_timeout'] = '5s'
postgresql['statement_timeout'] = '15s'
postgresql['idle_in_transaction_session_timeout'] = '60s'

保存后，重新配置 GitLab 以使更改生效。

这些是 Linux 软件包设置。如果使用外部数据库，例如客户的 PostgreSQL 安装或 Amazon RDS，这些值不会被设置，必须在外部设置。

临时更改语句超时

以下建议在启用 PgBouncer 的情况下不适用，因为更改的超时可能会影响比预期更多的事务。

在某些情况下，可能需要设置不同的语句超时，而不必重新配置 GitLab，因为在这种情况下会重启 Puma 和 Sidekiq。

例如，由于语句超时太短，备份可能会在备份命令的输出中失败并出现以下错误：

pg_dump: error: Error message from server: server closed the connection unexpectedly

您也可能在 PostgreSQL 日志中看到错误：

canceling statement due to statement timeout

要临时更改语句超时：

在编辑器中打开 /var/opt/gitlab/gitlab-rails/etc/database.yml
将 statement_timeout 的值设置为 0，这将设置无限制的语句超时。

在新的 Rails 控制台会话中确认使用了此值：

sudo gitlab-rails runner "ActiveRecord::Base.connection_db_config[:variables]"

执行需要不同超时的操作（例如备份或 Rails 命令）。
恢复 /var/opt/gitlab/gitlab-rails/etc/database.yml 中的编辑。

观察 (RE)INDEX 进度报告

在某些情况下，您可能希望观察 CREATE INDEX 或 REINDEX 操作的进度。例如，您可以这样做来确认 CREATE INDEX 或 REINDEX 操作是否处于活动状态，或者检查操作处于哪个阶段。

先决条件：

您必须使用 PostgreSQL 12 或更高版本。

要观察 CREATE INDEX 或 REINDEX 操作：

使用内置的 pg_stat_progress_create_index 视图。

例如，从数据库控制台会话中，运行以下命令：

SELECT * FROM  pg_stat_progress_create_index \watch 0.2

要了解有关生成友好输出和将数据写入日志文件的更多信息，请参阅此代码片段。

故障排除

数据库连接被拒绝

如果您遇到以下错误，请检查 max_connections 是否足够高以确保稳定连接。

connection to server at "xxx.xxx.xxx.xxx", port 5432 failed: Connection refused
      Is the server running on that host and accepting TCP/IP connections?

psql: error: connection to server on socket "/var/opt/gitlab/postgresql/.s.PGSQL.5432" failed:
FATAL:  sorry, too many clients already

要调整 max_connections，请参阅配置多个数据库连接。

数据库不接受命令以避免回卷数据丢失

此错误可能意味着 autovacuum 无法完成其运行：

ERROR:  database is not accepting commands to avoid wraparound data loss in database "gitlabhq_production"

或者

 ERROR:  failed to re-find parent key in index "XXX" for deletion target page XXX

要解决此错误，请手动运行 VACUUM：

使用命令 gitlab-ctl stop 停止 GitLab。

使用以下命令将数据库置于单用户模式：

/opt/gitlab/embedded/bin/postgres --single -D /var/opt/gitlab/postgresql/data gitlabhq_production

在 backend> 提示符下，运行 VACUUM;。此命令可能需要几分钟才能完成。
等待命令完成，然后按 Control + D 退出。
使用命令 gitlab-ctl start 启动 GitLab。

GitLab 数据库要求

请参阅数据库要求并查看和安装必需的扩展列表。

`production/sidekiq` 日志中的序列化错误

如果您在 production/sidekiq 日志中收到类似此示例的错误，请阅读关于将 default_transaction_isolation 设置为 read committed 以解决问题的信息：

ActiveRecord::StatementInvalid PG::TRSerializationFailure: ERROR:  could not serialize access due to concurrent update

PostgreSQL 复制槽错误

如果您收到类似此示例的错误，请阅读有关如何解决 PostgreSQL HA 复制槽错误的信息：

pg_basebackup: could not create temporary replication slot "pg_basebackup_12345": ERROR:  all replication slots are in use
HINT:  Free one or increase max_replication_slots.

Geo 复制错误

如果您收到类似此示例的错误，请阅读有关如何解决 Geo 复制错误的信息：

ERROR: replication slots can only be used if max_replication_slots > 0

FATAL: could not start WAL streaming: ERROR: replication slot "geo_secondary_my_domain_com" does not exist

Command exceeded allowed execution time

PANIC: could not write to file 'pg_xlog/xlogtemp.123': No space left on device

查看 Geo 配置和常见错误

在排查 Geo 问题时，您应该：

查看常见的 Geo 错误。
查看您的 Geo 配置，包括：
- 重新配置主机和端口。
- 查看和修复用户和密码映射。

`pg_dump` 和 `psql` 版本不匹配

如果您收到类似此示例的错误，请阅读有关如何备份和恢复非打包的 PostgreSQL 数据库的信息：

Dumping PostgreSQL database gitlabhq_production ... pg_dump: error: server version: 13.3; pg_dump version: 14.2
pg_dump: error: aborting because of server version mismatch

扩展 `btree_gist` 不在允许列表中

在 Azure Database for PostgreSQL - Flexible Server 上部署 PostgreSQL 可能会导致此错误：

extension "btree_gist" is not allow-listed for "azure_pg_admin" users in Azure Database for PostgreSQL

要解决此错误，请在安装前将扩展添加到允许列表。