数据库图数据库关系型数据库【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址https://gitcode.com/gh_mirrors/ed/edgedb点击查看免费下载本指南基于 Gel原 EdgeDB官方文档《Client Libraries》编写系统讲解官方客户端库的三大核心能力——客户端实例化、连接信息自动解析、查询执行并给出 Node.js、Deno、Python、Rust、Go、.NET、Elixir 七种语言的完整上手示例以及开发/生产环境下连接配置的权威做法项目链接、环境变量、DSN、凭据文件。读完本文你将掌握 Gel 客户端库的统一连接模型能编写不随部署环境变化而变化的数据库访问代码。为什么需要客户端库Gel 为流行编程语言提供了官方客户端库这些库围绕统一的功能集设计让开发者可以更轻松地与 Gel 实例协作。从文档定义看所有官方客户端库都具备以下三块核心能力实例化客户端Instantiating clients大多数库实现了一个Client类它内部维护到 Gel 实例的物理连接池pool of physical connections。你创建的是池的入口而不是单条连接。解析连接Resolving connections所有客户端库都实现了标准协议来决定如何连接到数据库。大多数情况下它会检查DSN等专用环境变量对于 Gel Cloud 实例则检查INSTANCE和SECRET_KEY。详细机制见下文连接章节。执行查询Executing queriesClient提供若干方法向数据库执行查询。底层查询通过 Gel 高效的二进制协议传输。什么情况下可以不用客户端库在某些场景下你并不需要客户端库。Gel 允许直接通过 HTTP 执行查询即edb的 HTTP 查询端点。这种方式比二进制协议慢且不支持事务和丰富的数据类型但当你选择的语言没有可用客户端库时它可能是一个合适的选择。从源码结构看二进制协议在仓库中占有明确位置edb/protocol/目录存放协议文档与测试工具见 edb/protocol/README实际协议实现位于edb/server/protocol/含protocol.pyx、protocol.pyi及 60 相关文件。客户端库正是在这一层之上封装了连接池与查询 API。可用客户端库要在应用代码中执行查询请使用 Gel 的官方客户端库之一完整索引见 Client philosophy即文档中的 Client Libraries 参考章节。官方库覆盖 JavaScript/TypeScript、Python、Rust、Go、.NETC#以及 Elixir 等主流语言。客户端库相比传统数据库驱动更高层参考文档 Client philosophy 总结了三个设计目标连接很容易Connecting is easy不需要手工拼接 DSN 传给驱动客户端库通过约定自动发现连接信息代码不随运行环境改变。事务健壮Transactions are robust所有查询默认在隐式事务中执行使用最安全的SERIALIZABLE隔离级别对于可重试的事务错误如序列化冲突客户端库会自动重试无需应用层处理。多客户端实例共享单一连接池Many client instances, single connection pool创建连接池开销较大因此可以创建一个主客户端再派生多个轻量实例共享同一个池每个派生实例可配置不同的全局变量、查询超时、访问策略开关等。快速上手七种语言的 Hello World下面按官方文档的步骤从零初始化一个项目并在各语言中执行第一条查询select random()使用 EdgeQL 内置的 random 函数返回值打印到控制台。1. 创建项目并初始化先新建目录并初始化 Gel 项目$ mydir myproject $ cd myproject $ gel project initgel project init会做三件事启动一个新的本地实例、创建标记项目身份的gel.toml配置文件、创建包含默认 schema 的dbschema目录并应用已有迁移。更详细的说明可参考 Projects项目 文档与 gel project init 命令参考。2. 配置各语言环境# Node.js $ npm init -y $ tsc --init # (TypeScript only) $ touch index.ts # Deno $ touch index.ts # Python $ python -m venv venv $ source venv/bin/activate $ touch main.py # Rust $ cargo init # Go $ go mod init example/quickstart $ touch hello.go # .NET $ dotnet new console -o . -f net6.03. 安装客户端库# Node.js $ npm install gel # npm $ yarn add gel # yarn # Python $ pip install gel # Rust编辑 Cargo.toml # [dependencies] # gel-tokio 0.5.0 # tokio { version 1.28.1, features [macros, rt-multi-thread] } # Go $ go get github.com/geldata/gel-go # .NET $ dotnet add package Gel.Net.DriverDeno 无需安装包n/aGel 官方文档针对 Deno 环境直接使用 TypeScript 脚本配合--unstable标志运行。4. 编写示例脚本复制以下脚本。注意创建客户端时没有传入任何连接信息如连接 URL。客户端库能自动检测到自己位于项目目录内并连接项目所链接的实例。关于连接配置的细节见下文连接章节。// Node.js import {createClient} from gel; const client createClient(); client.querySingle(select random()).then((result) { console.log(result); });# Python from gel import create_client client create_client() result client.query_single(select random()) print(result)// Rust — src/main.rs #[tokio::main] async fn main() { let conn gel_tokio::create_client() .await .expect(Client initiation); let val conn .query_required_single::f64, _(select random(), ()) .await .expect(Returning value); println!(Result: {}, val); }// Go — hello.go package main import ( context fmt log github.com/geldata/gel-go ) func main() { ctx : context.Background() client, err : gel.CreateClient(ctx, gel.Options{}) if err ! nil { log.Fatal(err) } defer client.Close() var result float64 err client. QuerySingle(ctx, select random();, result) if err ! nil { log.Fatal(err) } fmt.Println(result) }// .NET using Gel; var client new GelClient(); var result await client.QuerySingleAsyncdouble(select random();); Console.WriteLine(result);# Elixir — lib/gel_quickstart.ex defmodule GelQuickstart do def run do {:ok, client} Gel.start_link() result Gel.query_single!(client, select random()) IO.inspect(result) end end5. 运行脚本# Node.js $ npx tsx index.ts # Deno $ deno run --allow-all --unstable index.deno.ts # Python $ python index.py # Rust $ cargo run # Go $ go run . # .NET $ dotnet run # Elixir $ mix run -e GelQuickstart.run运行后你会在控制台看到一个随机数它是由 Gel 实例内部使用 EdgeQL 内置random函数生成的。连接所有客户端库都实现了标准协议来决定如何连接数据库。连接配置总体上遵循一套统一的解析逻辑与优先级顺序详见 Connection parameters 参考文档。配置的目标是指定某个实例上的某个分支branch以及必要的认证信息同时可附加连接行为选项。使用项目推荐用于开发在开发环境中官方推荐在代码库根目录初始化项目$ gel project init项目初始化后任何使用官方客户端库的代码都会自动连接到项目链接的实例——无需环境变量也无需硬编码凭据。这是因为 CLI 会在本地文件系统存储实例的位置与凭据host、port、user、password 等客户端库会自动查找到这些凭据。具体实操请参考 Using Projects 指南。从 CLI 角度看Connection flags 文档明确了连接解析顺序显式 flag 优先 → 环境变量 → 项目链接目录 → 否则失败。客户端库与 CLI 共享同一套解析逻辑。使用环境变量在生产环境中连接信息通过环境变量安全地传给客户端库。Gel Cloud 实例对于 Gel Cloud 实例推荐设置的变量是INSTANCE和SECRET_KEYINSTANCE设置为org-name/instance-name其中instance-name是创建 Gel Cloud 实例时设置的名字。Cloud 实例名只能包含拉丁字母数字与连字符不能以-开头或包含--且组织名 实例名总长度须小于 62 字符。SECRET_KEY如果尚未创建密钥可以在 Gel Cloud Web UI 中创建或通过 CLI 的cloud secretkey create命令创建。自托管实例对于自托管的远程实例最常用的是设置DSN环境变量。注意如果在项目目录内同时定义了DSN等环境变量环境变量优先于项目链接。DSN数据源名称 / 连接字符串DSN 即连接字符串形如username:passwordhostname:port完整形式为gel://user:passwordhost:port/branch。DSN 的每个元素都是可选的事实上gel://本身就是一个合法的 DSN。未指定的元素使用以下默认值元素默认值hostlocalhostport5656useradminpasswordnull未设置一个典型的 DSN 形如admin:PASSWORDdb.domain.com:8080。DSN 查询参数DSN 还可以携带以下查询参数使用 Web 标准查询字符串写法如user:passexample.com:8080?branchmy_branchtls_securityinsecure参数说明branch要连接的数据库分支。默认为main。tls_securityTLS 安全模式可选值strict默认验证证书与主机名、no_host_verification仅验证证书、insecure信任自签名证书。tls_ca_fileCA 根证书的文件系统路径。通常仅当通过 TLS 连接使用自签名证书的远程实例时需要。DSN 还支持三种参数变体以满足高级场景详见 Connection parametersPlain params直接内联如gel://hostname.com:1234?tls_securityinsecure。注意同一设置不能在 DSN 主体与查询参数中重复指定如hostname.com:1234?port5678是非法 DSN。File params用tls_security_file./tls_security.txt指定指向 UTF-8 单行值文件的路径。Environment params用tls_security_envMY_TLS_SECURITY指定另一个环境变量的名字非 shell 变量替换运行时读取该变量的值未设置则报错。完整的 DSN 规范见 DSN Specification。使用多个环境变量如果部署流水线需要DSN 的每个元素也可以独立指定HOSTPORTUSERPASSWORDBRANCHTLS_CA_FILECLIENT_TLS_SECURITY注意一旦定义了DSN它将覆盖上述所有变量关于覆盖行为的细节Connection parameters 说明覆盖只能发生在同一优先级或更低优先级内。例如PASSWORD环境变量可以覆盖DSN中的密码但若通过--dsnflag 显式传入 DSN则必须显式传入--password qwerty才能覆盖同理PASSWORD也会覆盖项目链接实例存储的密码这通常是不希望的。其他连接机制CREDENTIALS_FILE指向包含连接信息的.json文件的路径。在某些场景包括本地 Docker 开发下用文件表达连接信息很方便。示例{ host: localhost, port: 10700, user: testuser, password: testpassword, branch: main, tls_cert_data: -----BEGIN CERTIFICATE-----\nabcdef... }安全警告不要把这类凭据文件提交进版本控制这会带来安全风险。INSTANCE仅本地 / Gel Cloud 实例 实例的名称。仅对本地实例或 Gel Cloud 实例有用Cloud 场景见上文Gel Cloud 实例小节。连接配置的优先级从高到低连接配置的解析顺序为详见 Connection parameters 的 Priority levels 章节显式连接参数最高客户端库中显式传给创建函数的选项如 JS 的createClient({instance: my_instance})CLI 中则是命令行 flag如gel --instance my_instance。出于安全考虑不推荐在代码库中硬编码凭据但对调试/测试有用。环境变量推荐用于生产DSN、INSTANCE、CREDENTIALS_FILE、HOST/PORT等。定义后客户端无需任何额外信息即可连接。注意不允许歧义——同时指定INSTANCE和DSN会报错但HOST与PORT可以同时使用。项目链接凭据推荐用于开发运行过gel project init后在项目目录内客户端无需任何 flag 或参数即可自动连接。若以上机制都无法解析出连接信息则连接失败。参数参考Gel 支持的其他高级连接选项还包括SECRET_KEYCloud 认证、TLS_SERVER_NAMESNI 覆盖、CLIENT_SECURITY安全预设目前仅insecure_dev_mode等价于将tls_security设为insecure常用于本地 Docker 开发、WAIT_UNTIL_AVAILABLE连接失败时重试至超时默认10s支持1hr/10min/30sec/500ms或 ISO 8601 如PT1H等格式、CONNECT_TIMEOUT连接超时默认10s。每个参数都有对应的环境变量、CLI flag 与客户端库参数完整清单见 Connection parameters 参数参考。深入客户端库背后的实现印证二进制协议客户端库执行查询走的是 Gel 高效的二进制协议。仓库中 edb/protocol/README 说明协议文档与测试工具位于edb/protocol/实际协议实现位于edb/server/protocol/包含protocol.pyx等 Cython 实现与messages.py、enums.py。这一层负责查询消息的编解码是客户端库执行查询能力的底层支撑。连接池与派生客户端参考文档 Client philosophy 的示意图展示了多个客户端实例共享单一连接池的模型创建主客户端即建立连接池派生实例复用同一池并可独立配置设置全局变量、调整查询超时、禁用访问策略等。这与本指南实例化客户端的核心能力一一对应——Client对象是池的句柄而非单条连接。事务与自动重试所有查询默认在隐式事务中执行隔离级别为SERIALIZABLE保证高并发下结果一致客户端库对特定类别的事务错误如序列化冲突自动重试开发者无需在应用代码中处理。事务重试行为可在各客户端库的配置中定制。小结Gel 客户端库通过连接自动发现 连接池 二进制协议三层设计把连接管理从应用代码中剥离出来开发环境用gel project init项目链接生产环境用INSTANCE/SECRET_KEYCloud或DSN自托管配合统一的优先级解析规则让同一份代码无需条件分支即可在不同环境运行。本文所有示例脚本均可直接复制运行更完整的连接参数与客户端 API 细节可继续查阅 Client philosophy、Connection parameters 与 Connection flags 三份仓库内文档。赞分享数据库图数据库关系型数据库【免费下载链接】edgedbGel supercharges Postgres with a modern data model, graph queries, Auth AI solutions, and much more.项目地址https://gitcode.com/gh_mirrors/ed/edgedb点击查看免费下载相关推荐OPC UA客户端连接指南快速上手技巧OPC UA客户端连接指南快速上手技巧 Workstation.UaClient是一个强大的.NET库支持跨平台开发包括.NET Core、UWP、WPF通信物联网工业制造TDengine 连接指南从客户端安装到多语言连接器接入的完整实战TDengine 连接指南从客户端安装到多语言连接器接入的完整实战 TDengine 作为面向工业物联网IIoT场景的高性能时序数据库为开发者提供了丰富数据库时序数据库大数据物联网云原生DiceDB连接池客户端连接管理优化DiceDB连接池客户端连接管理优化 概述 在高并发数据库应用场景中连接管理是影响系统性能的关键因素。DiceDB作为Redis的Go语言重新实现采用创新数据库缓存后端上一篇如何搭建高效摄像头流媒体系统一站式解决方案指南下一篇Cursor Pro破解工具终极指南3步轻松解除AI编程限制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
