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

本文以本仓库 docs/resources/changelog/index.rst 及其下全部版本变更记录为核心骨架，系统梳理 EdgeDB（后更名为 Gel）从 1.x 到 7.x 的完整演进脉络：从数据模型能力（GROUP、全局变量、访问策略、触发器）、AI 与全文检索集成（ext::ai、fts）、SQL 兼容层，到 RBAC 权限体系等关键里程碑，同时给出本地与托管实例的升级操作流程、各版本破坏性变更与官方弃用策略。读完本文，你将掌握 EdgeDB/Gel 各版本的能力边界、升级前置条件与完整 dump-and-restore 操作命令，并能据此判断项目应从哪个版本起步。

Changelog 文档体系与版本节奏

官方变更记录位于仓库 docs/resources/changelog/ 目录，index.rst通过 toctree 聚合了全部版本文件：

• 1_x.rst（EdgeDB v1，代号 Nova）
• 2_x.rst（EdgeDB v2，代号 Sagittarius）
• 3_x.rst（EdgeDB v3，代号 Betelgeuse）
• 4_x.rst
• 5_x.rst
• 6_x.rst（自此更名为 Gel v6）
• 7_x.rst（Gel v7）
• deprecation.rst（弃用策略）

此外还保留了 1.0 时代的完整预发布历史，包括 1_0_a2.rst 至 1_0_rc5.rst 共 14 个 Alpha/Beta/RC 版本文件。

几个值得注意的全局性变化，贯穿了版本史：

• 产品更名：v1 至 v5 时代产品名为 EdgeDB，CLI 命令为edgedb；从 v6 起更名为Gel，CLI 命令同步改为gel，服务名也从edgedb-server-N变为gel-server-N。
• 发布节奏转变：3.0 正式确立了"每四个月一个版本、每三个版本中有一个长期支持（LTS）版本"的节奏，LTS 版本在首发后继续支持一年半。4.0 起官方明确采用"小而频繁"的短周期迭代，聚焦于每次少量特性。
• 版本代号：v1 (Nova)、v2 (Sagittarius)、v3 (Betelgeuse) 有明确代号；v4 起不再强调代号，直接以版本号指代。

升级路径：本地实例与托管实例

Changelog 中每个大版本都附有标准升级流程，操作高度一致，此处以 v7.0 为例完整展开（早期版本命令前缀为edgedb，v6 起为gel）。

探索新特性：初始化指定版本的项目

预发布版本不会被 CLI 自动推荐，若想体验新版本特性，需要在初始化项目时显式指定版本：

$ gel project init --server-version 7.0

本地实例升级

先确保 CLI 为最新版本（gel cli upgrade），然后在项目目录内执行：

$ gel project upgrade --to-testing

若未使用项目，也可以直接指定实例名：

$ gel instance upgrade -I my_instance

CLI 会先检查你的 schema 能否干净迁移到目标版本；发现问题会直接报告。例如 3.0 曾因多继承祖先顺序校验变化，要求type C extending A, B;改写为与基类声明顺序一致的type C extending B, A;；此时可使用edgedb migration upgrade-check --watch快速排查，或用edgedb migration create --squash压缩历史迁移来修复"迁移过时"类错误。

托管实例升级：dump-and-restore

远程实例官方推荐使用如下四步 dump-and-restore 流程（v7.0 示例）：

1. 核对 PostgreSQL 版本：Gel v7.0 要求 PostgreSQL 14 及以上，低于 14 需先升级 Postgres。

2. 搭建空的 7.0 实例：按部署指南执行。Debian/Ubuntu 添加 Gel 软件源并安装：

   $ echo deb [signed-by=/usr/local/share/keyrings/gel-keyring.gpg] \ https://packages.geldata.com/apt \ $(grep "VERSION_CODENAME=" /etc/os-release | cut -d= -f2) main \ | sudo tee /etc/apt/sources.list.d/gel.list $ sudo apt-get update && sudo apt-get install gel-7

   CentOS/RHEL 使用sudo yum install gel-7；在所需的systemctl命令中，将edgedb-server-6替换为gel-server-7；Docker 部署使用7.0标签。

3. 应用下线并 dump 旧库：

   $ gel dump --dsn <old dsn> --all --format dir my_database.dump/

   该命令将旧库的 schema 与数据整体导出为本地目录，目录名任意。

