企业官网建设流程全解析

• 数据库
• 图数据库
• 关系型数据库

本篇技术指南围绕 Gel 官方 CLI 的gel extension install命令展开，系统讲解如何为本地项目管理的实例安装独立扩展包（standalone extension），覆盖命令语法、参数、全局连接选项、完整工作流（查询可用扩展 → 安装 → 重启实例 → 在 schema 中声明）以及底层源码实现原理。读完本文，你将能够熟练管理postgis等独立扩展包，并理解扩展版本解析、ext::模块约束等内部机制。

命令概述：一条命令安装独立扩展

gel extension install是 Gel CLI 中gel extension命令组（命令组索引）的子命令之一，用于在本地项目管理的实例上安装独立扩展包。

与edgeql_http、graphql、auth、ai、pg_trgm、pg_unaccent、pgcrypto、pgvector等随服务器内置的扩展不同，独立扩展以**独立的包（package）**形式存在，需要通过 CLI 从扩展仓库下载并安装到本地实例上，postgis是最典型的代表（详见 Extensions 文档 中 "Standalone extensions" 一节）。

gel extension命令组共包含四个子命令，构成完整的生命周期管理能力：

命令语法与参数

gel extension install的命令形式如下（install.rst）：

gel extension install <extension> [<options>]

位置参数：<extension>

<extension>是要安装的扩展名称，为必填参数。例如要安装postgis，直接将其作为参数传入：

$ gel extension install postgis Found extension package: postgis version 3.4.3+6b82d77 00:00:03 [====================] 22.49 MiB/22.49 MiB Extension 'postgis' installed successfully.

命令执行时会依次完成以下动作：

1. 发现扩展包：从扩展仓库解析出指定名称的扩展包及其版本（如postgis的3.4.3+6b82d77）；
2. 下载安装：以进度条形式显示下载进度与包体大小（示例中为22.49 MiB）；
3. 完成安装：输出Extension 'postgis' installed successfully.确认成功。

其中版本号3.4.3+6b82d77是扩展包自身的版本标识：3.4.3对应上游 PostgreSQL 扩展（PostGIS）的版本，6b82d77则是扩展包构建对应的提交标识，用于精确锁定某个构建产物。

选项：全局连接选项

gel extension install本身没有额外的专属选项，但它接受与所有 Gel CLI 命令一致的全局连接选项（Connection options），用于指定命令所作用的实例目标。这些选项的完整说明见 Connection flags 文档，常用选项包括：

连接目标的解析优先级为：显式连接参数（flag）→ 环境变量 → 当前目录是否处于与实例关联的项目目录内；若三者均无法确定，命令会失败。

例如，为指定本地实例安装postgis：

$ gel extension install postgis -I my_instance

完整实战流程：从查询到使用

独立扩展的安装并非一条命令即告结束，完整流程包含以下步骤（对应 Extensions 文档 的实操示例）。

1. 查看当前已安装的扩展

$ gel extension list ┌─────────┬───────────────┐ │ Name │ Version │ └─────────┴───────────────┘

新实例默认没有安装任何独立扩展，因此列表为空。

2. 查询可安装的扩展

$ gel extension list-available ┌─────────┬───────────────┐ │ Name │ Version │ │ postgis │ 3.4.3+6b82d77 │ └─────────┴───────────────┘

list-available会列出当前实例可用的扩展包及版本，可作为安装前的查询手段。

3. 安装扩展

$ gel extension install postgis Found extension package: postgis version 3.4.3+6b82d77 00:00:03 [====================] 22.49 MiB/22.49 MiB Extension 'postgis' installed successfully.

4. 验证安装结果

$ gel extension list ┌─────────┬───────────────┐ │ Name │ Version │ │ postgis │ 3.4.3+6b82d77 │ └─────────┴───────────────┘

5. 重启实例

安装完成后，务必重启实例以使扩展生效：

$ gel instance restart

6. 在 schema 中声明扩展

独立扩展与内置扩展的声明方式一致，在 schema 顶层添加using语句：

using extension postgis;

注意：using extension声明必须位于任何 module 块之外，因为扩展影响的是整个数据库（branch）而非某个特定模块。

7. 使用扩展

安装并声明后，扩展提供的类型、标量、函数等即可在 EdgeQL 查询和 schema 定义中使用。以postgis为例，它提供地理空间数据类型与函数，可用于存储和查询地理信息。

卸载扩展

如需卸载，使用gel extension uninstall（uninstall.rst）：

$ gel extension uninstall postgis Extension 'postgis' uninstalled successfully.

与 schema 层扩展声明的协同

