Gel CLI 实战gel describe schema命令详解与原理剖析【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址: https://gitcode.com/gh_mirrors/ed/edgedbgel describe schema是 Gel 官方 CLI 中用于对当前连接数据库执行 Schema 内省introspection的核心命令它能在终端中直接输出整库的 SDL 结构描述是开发者快速审查数据模型、准备迁移、编写测试与核对版本间差异的利器。读完本文你将掌握该命令的完整语法、连接目标指定方式、SDL/DDL 输出格式的差异以及其在 Gel 编译器EdgeQL Compiler中的底层实现原理。本文内容以仓库文档 docs/reference/using/cli/gel_describe/gel_describe_schema.rst 为骨架并结合 describe 语句参考、连接选项文档 及 编译器实现 进行深度扩充。命令概览gel describe schema的作用是给出由连接选项所指定数据库的 Schema 的 SDLSchema Definition Language描述。其命令行语法synopsis为gel describe schema [options]从命令归属上看它位于gel describe命令组之下。该命令组是一系列 Schema 内省工具的集合gel describe组包含两个子命令见 gel_describe/index.rst子命令说明gel describe object描述一个具名的 Schema 对象type、link、property、function 等gel describe schema描述当前数据库分支的完整 Schema与 EdgeQLdescribe内省语句的关系文档明确指出gel describe schema是终端命令其等价于 EdgeQL 内省语句describe schema as sdl参见 describe 语句参考。也就是说下面两种写法在语义上是等价的# CLI 方式 gel describe schema # EdgeQL 方式在交互式 shell 或查询中 db describe schema as sdl;describe语句本身支持三种输出格式理解它们的差异有助于你准确使用 CLI 命令as ddl输出完整的 DDLData Definition Language定义即create type ...、create constraint ...形式的迁移式语句。生成的 DDL 是某个 Schema 对象或整个库的完整有效定义前提是其所引用的其他 Schema 对象已存在。as sdl输出 SDL 定义即type ... { ... }形式的声明式数据模型。SDL 是 Gel 推荐的声明式 Schema 表达方式也是gel describe schemaCLI 命令的默认输出。生成的 SDL 同样是完整有效的定义。as text [verbose]输出面向人的定义与 SDL 类似但会包含所有继承而来的细节。verbose模式会额外展示注解annotations与约束constraints等默认被省略的信息。一个值得注意的细节是describe语句的输出类型是str但它不能作为表达式嵌入到查询中使用——它是一条专用的内省语句而非普通函数。CLI 默认输出 SDL 的含义由于gel describe schema等价于describe schema as sdl因此你在终端中运行它得到的就是一段可以直接用于重建数据模型的 SDL 文本。同时从编译器实现看完整的 Schema 描述还支持 DDL 输出详见下文底层实现原理一节只是 CLI 命令将 SDL 作为默认与约定的输出格式。连接目标Connection Optionsgel describe schema命令运行在它所连接的数据库上因此指定连接目标的方式与所有 Gel CLI 命令一致——通过一组标准的连接选项connection flags。相关完整说明见 连接选项文档其解析优先级为显式 flag 优先CLI 始终尊重通过 flag 显式传入的连接参数环境变量若未提供 flag则使用环境变量如GEL_HOST、GEL_PORT、GEL_BRANCH等来确定实例项目目录若没有环境变量CLI 会检查当前工作目录是否位于某个已关联实例的项目目录内并使用项目配置失败以上条件都不满足时命令报错退出。常用连接参数如下完整清单请查阅 gel_connopts.rst选项说明-I name, --instancename指定要连接的命名实例Gel Cloud 实例名格式为org-name/instance-name覆盖 host/port--dsndsn指定连接 DSN覆盖除密码外的所有其他选项--credentials-file /path/to/file指向包含凭据的 JSON 文件-H hostname, --hosthostname服务器主机名默认取GEL_HOST环境变量-P port, --portportTCP 端口默认取GEL_PORT环境变量否则为5656--unix-path /path/to/socketUnix socket 路径若为目录则按 port 与 admin 参数计算实际路径--admin通过免密 Unix socket 连接默认以超级用户权限连接-u username, --userusername以指定用户连接默认取GEL_USER否则为 admin-b branch_name, --branchbranch_name指定分支名默认取GEL_BRANCH本地实例默认最近切换的分支或 main 分支--password / --no-password强制/禁止密码提示--password-from-stdin将标准输入的第一行作为密码--tls-ca-file /path/to/cert校验服务器的证书自签名服务器证书或 CA 证书--tls-security modeTLS 安全模式default、strict、no_host_verification、insecure--secret-key key连接 Gel Cloud 实例的 secret key--wait-until-availablewait_time连接失败时持续重试直至达到指定时长如30s--connect-timeouttimeout连接超时时间默认10s注在 EdgeDB 5 之前分支被称为数据库旧的-d dbname, --databasedbname与GEL_DATABASE环境变量仍被保留以作向后兼容。典型用法示例# 使用当前项目关联的实例最常见自动解析连接参数 gel describe schema # 显式指定实例 gel describe schema -I my_instance # 指定主机、端口、分支 gel describe schema -H localhost -P 5656 -b main # 通过 DSN 连接远程实例 gel describe schema --dsngel://user:passwordhost:5656/main # 输出到文件便于版本对比或迁移准备 gel describe schema current_schema.sdl输出格式示例从 CLI 到 EdgeQL以下示例取自 describe 语句参考 并适配 CLI 视角。假设数据库中存在如下 SDL 数据模型abstract type Named { required name: str { delegated constraint exclusive; } } type User extending Named { required email: str { annotation title : Contact email; } }在 EdgeQL shell 中执行describe schema;其默认输出为 DDL 格式可以得到整个数据库 Schema 的完整 DDL 描述db describe schema; { create module default if not exists; create abstract type default::Named { create required single property name - std::str { create delegated constraint std::exclusive; }; }; create type default::User extending default::Named { create required single property email - std::str { create annotation std::title : Contact email; }; }; }而在 CLI 中执行gel describe schema等价于describe schema as sdl你将得到对应的声明式 SDLtype default::User extending default::Named { required single property email - std::str { annotation std::title : Contact email; }; };两者的区别可以这样理解SDLCLI 默认声明式模型描述Schema 长什么样适合阅读、评审与作为数据模型的真源source of truthDDL命令式变更描述如何创建出这样的 Schema适合迁移脚本与从零建库。屏蔽Masking警告describe命令还具备一个实用特性当用户自定义对象屏蔽mask了标准库中的同名对象时它会给出警告提示。例如在default模块中自定义了len函数计算向量长度则会输出被屏蔽的内置std::len函数定义以注释形式附在结果中便于你意识到名称遮蔽问题。这也提醒我们gel describe schema输出的不只是我写了什么还包含标准库被遮蔽对象的信息是审计命名冲突的有效手段。底层实现原理编译器视角从源码层面看gel describe schema最终会转化为一条DescribeStmt描述语句并交由 EdgeQL 编译器处理。其关键实现在 edb/edgeql/compiler/stmt.py 的compile_DescribeStmt中约 L860-L891if ql.object is qlast.DescribeGlobal.Schema: if ql.language is qltypes.DescribeLanguage.DDL: # DESCRIBE SCHEMA AS DDL text s_ddl.ddl_text_from_schema( ctx.env.schema, ) elif ql.language is qltypes.DescribeLanguage.SDL: # DESCRIBE SCHEMA AS SDL text s_ddl.sdl_text_from_schema( ctx.env.schema, ) else: raise errors.QueryError( fcannot describe full schema as {ql.language}) # 结果以 std::str 字符串常量的形式返回给客户端 stmt.result setgen.ensure_set( irast.StringConstant(valuetext, typerefct), ctxictx, )从这段代码可以得出几个关键结论全库 Schema 描述支持两种语言DDL通过s_ddl.ddl_text_from_schema与SDL通过s_ddl.sdl_text_from_schema分别对应describe schema as ddl与describe schema as sdl。CLI 的gel describe schema约定使用 SDL。描述文本生成于编译期文本是基于编译上下文ctx.env.schema中已解析的 Schema 对象实时生成的而非查询数据库返回的原始元数据。返回类型是字符串常量最终以std::str类型的StringConstant作为查询结果这与文档中输出类型为 str但不能作为查询表达式的描述一致。非法组合会被拒绝例如对全库 Schema 使用as textDescribeLanguage.Text时会抛出QueryErrorcannot describe full schema as ...。此外同类命令describe config数据库配置、实例配置与describe roles角色也在这同一函数中处理stmt.py L894-L920分别通过config_desc.compile_describe_config与内置函数sys._describe_roles_as_ddl实现——这印证了describe是 Gel 内省体系中的统一入口。在测试与工具链中的实际应用describe schema as sdl在 Gel 自身测试基础设施中被广泛使用。例如 edb/testbase/server.py约 L1926中测试框架通过orig_schema await self.con.query_single(describe schema as sdl)在测试执行前后抓取 Schema 快照用于校验 Schema 的等价性/一致性。这为你提供了该命令的另一种典型用途在测试或 CI 中对 Schema 做前后对比确保迁移或运行时变更符合预期。实战场景小结综合文档与源码gel describe schema的高价值使用场景包括数据模型审查快速查看整个库的 SDL 全貌评审模型设计是否合理、命名是否一致迁移准备在编写gel migration create之前用gel describe schema核对当前基线明确即将发生的 Schema 变更版本对比将不同分支/实例的gel describe schema输出分别保存为.sdl文件用 diff 工具定位模型差异测试断言如 Gel 自身测试那样在测试前后抓取 SDL 快照验证操作后 Schema 的一致性参见 edb/testbase/server.py命名冲突审计关注输出中被标注为被屏蔽masked的标准库对象及时处理命名遮蔽。延伸阅读gel describe 命令组索引describe家族全部子命令概览gel describe object描述单个具名 Schema 对象支持--verbose显示注解与约束等额外细节describe 语句参考as ddl/as sdl/as text [verbose]三种格式的完整说明与示例连接选项文档所有连接 flag 的完整清单与解析优先级注解annotations 与 约束constraintsverbose模式下额外展示的 Schema 细节的数据模型定义。【免费下载链接】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），仅供参考