4. restore 到新实例：

   $ gel restore --all my_database.dump/ --dsn <new dsn>

   restore 完成后，把应用切到新实例的连接地址。官方明确提示：此流程在第 2、3 步之间存在停机时间。若 Postgres 集群同时托管了其他版本的 EdgeDB，引导新实例时应加上--ignore-other-tenants选项。

EdgeDB 1.x：Nova 时代的奠基

EdgeDB 1.0 于2022 年 2 月 10 日发布。1.x 系列以大量编译层、schema 与约束修复为主，其中具有长期影响的变化包括：

• 1.2 引入 on-demand 编译器池扩缩容：通过--compiler-pool-mode=on_demand开启；当编译请求持续排队时，每 3 秒派生一个新的编译器 worker 进程，上限为 CPU 核数；空闲 60 秒后回缩到--compiler-pool-size（on-demand 模式默认 1）。该机制直接奠定了后续高并发 EdgeQL 编译调度的基础。
• 1.2 增加reset on target delete（DDL 层），修复链接相关的迁移缺陷；并开始强制对新创建的exclusive约束在存量数据上生效。
• 1.3 / 1.4主要修复基数推断（cardinality inference）、tuple 乘数计算、JSON 转换、IN array_unpack大整数等编译正确性问题，并强制要求索引表达式不可变（immutable）。

EdgeDB 2.x：Sagittarius 的功能爆发

v2.0 于2022 年 7 月 28 日发布，是本项目功能密度最高的版本之一，多项能力沿用至今。

集成式 Admin UI

所有 v2 实例内置管理 GUI，在项目内执行edgedb ui（或edgedb ui -I my_inst指定实例）即可用默认浏览器打开，包含数据浏览器/编辑器、EdgeQL REPL、以及基于文本与图形两种形式的 schema 可视化工具。

GROUP分析查询

新增GROUP表达式用于分区与聚合，输出为自由对象（free objects），包含分组key、grouping与elements：

group Movie { title } by .release_year;

全局变量与对象级安全

schema 中可声明全局变量，客户端在连接上附带其值，查询与 schema 均可引用：

global current_user -> uuid;

select User filter .id = global current_user;

TypeScript 与 Python 客户端分别通过client.withGlobals({...})与client.with_globals({...})绑定全局变量。全局变量的主要用途正是支撑对象级安全：对象类型可挂载access policy，将授权逻辑下推到数据库内部，例如"仅允许作者访问自己的博文"：

type BlogPost { required property title -> str; link author -> User; access policy own_posts allow all using ( .author.id ?= global current_user ) }

其他数据能力

• Range 类型：range(1, 10)、range_unpack(range(1, 10))等，用于表示值区间。
• cal::date_duration：表示"月/天"跨度，不能表示亚天精度，主要简化cal::local_date运算，如'2022-06-25' + '5 days'。
• 源删除策略：on source delete delete target实现级联删除，追加if orphan可避免误删仍被其他实体引用的对象。
• 协议 1.0：消除非事务连接上的全部服务端状态，并支持多语句脚本的参数传递。
• edgedb+http：用 JWT 认证在 HTTP 上隧道二进制协议，且本地实例也支持 JWT 认证。

2.x 的后续小版本（2.1～2.16）密集修复访问策略与 DML、自由形状、UNLESS CONFLICT、迁移重写等交互问题；2.14 引入升级时 schema 修复机制（自动修正旧版本中错误推断并持久化的字段），官方特别提醒升级前先 dump。

EdgeDB 3.x：Betelgeuse 的开发体验革命

v3.0 于2023 年 6 月 22 日发布，重心是开发者体验与数据库内自动化。

简化 SDL 语法

非计算属性/链接不再强制property/link关键字，箭头改为冒号。以下写法在 3+ 中等价：

type User { required property email -> str; multi link friends -> User; }

type User { required email: str; multi friends: User; }

旧箭头语法仍完全支持。

edgedb watch原型开发工作流

gel watch会常驻监控项目dbschema目录下的 schema 文件，保存即实时应用到数据库：

1. 启动$ gel watch；
2. 在default.esdl中编写初始 schema，保存后自动应用；
3. 随应用演进直接编辑 schema 文件，保存即同步；
4. 原型确定后执行edgedb migration create生成迁移并"锁定"变更，提交到版本库与团队共享。

