管理 PostgreSQL 扩展

本指南介绍了如何为使用外部 PostgreSQL 数据库的安装管理 PostgreSQL 扩展。

您必须将以下扩展加载到主 GitLab 数据库（默认为 gitlabhq_production）：

如果您使用的是 GitLab Geo，则必须将以下扩展加载到所有辅助跟踪数据库（默认为 gitlabhq_geo_production）：

要安装扩展，PostgreSQL 要求用户具有超级用户权限。通常，GitLab 数据库用户不是超级用户。因此，无法使用常规的数据库迁移来安装扩展，而是在升级 GitLab 到新版本之前，必须手动安装扩展。

手动安装 PostgreSQL 扩展

要安装 PostgreSQL 扩展，应遵循以下步骤：

1. 使用超级用户连接到 GitLab PostgreSQL 数据库，例如：

   sudo gitlab-psql -d gitlabhq_production

2. 使用 CREATE EXTENSION 安装扩展（本示例中为 btree_gist）：

   CREATE EXTENSION IF NOT EXISTS btree_gist

3. 验证已安装的扩展：

    gitlabhq_production=# \dx
                                        已安装扩展列表
        名称    | 版本 |   模式   |                            描述
    ------------+---------+------------+-------------------------------------------------------------------
    btree_gist | 1.5     | public     | 支持在 GiST 中索引常见数据类型
    pg_trgm    | 1.4     | public     | 基于三字母组的文本相似度测量和索引搜索
    plpgsql    | 1.0     | pg_catalog | PL/pgSQL 过程语言
    (3 行)

在某些系统上，您可能需要安装额外的软件包（例如 postgresql-contrib），才能使某些扩展可用。

常见失败场景

以下是一个新 GitLab 安装失败的示例，原因是未预先安装扩展。

---- "bash" "/tmp/chef-script20210513-52940-d9b1gs" 输出开始 ----
STDOUT: psql:/opt/gitlab/embedded/service/gitlab-rails/db/structure.sql:9: ERROR:  没有权限创建扩展 "btree_gist"
HINT:  必须是超级用户才能创建此扩展。
rake aborted!
执行失败：
psql -v ON_ERROR_STOP=1 -q -X -f /opt/gitlab/embedded/service/gitlab-rails/db/structure.sql --single-transaction gitlabhq_production

以下是在运行迁移之前未安装扩展的示例。在这种情况下，由于权限不足，数据库迁移无法创建扩展 btree_gist。

== 20200515152649 EnableBtreeGistExtension: 迁移中 =========================
-- execute("CREATE EXTENSION IF NOT EXISTS btree_gist")

GitLab 要求在数据库 'gitlabhq_production' 中安装 PostgreSQL 扩展 'btree_gist'，但
数据库用户不被允许安装该扩展。

您可以使用数据库超级用户手动安装扩展：

  CREATE EXTENSION IF NOT EXISTS btree_gist

或者，您可以通过使用超级用户登录 GitLab 数据库 (gitlabhq_production) 并运行以下命令来解决此问题：

    ALTER regular WITH SUPERUSER

此查询将授予用户超级用户权限，确保任何数据库扩展
都可以通过迁移安装。

要从失败的迁移中恢复，必须由超级用户手动安装扩展，并通过重新运行数据库迁移完成 GitLab 升级：

sudo gitlab-rake db:migrate