Gel CLI 扩展管理一gel extension list-available命令详解与可用扩展查询实战【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址: https://gitcode.com/gh_mirrors/ed/edgedb导读gel extension list-available是 Gel CLI 中用于列出当前可安装available扩展包的子命令是扩展生命周期管理的起点——在安装install、声明using extension之前先通过它确认目标扩展是否可获取及其具体版本号。本文将围绕该命令的语法、输出格式、与gel extension list的区别结合 Gel 源码edb/load_ext/main.py与edb/schema/extensions.py与官方文档docs/reference/datamodel/extensions.rst讲透从“查询可用扩展”到“安装并启用扩展”的完整链路。一、命令定位扩展命令组中的“查询窗口”gel extension是一个命令组command group对应docs/reference/using/cli/gel_extension/index.rst包含四个子命令构成扩展管理的完整闭环子命令作用gel extension list列出已安装installed的扩展gel extension list-available列出可安装available的扩展gel extension install extension安装指定扩展gel extension uninstall extension卸载指定扩展list-available与list表面相似实则对应两条不同的数据来源前者查询的是扩展包的发布仓库/可用包列表回答“我能装什么”后者查询的是当前实例已经装好的扩展回答“我装了什么”。两个命令通常配合使用先用list-available探测目标扩展是否存在及版本再用install安装最后用list验证安装结果gel extension list的文档见 list.rst安装与卸载分别见 install.rst 与 uninstall.rst。二、命令语法与全局选项gel extension list-available的完整语法为gel extension list-available [options]该命令不需要任何位置参数——它不针对某个具体扩展而是枚举当前环境下所有可用的扩展包。可用选项均为全局连接选项Connection options涵盖目标实例、数据库、用户名、凭据、项目目录等例如# 列出默认当前项目或本地实例环境下的可用扩展 gel extension list-available # 显式指定实例与数据库后查询 gel extension list-available --instance my-instance --database mydb # 使用 DSN 连接远程实例后查询 gel extension list-available --dsn gel://user:passhost:5656/db所有全局选项的完整清单、默认值与取值说明见 docs/reference/using/cli/gel_connopts.rst。由于可用扩展列表可能因实例类型与版本而异当项目同时关联多个实例时建议显式指定--instance或--dsn避免查询到非目标环境的结果。三、输出格式解读命令成功执行后以 ASCII 表格形式输出两列Name扩展名与Version版本号。以postgis为例来源list-available.rst$ gel extension list-available ┌─────────┬───────────────┐ │ Name │ Version │ │ postgis │ 3.4.36b82d77 │ └─────────┴───────────────┘输出解读要点Name扩展的规范化名称小写、无命名空间前缀如postgis与后续gel extension install postgis使用的名称完全一致Version完整版本标识符形如3.4.36b82d77。其中3.4.3是扩展自身的语义化版本号6b82d77是构建标识build metadata标识该版本对应的具体构建提交或包版本用于精确区分同一扩展的不同构建产物若当前环境下没有可安装的扩展包表格将仅保留表头Name/Version两行行为与gel extension list的空结果一致见docs/reference/datamodel/extensions.rst中list与list-available的空表输出示例。四、可用扩展 vs 内建扩展明确list-available的边界理解list-available的输出范围需要先区分 Gel 的两类扩展详见 docs/reference/datamodel/extensions.rst内建扩展built-in extensions随 Gel 服务端分发通过 SDL 顶层using extension name;语句直接声明启用无需也无需通过list-available/install管理。常见内建扩展包括edgeql_http启用 EdgeQL over HTTPgraphql启用 GraphQL 端点auth启用 Gel Authai启用ext::ai模块pg_trgm、pg_unaccent、pgcrypto、pgvector对 PostgreSQL 相应扩展的再导出封装。独立扩展包standalone extensions以 zip 包形式分发、需要通过 CLI 安装的扩展list-available查询的正是这一类。当前仓库中的典型代表是postgis。在 SDL 中声明独立扩展的写法与内建扩展完全一致来源docs/reference/datamodel/extensions.rstusing extension postgis;二者的关系可总结为内建扩展开箱即用独立扩展先查询list-available→ 安装install→ 声明using extension。五、实战从查询到启用的完整扩展流程list-available是扩展管理流程的第一步。以下以postgis为例串联list-available与其余子命令构成可直接照搬的完整操作序列命令输出来自 install.rst 与 docs/reference/datamodel/extensions.rst第 1 步确认可用扩展及版本$ gel extension list-available ┌─────────┬───────────────┐ │ Name │ Version │ │ postgis │ 3.4.36b82d77 │ └─────────┴───────────────┘第 2 步安装扩展$ gel extension install postgis Found extension package: postgis version 3.4.36b82d77 00:00:03 [] 22.49 MiB/22.49 MiB Extension postgis installed successfully.注意安装输出中的Found extension package: postgis version 3.4.36b82d77与第 1 步list-available展示的版本号一一对应——这正是list-available提供版本信息的意义先看清版本再决定安装避免安装到非预期构建。第 3 步验证安装结果$ gel extension list ┌─────────┬───────────────┐ │ Name │ Version │ │ postgis │ 3.4.36b82d77 │ └─────────┴───────────────┘第 4 步重启实例使扩展生效$ gel instance restart官方文档明确要求安装扩展后重启实例见 docs/reference/datamodel/extensions.rst。第 5 步在 schema 中声明并启用using extension postgis;注意事项使用独立扩展创建的数据库在 dump/restore 时必须先安装对应扩展再执行 restore否则恢复过程会因缺少扩展而失败docs/reference/datamodel/extensions.rst 明确注明此限制。因此在备份迁移、克隆环境等场景下list-available同样是前置检查的关键一步确认目标实例的扩展源可访问、目标版本可用。六、源码视角可用扩展背后的安装与分发机制list-available面向用户呈现的是一行简明的表格其背后是 Gel 对独立扩展包的一整套管理机制可从源码中得到印证。6.1 扩展包的结构与清单MANIFEST.toml独立扩展以 zip 包分发包内必须包含一个顶层目录目录下含有MANIFEST.toml清单文件。在edb/load_ext/main.py中get_dir()强制校验这一点def get_dir(z: zipfile.ZipFile) - pathlib.Path: files z.infolist() if not (files and files[0].is_dir()): print(ERROR: Extension package must contain one top-level dir) sys.exit(1) dirname pathlib.Path(files[0].filename) return dirname随后install_edgedb_extension()edb/load_ext/main.py通过tomllib解析MANIFEST.toml并按清单中files字段列出的文件列表解包落盘。也就是说“可用扩展”本质上是一个个符合此打包规范的 zip 包list-available展示的版本号3.4.36b82d77即来自各包的版本元数据。6.2 扩展与 PostgreSQL 层的映射对需要下沉到 PostgreSQL 的扩展如postgis安装时会进一步把包内文件分发到pg_config报告的目录中。edb/load_ext/main.py中的CONFIG_PATHS明确映射了三个目录类别CONFIG_PATHS { share: sharedir, lib: pkglibdir, include: pkgincludedir-server, }包内share/postgresql/、lib/postgresql/、include/postgresql/下的文件会分别落入 PostgreSQL 的sharedir、pkglibdir、pkgincludedir-server安装过程还会生成 manifest 记录已安装文件供卸载时精确清理uninstall_pg_extensionedb/load_ext/main.py。这也解释了为何list-available的可用列表与本地 PostgreSQL 构建相关——可用扩展包必须与当前实例底层的 PostgreSQL 环境兼容。6.3 扩展版本约束与解析在 SDL 层扩展声明支持版本约束如using extension ltree version 2.0服务端在解析时会校验“包内sql_extensions声明的 PostgreSQL 扩展版本范围”是否可满足。tests/test_edgeql_extensions.py中构造了完整的负向用例当声明的版本约束无法满足时例如ltree 1000.0测试断言服务端报错could not find extension satisfying ...见 tests/test_edgeql_extensions.py。这说明可用扩展列表并非静态的——服务端会依据版本约束动态匹配可用的 PostgreSQL 扩展版本而list-available输出的版本号正是这一匹配过程的输入锚点。七、常见使用场景小结环境侦察在新实例或新项目上第一时间用list-available确认扩展源可用、版本符合预期再做install避免直接安装导致版本不符安装前核对与install输出的Found extension package: ... version ...对照确保装的就是查到的版本与list对比排障list有而list-available没有说明扩展可能来自旧版本残留或手动部署list-available有而list没有说明尚未安装可放心执行安装流程dump/restore 前置检查恢复含独立扩展的 dump 前先确认目标实例list-available能取到对应扩展包并完成安装限制见 docs/reference/datamodel/extensions.rst。结语gel extension list-available虽是一个零参数的查询命令却是 Gel 扩展管理链路的“第一道闸门”它以两列表格明确回答“当前环境能安装哪些扩展、各是什么版本”为后续的install、schema 声明using extension与 dump/restore 流程提供版本依据。结合 edb/load_ext/main.py 中扩展包的打包与安装机制、edb/schema/extensions.py 中的版本解析逻辑以及 tests/test_edgeql_extensions.py 中的约束校验用例可以完整理解从“查询可用”到“安装启用”的每一个环节。更多扩展管理命令请参阅 gel_extension 命令组文档 与 扩展数据模型文档。【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址: https://gitcode.com/gh_mirrors/ed/edgedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gel CLI 扩展管理（一）：`gel extension list-available` 命令详解与可用扩展查询实战
Gel CLI 扩展管理一gel extension list-available命令详解与可用扩展查询实战【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址: https://gitcode.com/gh_mirrors/ed/edgedb导读gel extension list-available是 Gel CLI 中用于列出当前可安装available扩展包的子命令是扩展生命周期管理的起点——在安装install、声明using extension之前先通过它确认目标扩展是否可获取及其具体版本号。本文将围绕该命令的语法、输出格式、与gel extension list的区别结合 Gel 源码edb/load_ext/main.py与edb/schema/extensions.py与官方文档docs/reference/datamodel/extensions.rst讲透从“查询可用扩展”到“安装并启用扩展”的完整链路。一、命令定位扩展命令组中的“查询窗口”gel extension是一个命令组command group对应docs/reference/using/cli/gel_extension/index.rst包含四个子命令构成扩展管理的完整闭环子命令作用gel extension list列出已安装installed的扩展gel extension list-available列出可安装available的扩展gel extension install extension安装指定扩展gel extension uninstall extension卸载指定扩展list-available与list表面相似实则对应两条不同的数据来源前者查询的是扩展包的发布仓库/可用包列表回答“我能装什么”后者查询的是当前实例已经装好的扩展回答“我装了什么”。两个命令通常配合使用先用list-available探测目标扩展是否存在及版本再用install安装最后用list验证安装结果gel extension list的文档见 list.rst安装与卸载分别见 install.rst 与 uninstall.rst。二、命令语法与全局选项gel extension list-available的完整语法为gel extension list-available [options]该命令不需要任何位置参数——它不针对某个具体扩展而是枚举当前环境下所有可用的扩展包。可用选项均为全局连接选项Connection options涵盖目标实例、数据库、用户名、凭据、项目目录等例如# 列出默认当前项目或本地实例环境下的可用扩展 gel extension list-available # 显式指定实例与数据库后查询 gel extension list-available --instance my-instance --database mydb # 使用 DSN 连接远程实例后查询 gel extension list-available --dsn gel://user:passhost:5656/db所有全局选项的完整清单、默认值与取值说明见 docs/reference/using/cli/gel_connopts.rst。由于可用扩展列表可能因实例类型与版本而异当项目同时关联多个实例时建议显式指定--instance或--dsn避免查询到非目标环境的结果。三、输出格式解读命令成功执行后以 ASCII 表格形式输出两列Name扩展名与Version版本号。以postgis为例来源list-available.rst$ gel extension list-available ┌─────────┬───────────────┐ │ Name │ Version │ │ postgis │ 3.4.36b82d77 │ └─────────┴───────────────┘输出解读要点Name扩展的规范化名称小写、无命名空间前缀如postgis与后续gel extension install postgis使用的名称完全一致Version完整版本标识符形如3.4.36b82d77。其中3.4.3是扩展自身的语义化版本号6b82d77是构建标识build metadata标识该版本对应的具体构建提交或包版本用于精确区分同一扩展的不同构建产物若当前环境下没有可安装的扩展包表格将仅保留表头Name/Version两行行为与gel extension list的空结果一致见docs/reference/datamodel/extensions.rst中list与list-available的空表输出示例。四、可用扩展 vs 内建扩展明确list-available的边界理解list-available的输出范围需要先区分 Gel 的两类扩展详见 docs/reference/datamodel/extensions.rst内建扩展built-in extensions随 Gel 服务端分发通过 SDL 顶层using extension name;语句直接声明启用无需也无需通过list-available/install管理。常见内建扩展包括edgeql_http启用 EdgeQL over HTTPgraphql启用 GraphQL 端点auth启用 Gel Authai启用ext::ai模块pg_trgm、pg_unaccent、pgcrypto、pgvector对 PostgreSQL 相应扩展的再导出封装。独立扩展包standalone extensions以 zip 包形式分发、需要通过 CLI 安装的扩展list-available查询的正是这一类。当前仓库中的典型代表是postgis。在 SDL 中声明独立扩展的写法与内建扩展完全一致来源docs/reference/datamodel/extensions.rstusing extension postgis;二者的关系可总结为内建扩展开箱即用独立扩展先查询list-available→ 安装install→ 声明using extension。五、实战从查询到启用的完整扩展流程list-available是扩展管理流程的第一步。以下以postgis为例串联list-available与其余子命令构成可直接照搬的完整操作序列命令输出来自 install.rst 与 docs/reference/datamodel/extensions.rst第 1 步确认可用扩展及版本$ gel extension list-available ┌─────────┬───────────────┐ │ Name │ Version │ │ postgis │ 3.4.36b82d77 │ └─────────┴───────────────┘第 2 步安装扩展$ gel extension install postgis Found extension package: postgis version 3.4.36b82d77 00:00:03 [] 22.49 MiB/22.49 MiB Extension postgis installed successfully.注意安装输出中的Found extension package: postgis version 3.4.36b82d77与第 1 步list-available展示的版本号一一对应——这正是list-available提供版本信息的意义先看清版本再决定安装避免安装到非预期构建。第 3 步验证安装结果$ gel extension list ┌─────────┬───────────────┐ │ Name │ Version │ │ postgis │ 3.4.36b82d77 │ └─────────┴───────────────┘第 4 步重启实例使扩展生效$ gel instance restart官方文档明确要求安装扩展后重启实例见 docs/reference/datamodel/extensions.rst。第 5 步在 schema 中声明并启用using extension postgis;注意事项使用独立扩展创建的数据库在 dump/restore 时必须先安装对应扩展再执行 restore否则恢复过程会因缺少扩展而失败docs/reference/datamodel/extensions.rst 明确注明此限制。因此在备份迁移、克隆环境等场景下list-available同样是前置检查的关键一步确认目标实例的扩展源可访问、目标版本可用。六、源码视角可用扩展背后的安装与分发机制list-available面向用户呈现的是一行简明的表格其背后是 Gel 对独立扩展包的一整套管理机制可从源码中得到印证。6.1 扩展包的结构与清单MANIFEST.toml独立扩展以 zip 包分发包内必须包含一个顶层目录目录下含有MANIFEST.toml清单文件。在edb/load_ext/main.py中get_dir()强制校验这一点def get_dir(z: zipfile.ZipFile) - pathlib.Path: files z.infolist() if not (files and files[0].is_dir()): print(ERROR: Extension package must contain one top-level dir) sys.exit(1) dirname pathlib.Path(files[0].filename) return dirname随后install_edgedb_extension()edb/load_ext/main.py通过tomllib解析MANIFEST.toml并按清单中files字段列出的文件列表解包落盘。也就是说“可用扩展”本质上是一个个符合此打包规范的 zip 包list-available展示的版本号3.4.36b82d77即来自各包的版本元数据。6.2 扩展与 PostgreSQL 层的映射对需要下沉到 PostgreSQL 的扩展如postgis安装时会进一步把包内文件分发到pg_config报告的目录中。edb/load_ext/main.py中的CONFIG_PATHS明确映射了三个目录类别CONFIG_PATHS { share: sharedir, lib: pkglibdir, include: pkgincludedir-server, }包内share/postgresql/、lib/postgresql/、include/postgresql/下的文件会分别落入 PostgreSQL 的sharedir、pkglibdir、pkgincludedir-server安装过程还会生成 manifest 记录已安装文件供卸载时精确清理uninstall_pg_extensionedb/load_ext/main.py。这也解释了为何list-available的可用列表与本地 PostgreSQL 构建相关——可用扩展包必须与当前实例底层的 PostgreSQL 环境兼容。6.3 扩展版本约束与解析在 SDL 层扩展声明支持版本约束如using extension ltree version 2.0服务端在解析时会校验“包内sql_extensions声明的 PostgreSQL 扩展版本范围”是否可满足。tests/test_edgeql_extensions.py中构造了完整的负向用例当声明的版本约束无法满足时例如ltree 1000.0测试断言服务端报错could not find extension satisfying ...见 tests/test_edgeql_extensions.py。这说明可用扩展列表并非静态的——服务端会依据版本约束动态匹配可用的 PostgreSQL 扩展版本而list-available输出的版本号正是这一匹配过程的输入锚点。七、常见使用场景小结环境侦察在新实例或新项目上第一时间用list-available确认扩展源可用、版本符合预期再做install避免直接安装导致版本不符安装前核对与install输出的Found extension package: ... version ...对照确保装的就是查到的版本与list对比排障list有而list-available没有说明扩展可能来自旧版本残留或手动部署list-available有而list没有说明尚未安装可放心执行安装流程dump/restore 前置检查恢复含独立扩展的 dump 前先确认目标实例list-available能取到对应扩展包并完成安装限制见 docs/reference/datamodel/extensions.rst。结语gel extension list-available虽是一个零参数的查询命令却是 Gel 扩展管理链路的“第一道闸门”它以两列表格明确回答“当前环境能安装哪些扩展、各是什么版本”为后续的install、schema 声明using extension与 dump/restore 流程提供版本依据。结合 edb/load_ext/main.py 中扩展包的打包与安装机制、edb/schema/extensions.py 中的版本解析逻辑以及 tests/test_edgeql_extensions.py 中的约束校验用例可以完整理解从“查询可用”到“安装启用”的每一个环节。更多扩展管理命令请参阅 gel_extension 命令组文档 与 扩展数据模型文档。【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址: https://gitcode.com/gh_mirrors/ed/edgedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考