Triggers 与 Mutation Rewrites

• 触发器：在指定对象类型上定义表达式，原查询执行时在同一事务内自动触发：

  type Person { required name: str; trigger log_insert after insert for each do ( insert Log { action := 'insert', target_name := __new__.name } ); }

• 变更重写（mutation rewrites）：触发器无法修改触发它的对象本身，rewrite 则专门解决此问题，典型场景是维护修改时间戳：

  type Post { required title: str; required body: str; modified: datetime { rewrite insert, update using (datetime_of_statement()) } }

Splats 与集合运算

• Splat：select Movie {*}一键选取全部属性，select Movie {**}双 splat 还包含一层嵌套链接对象的属性。
• intersect/except：{1,2,3,4,5} intersect {3,4,5,6,7}求交集，except求差集，可作用于对象集合。
• assert函数：可结合触发器构造强约束，例如禁止某人的friends与enemies相交，违反时报出自定义错误 "Invalid frenemies"。

ext::pgvector与 SQL 只读支持

• ext::pgvector扩展用于高效存取向量（如文本嵌入），支持ext::pgvector::ivfflat_cosine(lists := 100)索引与vec::cosine_distance()距离函数。

• SQL 只读支持：任何 Postgres 兼容客户端可用与 EdgeDB 协议相同的端口、库名、账号密码直连：

  $ psql -h localhost -p 10701 -U edgedb -d edgedb

  官方已与pg_dump、Metabase、Tableau、DataGrip、dbt 等工具做过兼容性测试。

更多 3.0 特性与发布节奏调整

• 嵌套模块：module momma_module { module baby_module { ... } }，引用形式momma_module::baby_module::<entity-name>。
• 抽象索引：经pg模块暴露pg::hash、pg::btree、pg::gin、pg::gist、pg::spgist、pg::brin等 Postgres 索引类型。
• CLI 增强：新增edgedb migration upgrade-check、edgedb migration create --squash、edgedb migration edit、edgedb info --get <key>等命令。
• 全文检索（FTS）未随 3.0 发布，官方将其单独推迟，随后转入每四个月一版的短周期节奏。

EdgeDB 4.x：短周期迭代与扩展生态

v4.0 起采用更短的发布周期，每次聚焦少量特性。

全文检索fts模块

通过在对象类型上挂fts::index将其变为可检索文档：

type Item { required available: bool { default := false; }; required name: str; required description: str; index fts::index on ( fts::with_options(.name, language := fts::Language.eng) ); }

fts::search返回"对象 + 分数"元组，可据此排序：

with res := ( select fts::search(Item, 'candy corn', language := 'eng') ) select res.object {name, score := res.score} order by res.score desc;

一个类型至多一个fts::index，多个可检索字段须并列写在同一索引内。从本仓库源码 edb/lib/fts.edgeql 可见std::fts::Language枚举（含ara、eng、spa、tur等 ISO 639-3 语言标识）与std::fts::Weight权重的标准库实现。

其他 4.0 亮点

• Multirange：由若干 range 组成、自动归一化为无重叠有序区间，如multirange([range(8, 10)]) + range(1, 5) - range(3, 4)。
• HTTP/GraphQL 认证：EdgeQL over HTTP 与 GraphQL 端点默认要求认证（HTTP Basic），属于向后不兼容变更。
• auth扩展：内置认证服务，支持 GitHub/Google/Apple/Azure OAuth 与邮箱密码登录，提供托管认证 UI；登录成功创建ext::auth::Identity对象，token 可写入全局ext::auth::client_token，进而填充计算全局ext::auth::ClientTokenIdentity供访问策略直接使用。
• ext::pgcrypto：暴露digest、hmac、gen_salt、crypt（支持 md5/sha1/sha224/sha256/sha384/sha512 及 OpenSSL 任意摘要算法）。
• ext::pg_trgm：提供word_similarity等字符串相似度函数。
• 性能：将 EdgeQL 解析器用 Rust 重写，基准服务器内存占用降低约 40%。

EdgeDB 5.x：AI 集成与数据库分支

ext::ai扩展

v5.0 引入ext::ai，对接 OpenAI、Mistral、Anthropic 等 AI 后端。仓库源码 edb/lib/ext/ai.edgeql 中定义了抽象索引ext::ai::index，用于把对象的检索委托给特定 AI 搜索提供方；配套函数ext::ai::to_context(object: anyobject)求值该索引表达式并返回上下文，ext::ai::search(object, query: array<float32>)按语义向量执行检索。同时提供两个 HTTP 端点：/ai/embeddings与/ai/rag。

