Gel（edgedb）Python 客户端连接数据库实战：create_async_client 与 EdgeQL 查询入门

数据库图数据库关系型数据库【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址https://gitcode.com/gh_mirrors/ed/edgedb点击查看免费下载本篇技术指南以 Gel 快速上手Quickstart系列中Connecting to the database一节对应仓库 docs/intro/quickstart/connecting/fastapi.rst为核心讲解如何在 FastAPI 应用中通过gelPython 客户端库连接本地 Gel 实例、执行 EdgeQL 字符串查询、插入与回读Deck数据并完成清理。读完本文你将掌握create_async_client()的零配置连接原理、query/query_single等核心 API 的语义差异以及本地开发与生产部署两种场景下的连接解析机制。前置环境确保你已完成项目初始化本文的所有示例都假设你已经按照 FastAPI 快速上手的 setup 章节 完成了环境准备克隆quickstart-fastapi模板、创建虚拟环境、安装依赖并执行了uvx gel project init。这一步会在项目根目录生成一个与本机 Gel 实例绑定的项目链接同时创建gel.toml与dbschema/目录并在 建模章节 中定义Deck与Card类型。第一步初始化客户端并执行第一条静态查询在深入编写应用逻辑之前先用一个最简脚本验证数据库连接。新建./test.pyimport gel import asyncio async def main(): client gel.create_async_client() result await client.query_single(select Hello from Gel!;) print(result) asyncio.run(main())运行$ python test.py Hello from Gel!为什么不用传任何连接参数请注意create_async_client函数并没有接收任何连接详情。这正是 Gel Python 客户端与其他数据库驱动在体验上的关键差异你不需要自己设计一套拼连接串、管理凭据的方案也无需担心把凭据泄露进代码。连接信息的解析由客户端库统一完成本地开发只要在项目目录内运行过gel project init客户端会自动检测到项目链接连接到该项目绑定的本地 Gel 实例部署环境为进程设置约定的环境变量详见下文客户端同样能自动识别。关于这一连接解析协议docs/intro/clients.rst 有完整说明所有官方客户端库Python、TypeScript、Rust、Go、.NET 等都实现了同一套标准协议用于决定如何连接数据库gel.Client在内部还会维护一个连接池并通过 Gel 高效的二进制协议执行查询。第二步通过 EdgeQL 字符串完成增、查、删在 Python 中我们直接把 EdgeQL 查询写成字符串。这样既能获得 EdgeQL 完整的表达力又可以通过 Gel 严格strict的 schema 保持类型安全——schema 由dbschema/中的类型定义与迁移文件migrations保证查询返回的对象结构与类型由服务端校验。将test.py扩展为先插入两副Deck牌组再把它们全部查询出来并打印id与name最后清空Deck表import gel import asyncio async def main(): client gel.create_async_client() await client.query( insert Deck { name : I am one } ) await client.query( insert Deck { name : I am two } ) decks await client.query( select Deck { id, name } ) for deck in decks: print(fID: {deck.id}, Name: {deck.name}) await client.query(delete Deck) asyncio.run(main())运行结果$ python test.py Hello from Gel! ID: f4cd3e6c-ea75-11ef-83ec-037350ea8a6e, Name: I am one ID: f4cf27ae-ea75-11ef-83ec-3f7b2fceab24, Name: I am two这段代码用到的 API 语义Deck类型正是在 建模章节 中通过 SDL 定义并迁移进数据库的required name: str、multi cards: Card等。上面的代码暴露了 Python 客户端的三个关键方法它们在 Python 客户端参考 中有精确的语义定义方法返回值语义越界行为query始终返回结果列表list对基数cardinality不做任何约束无query_single期望零或一个元素的单例结果T \| None返回多于一个元素时抛出ResultCardinalityMismatchErrorquery_required_single期望恰好一个元素返回空集或多于一个元素时抛出运行时错误例如在第一步中select Hello from Gel!;恒返回一个元素因此适合用query_single直接拿到字符串而在本例中select Deck {...}可能返回任意多行所以用query拿到对象列表再遍历。注意数组和元组被视为结果集中的一个元素所以query_single(select [1, 2, 3];)返回的是list[int64] | None而非报错。此外query系列方法支持$参数注入命名参数以关键字方式传入如await client.query(select 2 $addend;, addend2)位置参数以位置方式传入但同一查询中不能混用两种方式参数仅支持标量或标量数组。连接解析机制深挖projects 与环境变量create_async_client之所以零配置是因为客户端内部按固定优先级解析连接信息docs/intro/clients.rst 的 Connection 一节完整列出了这一协议本地开发项目链接projects在代码库根目录执行gel project init后任何使用官方客户端库的代码都会自动连接到该项目链接的实例——不需要环境变量也不需要硬编码凭据。项目配置本身记录在gel.toml中模板中该文件还带有hooks.schema.update.after uvx gel-py之类的钩子用于在 schema 变更后自动重新生成类型安全的查询代码。生产部署环境变量在非项目目录或生产环境中通过环境变量向客户端传递连接信息Gel Cloud 实例推荐设置GEL_INSTANCE取值为org-name/instance-name与GEL_SECRET_KEY密钥可在 Cloud UI 中创建也可通过gel cloud secretkey create命令生成。自托管远程实例最常用的是GEL_DSN即连接字符串形如username:passwordhostname:port其中每个元素都可省略并拥有默认值host 默认localhost、port 默认5656、user 默认admin、password 默认空。DSN 还可带查询参数例如branch要连接的数据库分支默认main、tls_securitystrict/no_host_verification/insecure默认strict、tls_ca_file指向 CA 根证书的文件路径。拆分式环境变量也可分别设置GEL_HOST、GEL_PORT、GEL_USER、GEL_PASSWORD、GEL_BRANCH、GEL_TLS_CA_FILE、GEL_CLIENT_TLS_SECURITY但一旦设置了GEL_DSN它会覆盖这些拆分变量。其他机制GEL_CREDENTIALS_FILE指向一个包含host、port、user、password、branch、tls_cert_data等字段的 JSON 文件GEL_INSTANCE则仅对本地或 Cloud 实例有效。此外若在项目目录内定义了GEL_DSN等环境变量环境变量优先于项目链接。从源码结构看参见 docs/reference/using/python/client.rstgel.create_async_client()创建的AsyncIOClient实例内部维护一个动态大小的连接池且连接是惰性lazily初始化的——在首次执行查询之前不会真正建立连接。若想在未发起查询时主动触发连接、尽早暴露配置错误可调用await client.ensure_connected()。小结至此你已经走通了 Gel Python 的完整闭环在项目目录内用create_async_client()免配置获得客户端用 EdgeQL 字符串直接完成insert/select/delete操作并通过query与query_single精确控制返回结果的基数语义。接下来可以继续阅读 working 章节 或 Python 客户端 API 参考进一步了解gel库在 FastAPI 路由中如何复用客户端、执行事务与处理类型化结果。赞分享数据库图数据库关系型数据库【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址https://gitcode.com/gh_mirrors/ed/edgedb点击查看免费下载相关推荐猫抓Cat-Catch浏览器媒体资源嗅探的终极解决方案猫抓Cat Catch浏览器媒体资源嗅探的终极解决方案 在现代Web开发和技术应用场景中如何高效捕获和分析浏览器中的媒体资源一直是一个技术挑战。猫抓Cat数据库图数据库关系型数据库EdgeQL 快速实战指南GelEdgeDB查询语言核心语法全解EdgeQL 快速实战指南GelEdgeDB查询语言核心语法全解 EdgeQL 是 Gel本项目仓库为 edgedb 的查询语言被设计为 SQL 的数据库图数据库关系型数据库SpacetimeDB 接入 PostgreSQL Wire Protocol让 psql、Python 与 Rust 客户端直连查询数据库SpacetimeDB 接入 PostgreSQL Wire Protocol让 psql、Python 与 Rust 客户端直连查询数据库 本篇技术指南围绕数据库关系型数据库后端上一篇background-agents事件转发器与Bridge重连设计深度解析下一篇ViGEmBus让Windows游戏手柄兼容性不再是难题的虚拟驱动神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考