值得强调的是，CLI 的gel extension install与 schema 中的扩展机制是两个层面、相辅相成的关系：

• CLI 层（包安装）：gel extension install负责把扩展包二进制下载并安装到本地实例中，属于"实例级"操作；
• Schema 层（声明启用）：using extension postgis;或 DDL 中的create extension graphql;负责在具体 schema 中启用扩展，属于"schema 级"操作。

在 Extensions 文档 中可以看到，内置扩展（如graphql、edgeql_http）直接通过using extension或create extension启用即可；而独立扩展必须先通过 CLI 完成包安装，然后才能在 schema 中声明。文档中明确给出对应的底层 DDL 命令（主要用于审查迁移文件）：

create extension graphql; create extension edgeql_http; drop extension graphql;

备份恢复注意事项

一个重要的运维细节：恢复（restore）使用了独立扩展的 dump 时，必须先安装对应的扩展，再执行恢复流程。否则恢复过程会因为缺少扩展包而失败（Extensions 文档 中的 note 明确指出了这一点）。因此，在跨环境迁移时，应先在目标实例上执行gel extension install <ext>，再执行gel restore。

源码级原理：扩展包是如何被解析与管理的

理解底层实现有助于排查问题。扩展的包管理逻辑集中在 edb/schema/extensions.py 中。

扩展包模型：版本是核心字段

ExtensionPackage是扩展包在 schema 中的表示，其核心字段是version（extensions.py 第 47-62 行）：

class ExtensionPackage(...): ... version = so.SchemaField( ... )

每个扩展包实例都携带独立的版本信息，因此同一扩展的不同版本可以在 schema 中以多个包的形式共存。

版本解析：精确匹配与取最新

扩展包解析逻辑位于get_package()函数（extensions.py 第 225-264 行）。从源码结构可以推断其行为：

• 当 schema 中存在指定版本时，优先使用精确版本；
• 若没有精确匹配，则取可用的最新版本；
• 若指定版本不存在且没有更旧的可用版本，会抛出错误并提示"extension package ... version ... does not exist"。

这意味着gel extension install下载的版本由远程仓库与本地 schema 状态共同决定，Found extension package: postgis version 3.4.3+6b82d77这行输出正是版本解析完成后的结果展示。

ext::模块前缀约束

扩展包声明了ext_module字段（extensions.py 第 86 行），表示扩展导出的模块。源码中对模块名有强制约束：扩展模块必须以ext::开头（extensions.py 第 645-653 行 附近）：

if module_name.get_root_module_name() != s_schema.EXT_MODULE: raise ... f'module "{module}": ' f'extension modules must begin with "ext::"'

这也是为什么postgis等扩展的模块均以ext::前缀暴露给用户。例如内置的pg_trgm、pg_unaccent、pgcrypto、pgvector分别对应ext::pg_trgm、ext::pg_unaccent、ext::pgcrypto、ext::pgvector模块（Extensions 文档）。

卸载时的模块清理

卸载扩展（gel extension uninstall）时，schema 层会执行对应的ExtensionPackageCommand（extensions.py 第 205 行 附近），其删除逻辑（extensions.py 第 859-933 行 附近）会：

1. 获取扩展包对应的模块名（get_ext_module）；
2. 若扩展携带模块，删除该模块及其子模块下的全部对象；
3. 保留__ext_casts__、__ext_index_matches__等内部模块中由扩展产生的类型转换和索引匹配定义，避免误删。

这一"重手笔"的模块级清理策略，保证了卸载后 schema 中不会残留扩展遗留的对象。

安装前置条件与适用范围

在使用gel extension install之前，请确认以下前提：

1. 实例类型：独立扩展包目前支持安装在本地项目管理的实例上（Extensions 文档 中明确表述为 "local project-managed instances"）；
2. 连接可达：命令通过全局连接选项定位目标实例，需确保连接参数正确（实例、DSN、host/port、branch 等）；
3. 重启生效：安装完成后需执行gel instance restart使扩展可用；
4. dump 恢复顺序：恢复含独立扩展的 dump 前，先安装对应扩展。

总结

gel extension install <extension>是 Gel 独立扩展包管理的核心入口，它完成了从远程仓库发现包、解析版本、下载安装到本地实例的全过程。将其与list、list-available、uninstall配合使用，再加上安装后的实例重启与 schema 中的using extension声明，即可完整地管理postgis等独立扩展。在底层，edb/schema/extensions.py 通过带版本字段的ExtensionPackage模型、精确/最新版本解析逻辑以及ext::模块前缀约束，保证了扩展包在 schema 层的正确表示与生命周期管理。

• 数据库
• 图数据库
• 关系型数据库