数据库分支（branches）

v5.0 用语义更清晰的术语branch取代database，旧create database/drop database标记为弃用，新命令家族包括：

• create empty branch <newbranch>：空 schema 新分支（等价旧 create database）；
• create schema branch <newbranch> from <oldbranch>：仅复制 schema；
• create data branch <newbranch> from <oldbranch>：连同数据一起复制；
• drop branch <oldbranch>、alter branch <oldname> rename to <newname>。

其设计意图是让数据库分支与引入 schema 变更的代码分支一一对应，配合 CLI 的 branch 命令完成克隆、复制、重命名、丢弃与 rebase，从而在合并代码前把特性分支数据库"快进"到主分支状态。

认证与向量检索增强

• pgvector新增 HNSW 索引三件套：ext::pgvector::hnsw_euclidean、hnsw_ip、hnsw_cosine；IVFFlat 的probes与 HNSW 的ef_search改由ext::pgvector::Config对象配置，用configure session set / reset ext::pgvector::Config::probes调整。
• auth扩展新增 WebAuthn（Passkeys）与邮箱 Magic Link 两类"无密码"认证，并支持 Slack、Discord 两家 OAuth 提供方。
• 编译缓存持久化到重启之后，迁移后自动重编译。

Gel 6.x：更名与 SQL 写入能力

v6.0 起产品更名为Gel，是本项目从"EdgeDB"走向新品牌的分水岭，同时迎来一批面向存量 SQL 生态的关键能力。

• SQL 写入支持：通过 PostgreSQL 协议连接时，可直接使用 SQL DML（insert、update、delete），目标覆盖 SQL ORM 与 SQL 客户端的大部分典型用法；窗口函数、递归查询、显式锁等暂不支持。存量 SQL 代码可平滑迁入后再渐进采用 EdgeQL。
• 就地升级（in-place upgrade）方向：官方目标是把 v6 做成最后一个必须 dump-and-restore 的大版本。
• 查询性能可观测性：sys::QueryStats记录每条查询的计划/执行统计（如plans、total_plan_time、calls、mean_exec_time），可结合sys::get_current_branch()按分支过滤。
• ext::postgis：接入 PostgreSQL 地理空间扩展，支持地理对象与空间数据类型。
• std::net：新增标准库网络请求模块（首批支持 HTTP），异步调度请求并轮询响应。
• ext::auth增强：支持通用 OpenID Connect 提供方、接收并校验id_token、用 webhook 替代/补充 SMTP 处理认证生命周期事件、跨设备免 PKCE 邮箱验证并返回identity_id；同时将 SMTP 配置迁移到顶层cfg::SMTPProviderConfig对象（破坏性变更）。
• 简化 scoping 规则：移除路径因子分解（path factoring），6.0 新建 schema 默认采用新规则，存量 schema 继续使用旧规则并在触发旧行为时告警。
• Command Hooks 与 File Watchers：gel.toml中[hooks] schema.update.after="scripts/extract_schema_docs.sh"可在 schema 变更后自动执行脚本；[[watch]] files = ["queries/*.edgeql"] script = "npx @edgedb/generate queries"配合gel watch监控文件变化（旧版 watch 语义改为gel watch --migrate）。
• EdgeQL 细节：自由对象不再自带id（破坏性变更）、新增__default__关键字引用默认值、字符串插值\(expr)、update/delete支持类型交集、用户自定义函数中允许 DML（引入Modifying波动等级）、sys::Database更名为sys::Branch、默认角色由edgedb改为admin等。

Gel 7.x：RBAC 与一次性代码认证

细粒度 RBAC 权限体系

v7.0 引入基于角色的访问控制：可创建非 SUPERUSER角色并授予有限权限，默认采取"安全优先"的收紧策略：

