• 手动安装 PostgreSQL 扩展
• 常见故障情形

{{< details >}}

• Tier: 基础版, 专业版, 旗舰版
• Offering: 私有化部署

{{< /details >}}

这份指南记录了如何管理具有外部 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
                                        List of installed extensions
        Name    | Version |   Schema   |                            Description
    ------------+---------+------------+-------------------------------------------------------------------
    btree_gist | 1.5     | public     | support for indexing common datatypes in GiST
    pg_trgm    | 1.4     | public     | text similarity measurement and index searching based on trigrams
    plpgsql    | 1.0     | pg_catalog | PL/pgSQL procedural language
    (3 rows)
   

在某些系统中，您可能需要安装一个额外的软件包（例如，postgresql-contrib），以便某些扩展可用。

常见故障情形

以下是由于尚未安装扩展而导致新的极狐GitLab 安装失败的示例。

---- Begin output of "bash"  "/tmp/chef-script20210513-52940-d9b1gs" ----
STDOUT: psql:/opt/gitlab/embedded/service/gitlab-rails/db/structure.sql:9: ERROR:  permission denied to create extension "btree_gist"
HINT:  Must be superuser to create this extension.
rake aborted!
failed to execute:
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: migrating =========================
-- 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