CREATE ROLE my_role { # ... SET permissions := { sys::perm::data_modifiction, sys::perm::query_stats, cfg::perm::configure_timeouts, cfg::perm::configure_apply_access_policies, ext::auth::perm::auth_read, ext::auth::perm::auth_write, }; };

上述角色可执行 DDL、查看查询统计、配置超时与访问策略开关、读写 auth 扩展表。仓库源码 edb/schema/roles.py 中实现了permissions与apply_access_policies_pg_defaultschema 字段及其校验逻辑，其中sys::perm::superuser仅授予超级用户。相关配套还有：sys::data_modification（非超级用户运行 DML 的权限）、sys::current_role全局变量、Role 上的branches字段（限定角色可访问的分支）、函数required_permissions、以及 dump/restore/ADMINISTER/DESCRIBE/ANALYZE 等操作的权限限制。

一次性代码（One-Time Code）认证

ext::auth新增基于一次性数字码的认证流程，作为邮箱链接的替代，解决"桌面发起、手机收邮件"的跨设备 PKCE 会话不匹配问题：码生成与 PKCE 解耦，验证阶段再创建/复用 PKCE 会话；验证码被安全哈希存储、带限流保护、10 分钟自动过期。默认verification_method仍为Link以保证兼容：

configure current branch insert ext::auth::MagicLinkProviderConfig { verification_method := ext::auth::VerificationMethod.Code, };

同一属性也适用于EmailPasswordProviderConfig与WebAuthnProviderConfig。

SQL 适配器与 HTTP 会话配置

• SQL 适配器访问策略默认开启：apply_access_policies_pg默认值由false改为true，即 SQL 连接上默认应用 EdgeQL 访问策略；为兼容无法执行配置命令的第三方工具，新增 Role 字段apply_access_policies_pg_default可将其置为false。
• 会话配置：GraphQL 与 EdgeQL HTTP 接口现在支持传入会话配置变量；若此前依赖"HTTP/GraphQL 端点用户无法改配置"，应改为只授予无法修改敏感配置的角色。

7.x 其他与 7.1

• 其他特性包括：required link properties、sys::approximate_count()、指针splat_strategy限定符、GraphQL over 二进制协议、math::exp/math::e、FOR OPTIONAL、.?>链接解引用运算符、可配置查询缓存大小、Discord OAuthprompt参数、并发创建索引等。
• 7.0 在创建迁移时会警告 schema 未含using simple_scoping;或using warn_old_scoping;（旧 scoping 原计划 8.0 移除）；7.1直接移除了该弃用警告。

弃用策略与兼容性承诺

deprecation.rst 明确官方的长期兼容性承诺，共三条：

• 继续对前一个主版本提供严重 bug 修复支持；
• 客户端绑定（client bindings）支持当前与上一个主版本；
• CLI 支持从版本 1 起的所有版本。

结合版本史中的具体实践：3.0 弃用 pre-1.0 二进制协议并预告 4.0 完全移除；5.0 弃用create database/drop database命令；6.0 更名 Gel 并将sys::Database更名为sys::Branch，默认角色由edgedb改为admin。这些都是升级到新版本前需要排查的破坏性变化点。

在本仓库中继续深入

• 版本原始记录：完整阅读每个版本的细节可进入 docs/resources/changelog/ 目录，其中 1.0 的 Alpha/Beta/RC 历史（1_0_a2.rst 至 1_0_rc5.rst）记录了最早的协议与数据模型决策。
• 功能文档：各版本提及的功能在 docs/reference/ 下有对应参考文档，如 datamodel 的访问策略（access_policies.rst）、触发器（triggers.rst）、扩展（extensions.rst），以及 stdlib 的 fts.rst、range.rst、net.rst 等。
• 源码印证：fts模块的语言枚举见 edb/lib/fts.edgeql；AI 扩展的索引与检索函数见 edb/lib/ext/ai.edgeql；RBAC 的权限字段与校验逻辑见 edb/schema/roles.py；扩展清单位于 edb/lib/ext/ 目录（auth、graphql、notebook、pg_trgm、pg_unaccent、pgcrypto、pgvector、edgeqlhttp 等），可作为"某版本声称的能力在仓库中如何落地"的对照。

综上，从 2022 年 EdgeDB 1.0 到 Gel 7.x，这一版本序列完整记录了数据库引擎层（编译器、协议、存储）、数据建模语言（EdgeQL/SDL）、扩展生态（auth、ai、fts、pgvector、postgis）与运维模型（分支、就地升级、RBAC）的持续演进。无论你是准备从零选型、评估升级路径，还是想理解某个特性的来龙去脉，docs/resources/changelog/index.rst 及其版本文件都是最权威的入口。

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