effect/sql-pg 全解析基于 Effect 的 PostgreSQL 客户端架构与演进史【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本文以effect/sql-pg的官方变更日志.repos/effect-smol/packages/sql/pg/CHANGELOG.md为骨架结合其源码PgClient.ts、PgProtocol.ts、PgTypes.ts、PgAuth.ts、PgMigrator.ts系统梳理这个把 PostgreSQL 接入 Effect 类型化错误体系、依赖注入与资源管理模型中的官方 SQL 客户端你将掌握它的连接池与单客户端构造方式、完整配置项、LISTEN/NOTIFY 与 JSON 片段等 PostgreSQL 专属能力、SQLSTATE 到类型化错误的分类映射以及 v4 新增的低层协议protocol 3.0、二进制类型编解码与 MD5/SCRAM-SHA-256 认证实现并能从源码级理解每一次关键变更背后的设计动机。一、包定位一个「Effect SQL 驱动的 PostgreSQL 客户端」effect/sql-pg是 Effect 生态中面向 PostgreSQL 的官方 SQL 客户端包。它的定位在 README 中一句话说得很清楚built on thepglibrary即运行时底层复用 Node.js 生态最成熟的pg驱动而上层完全以 Effect 的模型Effect、Layer、Scope、Stream、Config、Redacted重新组织连接、查询、事务与流式读取。对应地package.json把pg、pg-pool、pg-cursor、pg-connection-string、pg-types列为运行时依赖而effect是唯一的 peerDependency。安装方式来自 READMEnpm install effectrc effect/sql-pgrc包名从 changelog 中可以读出清晰的版本脉络0.1.0随 Effect 3.0 一同发布随后沿0.x推进在 4.0.0 大版本上以4.0.0-beta.Nbeta与4.0.0-rc.N候选两条线演进最新的4.0.0-rc.112与effect4.0.0-rc.112同步发布。模块导出采用扁平结构见 index.ts依次暴露PgClient、PgProtocol、PgTypes、PgAuth、PgMigrator五个命名空间。版本历史中值得注意的一个节点0.2.0起effect/sql变得「dialect agnostic」所有客户端实现共享同一个Context.Tag因此你可以编写同时支持多种 SQL 方言的服务仅在需要实现特有功能时如 PostgreSQL 的LISTEN/NOTIFY才从本包取专用 Tag。二、核心服务PgClient接口、配置与构造方式2.1 服务接口源码中PgClient接口PgClient.ts在通用SqlClient之上追加了 PostgreSQL 专属成员export interface PgClient extends Client.SqlClient { readonly [TypeId]: TypeId readonly config: PgClientConfig readonly json: (_: unknown) Fragment // 构造 JSON 参数片段 readonly listen: (channel: string) Stream.Streamstring, SqlError readonly notify: (channel: string, payload: string) Effect.Effectvoid, SqlError }json把任意值包装成 JSON 参数片段由编译器生成$N占位符并序列化listen/notify基于 PostgreSQL 的 LISTEN/NOTIFY 机制实现通道订阅与消息推送见第五节。2.2 配置项全表PgClientConfigPgClient.ts与PgPoolConfig同文件 L135-L141是两个核心配置模型其字段如下配置项所属类型说明urlClientRedacted.Redacted连接串connection string运行时经Redacted.value取出使用host/port/pathClientstring/number/string连接地址path对应 unix socket 场景sslClientboolean \| ConnectionOptionsTLS 开关或完整tls.ConnectionOptions0.14.1 起支持传入 TLS 选项对象database/username/passwordClientstring/string/Redacted.Redacted认证凭据密码用Redacted包装避免意外泄漏connectTimeoutClientDuration.Input连接超时默认 5 秒见 0.24.3 变更streamClient() Duplex自定义网络流0.6.3 新增applicationNameClientstring映射为connection.application_name0.6.3 新增默认effect/sql-pgspanAttributesClientRecordstring, unknown附加到观测 span 的属性0.3.1 起可传入transformResultNames/transformQueryNamesClient(str: string) string结果列名 / SQL 标识符的命名变换函数transformJsonClientboolean是否对 JSON 参数应用命名变换默认truetypesClientPg.CustomTypesConfigpg自定义类型解析器配置0.1.17 新增idleTimeoutPoolDuration.Input池中空闲连接回收时间maxConnections/minConnectionsPoolnumber连接池上/下限connectionTTLPoolDuration.Input连接最大存活时长maxLifetimeSeconds这些字段在make连接池路径与makeClient单客户端路径中会逐一映射为pg.Pool/pg.Client的原生配置例如connectTimeout经Duration.toMillis转成connectionTimeoutMillisconnectionTTL经Duration.toSeconds转成maxLifetimeSeconds。2.3 五种构造方式与 LayerPgClient提供了一组从易到难、可组合的构造器PgClient.ts构造器底层形态说明make(options: PgPoolConfig)pg.Pool托管连接池最常用构造时先执行SELECT 1探活makeClient(options)pg.Client单个托管客户端可选acquireForStream让流式/订阅操作使用独立连接fromPool({ acquire })外部pg.Pool由你提供的池构建客户端派生事务、流式与 LISTEN/NOTIFY 支持fromClient({ acquire, acquireForStream })外部pg.Client由你提供的客户端构建用信号量串行化共享访问makeWith(...)自定义连接获取器完全自定义的 acquirer / transactionAcquirer / listenAcquirer对应地有三个 Layerlayer(config)接收裸配置对象0.19.0 起采用layer/layerConfig命名约定layer直接收裸对象layerConfig(config: Config.WrapPgPoolConfig)接收Config.Config便于从环境变量等来源读取配置layerFrom(acquire)从任意的PgClient获取 Effect 构建 Layer。三者都会同时提供PgClient与通用SqlClient两个服务标签。layerConfig的失败通道是Config.ConfigError | SqlErrorlayer则是SqlError。2.4 连接生命周期与健壮性细节从 changelog 与源码对照连接管理经历了多轮打磨0.15.2「把连接测试纳入客户端构造」make在 acquire 阶段执行SELECT 1若失败则分类为SqlErrorreason 为connect并用Effect.timeoutOrElse兜底超时默认 5 秒0.24.3 起connectTimeout可配置beta.99「修复PgClient.makeClient的连接时序」单客户端路径在资源获取阶段即调用client.connect()确保拿到手的就是已连接对象beta.106「防止makeClient连接期间的未处理 error 事件」源码中通过client.on(error, onError)提前挂接空处理器onError() {}避免pg客户端在无人监听 error 时把异常抛向全局释放时再off(error, onError)关闭兜底pool/client 的关闭操作都套了Effect.timeoutOption(1000)防止资源释放被卡死。三、语句编译、类型化错误与 SQLSTATE 分类3.1 编译器$N占位符与 PostgreSQL 方言makeCompilerPgClient.ts构建方言编译器占位符统一为 PostgreSQL 的$N形式标识符用双引号转义defaultEscape(\)INSERT ... ON CONFLICT与RETURNING子句按 PostgreSQL 语法生成onCustom分支处理PgJson自定义片段——这正是sql.json(value)的底层实现。3.2 reason-based 错误模型0.37.0 将SqlError重构为「reason-based」结构所有 SQL 驱动把数据库原生失败归类为结构化 reason拿不到原生错误码时回退Unknown。在effect/sql-pg中这个映射由classifyErrorPgClient.ts基于 PostgreSQL 的 SQLSTATE 代码完成SQLSTATE 前缀/值分类结果reason08*ConnectionError连接失败28*AuthenticationError认证失败42501AuthorizationError权限不足42*SqlSyntaxError语法错误23505UniqueViolation唯一约束违反见下23*ConstraintError其余约束违反40P01DeadlockError死锁40001SerializationError序列化失败55P03LockTimeoutError锁等待超时57014StatementTimeoutError语句超时其他/无码UnknownError3.3UniqueViolation的细化4.0.0-beta.65 新增UniqueViolation作为独立错误 reason受支持的唯一约束冲突从宽泛的ConstraintError中拆出适用于 PostgreSQL、PGlite、MySQL、MSSQL 以及 SQLite 家族共享的分类。UniqueViolation.constraint字段承载「能拿到的最佳约束/索引/键标识」拿不到可靠标识时精确回退为字符串unknown。源码中pgConstraintFromCausePgClient.ts负责从pg错误对象读取constraint字段并做 trim 归一化。四、LISTEN/NOTIFY订阅式消息通道listen/notify是PgClient最典型的 PostgreSQL 专属能力0.8.2 首次加入其实现历经三次关键改造0.8.2新增listen/notify4.0.0-beta.38notify改用pg_notify($1, $2)函数通道与负载都作为参数传递而非拼接成NOTIFY语句字符串从根上消除了通道名/负载注入 SQL 的隐患。源码印证见 makeWith 的 notify 实现SELECT pg_notify($1, $2)4.0.0-beta.37LISTEN / UNLISTEN订阅改为使用专用 PostgreSQL 客户端而不是占用一个池化连接在整个监听生命周期内——这样订阅不再挤占连接池配额也不会因池连接被回收而中断监听。源码中fromPool通过RcRef懒加载一个独立new Pg.Client(pool.options)作为listenAcquirerPgClient.ts订阅结束的 finalizer 中执行UNLISTEN并移除notification监听器。实际使用形态listen(channel)返回Stream.Streamstring, SqlError你可以在 Effect 程序中订阅并消费notify(channel, payload)是Effectvoid, SqlError。五、事务、流式查询与资源获取5.1 事务期间持有连接许可4.0.0-beta.104 明确「为整个事务生命周期持有共享的 PostgreSQL 客户端许可」。在fromClient路径中可以看到对应实现普通查询经semaphore.withPermit串行化而事务获取使用Effect.uninterruptibleMask先semaphore.take(1)再把semaphore.release(1)注册为 Scope finalizerPgClient.ts——信号量许可伴随整个事务作用域而不是查询结束即释放。5.2 事务连接获取失败保持在错误通道内4.0.0-beta.44 修复PgClient.fromPool的事务连接获取pool.connect回调中的失败统一转换为SqlErrorreason 为acquireConnection保证失败始终落在类型化错误通道而不会以未处理异常的形式泄漏。reserveRawPgClient.ts即此路径的实现它还处理了「回调返回空客户端」「已结束但仍回调」等边界。5.3 流式结果与取消executeStream基于pg-cursor实现每条流式查询先reserve一个连接创建Cursor以 128 行为批次cursor.read推送数据结束时cursor.close()PgClient.ts。与之配套的makeCancel使用pg_cancel_backend(processId)做尽力而为的查询取消带 5 秒超时取消失败不报错。六、v4 新增的低层协议栈PgProtocol / PgTypes / PgAuth4.0.0-rc.112是本包最重要的里程碑之一新增了低层 PostgreSQL 协议、二进制类型编解码与认证 codec对应的三个新模块组成一条完整、自洽的「裸协议栈」6.1PgProtocolprotocol 3.0 的消息编解码PgProtocol.ts负责 protocol 3.0 的编码与增量解析全部为纯函数「bytes in, bytes or plain data out」。关键设计源码顶部注释可印证消息格式1 字节类型 4 字节int32长度长度字段包含自身但不包含类型字节 负载整数大端序字符串为 NUL 结尾的 UTF-8makeParser提供有状态增量解析器push(chunk)返回当前完整的所有消息未凑整的尾部消息保留到后续字节到达默认maxMessageSize为 16 MiBdefaultMaxMessageSize常量解析或字段读取错误是终态错误——parser 抛错后不可复用且当次 push 已解码的消息会被丢弃缓冲池机制已交给调用方的字节永不重写因此DataRow字段可以零拷贝地以view 形式返回每缓冲一次分配而非每列一次分配池上限 64 KiB翻倍增长代价是持有 view 会连带持有整个池缓冲凡是要活得比消息更久的数据必须拷贝启动握手前特殊应答无类型字节的 SSL 响应由decodeSslResponse单独处理不进入通用 parser。6.2PgTypes按 OID 的二进制编解码PgTypes.ts实现二进制线格式format 1的标量与一维数组 codec布局对齐 rust-postgres 的postgres-types包含 infinity 哨兵假设服务端以integer_datetimes构建PostgreSQL 10 起唯一受支持的配置。要点不做类型推断OID 必须显式给出直接传 OID或通过int4这类自带 OID 的构造器错误模型公开 codec 返回类型化Result失败PgTypesCodecError而 parser 的字段读取器走内部抛异常的快路径timestamp在线路上无时区双向均按 UTC 处理解码向零截断亚毫秒精度性能取向用预分配 scratch bufferscratch4/scratch8代替逐字节 DataView 包装用两位数字表避免padStartASCII 字符串编码按 48 字符区分「逐字符循环」与encodeInto两条路径V8 实测交叉点约 50 字符。6.3PgAuthMD5 与 SCRAM-SHA-256PgAuth.ts实现协议认证交换中的 MD5 与 SCRAM-SHA-256均返回类型化ResultPgAuthError。SASL 帧结构属于PgProtocol本模块只负责帧内部的计算createHash/createHmac/pbkdf2Sync XOR。两个明确边界源码注释SCRAM-SHA-256-PLUS通道绑定未实现因为通道绑定需要 TLS socket 而 codec 不持有它密码按 UTF-8 直接使用、不做 SASLprep 归一化因此需要归一化的非 ASCII 密码不受支持。明文认证无需本模块——直接发送PasswordMessage即可。重要澄清rc.112 中PgClient本身保持原样运行时依然走pg新协议栈是独立交付的低层能力供需要自行实现客户端、或希望脱离pg的定制场景使用。七、迁移工具PgMigrator与语句辅助能力4.0.0-beta.8实现PgMigrator同时修复ChildProcess选项类型。PgMigrator.ts复用effect/unstable/sql/Migrator暴露run与layerrun用当前 SQL 客户端执行待应用的迁移文件schema dump 走pg_dump子进程附带--no-owner --no-privileges并通过PGHOST/PGPORT/PGUSER/PGPASSWORD环境变量传连接信息因此run依赖ChildProcessSpawner、FileSystem、Path等服务。4.0.0-beta.86新增Statement.valuesUnprepared——把未预处理的 SQL 语句行以数组形式返回与executeValues的rowMode: array对应见 PgClient.ts。0.1.11新增sql\....unprepared执行不尝试PREPARE的查询并加入 SQL 事务 tracing span、把 span 属性对齐语义约定0.2.9 起改用opentelemetry/semantic-conventions常量0.43.0 又随上游把属性名升级为db.system.name、db.namespace等新一代命名——PgClient.ts中的 span 属性常量ATTR_DB_SYSTEM_NAME db.system.name、ATTR_DB_NAMESPACE db.namespace 正是这一演进的结果。0.1.17PgClientConfig增加prepare与types。八、API 与模块演进的代表性节点从 changelog 可以梳理出几条贯穿始终的设计主线方言无关化0.2.0effect/sql改为方言无关客户端共享同一Context.Tag需要方言特定能力时再用实现包专属 Tag如PgClient或用sql.onDialect({ pg: ... })按方言分支。扁平导入与命名约定0.4.0 扁平化0.19.0layer/layerConfig约定导入路径与构造器命名走向统一规范。模块重命名4.0.0-beta.44ServiceMap模块重命名为Context贯穿导出、文档与测试。入口点精简4.0.0-beta.103移除显式./index入口点。v4 大版本4.0.0-beta.0以v4 beta标记的 Major Changes 开启 4.0 系列随后 beta功能推进→ rc候选发布两个阶段直至4.0.0-rc.112。九、测试与基准验证仓库为上述能力提供了完备的测试与基准支撑见 test/ 与 benchmark/PgProtocol.test.ts/PgTypes.test.ts/PgAuth.test.ts覆盖协议解析、二进制编解码与认证交换fixtures 目录goldens.ts保存黄金样本SqlErrorClassification.test.ts/TransactionAcquire.test.ts验证 SQLSTATE 分类映射与事务连接获取的错误通道Client.integration.test.ts、KeyValueStore.integration.test.ts、Persistence.integration.test.ts等集成测试基于testcontainers/postgresql起真实 PostgreSQL 容器见 package.json 的 devDependencies基准pnpm benchmark:codec运行 benchmark/PgCodec.ts基于 tinybench量化 codec 性能。十、总结effect/sql-pg的演进史本质上是一部「如何在保证类型安全与资源安全的前提下把成熟驱动pg全面纳入 Effect 生态」的工程实践记录从0.1.0的初版连接管理到0.19.0的统一layer约定再到 v4 时代原生协议栈PgProtocol/PgTypes/PgAuth的独立交付。理解这条脉络不仅能帮你正确配置PgClientConfig/PgPoolConfig并合理选用make/makeClient/fromPool等构造路径也能让你在遇到连接超时、唯一约束冲突、LISTEN/NOTIFY 通道行为异常等问题时快速定位到对应的 SQLSTATE 分类逻辑与资源获取实现真正做到「知其然更知其所以然」。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 @effect/sql-pg 全解析：基于 Effect 的 PostgreSQL 客户端架构与演进史
effect/sql-pg 全解析基于 Effect 的 PostgreSQL 客户端架构与演进史【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本文以effect/sql-pg的官方变更日志.repos/effect-smol/packages/sql/pg/CHANGELOG.md为骨架结合其源码PgClient.ts、PgProtocol.ts、PgTypes.ts、PgAuth.ts、PgMigrator.ts系统梳理这个把 PostgreSQL 接入 Effect 类型化错误体系、依赖注入与资源管理模型中的官方 SQL 客户端你将掌握它的连接池与单客户端构造方式、完整配置项、LISTEN/NOTIFY 与 JSON 片段等 PostgreSQL 专属能力、SQLSTATE 到类型化错误的分类映射以及 v4 新增的低层协议protocol 3.0、二进制类型编解码与 MD5/SCRAM-SHA-256 认证实现并能从源码级理解每一次关键变更背后的设计动机。一、包定位一个「Effect SQL 驱动的 PostgreSQL 客户端」effect/sql-pg是 Effect 生态中面向 PostgreSQL 的官方 SQL 客户端包。它的定位在 README 中一句话说得很清楚built on thepglibrary即运行时底层复用 Node.js 生态最成熟的pg驱动而上层完全以 Effect 的模型Effect、Layer、Scope、Stream、Config、Redacted重新组织连接、查询、事务与流式读取。对应地package.json把pg、pg-pool、pg-cursor、pg-connection-string、pg-types列为运行时依赖而effect是唯一的 peerDependency。安装方式来自 READMEnpm install effectrc effect/sql-pgrc包名从 changelog 中可以读出清晰的版本脉络0.1.0随 Effect 3.0 一同发布随后沿0.x推进在 4.0.0 大版本上以4.0.0-beta.Nbeta与4.0.0-rc.N候选两条线演进最新的4.0.0-rc.112与effect4.0.0-rc.112同步发布。模块导出采用扁平结构见 index.ts依次暴露PgClient、PgProtocol、PgTypes、PgAuth、PgMigrator五个命名空间。版本历史中值得注意的一个节点0.2.0起effect/sql变得「dialect agnostic」所有客户端实现共享同一个Context.Tag因此你可以编写同时支持多种 SQL 方言的服务仅在需要实现特有功能时如 PostgreSQL 的LISTEN/NOTIFY才从本包取专用 Tag。二、核心服务PgClient接口、配置与构造方式2.1 服务接口源码中PgClient接口PgClient.ts在通用SqlClient之上追加了 PostgreSQL 专属成员export interface PgClient extends Client.SqlClient { readonly [TypeId]: TypeId readonly config: PgClientConfig readonly json: (_: unknown) Fragment // 构造 JSON 参数片段 readonly listen: (channel: string) Stream.Streamstring, SqlError readonly notify: (channel: string, payload: string) Effect.Effectvoid, SqlError }json把任意值包装成 JSON 参数片段由编译器生成$N占位符并序列化listen/notify基于 PostgreSQL 的 LISTEN/NOTIFY 机制实现通道订阅与消息推送见第五节。2.2 配置项全表PgClientConfigPgClient.ts与PgPoolConfig同文件 L135-L141是两个核心配置模型其字段如下配置项所属类型说明urlClientRedacted.Redacted连接串connection string运行时经Redacted.value取出使用host/port/pathClientstring/number/string连接地址path对应 unix socket 场景sslClientboolean \| ConnectionOptionsTLS 开关或完整tls.ConnectionOptions0.14.1 起支持传入 TLS 选项对象database/username/passwordClientstring/string/Redacted.Redacted认证凭据密码用Redacted包装避免意外泄漏connectTimeoutClientDuration.Input连接超时默认 5 秒见 0.24.3 变更streamClient() Duplex自定义网络流0.6.3 新增applicationNameClientstring映射为connection.application_name0.6.3 新增默认effect/sql-pgspanAttributesClientRecordstring, unknown附加到观测 span 的属性0.3.1 起可传入transformResultNames/transformQueryNamesClient(str: string) string结果列名 / SQL 标识符的命名变换函数transformJsonClientboolean是否对 JSON 参数应用命名变换默认truetypesClientPg.CustomTypesConfigpg自定义类型解析器配置0.1.17 新增idleTimeoutPoolDuration.Input池中空闲连接回收时间maxConnections/minConnectionsPoolnumber连接池上/下限connectionTTLPoolDuration.Input连接最大存活时长maxLifetimeSeconds这些字段在make连接池路径与makeClient单客户端路径中会逐一映射为pg.Pool/pg.Client的原生配置例如connectTimeout经Duration.toMillis转成connectionTimeoutMillisconnectionTTL经Duration.toSeconds转成maxLifetimeSeconds。2.3 五种构造方式与 LayerPgClient提供了一组从易到难、可组合的构造器PgClient.ts构造器底层形态说明make(options: PgPoolConfig)pg.Pool托管连接池最常用构造时先执行SELECT 1探活makeClient(options)pg.Client单个托管客户端可选acquireForStream让流式/订阅操作使用独立连接fromPool({ acquire })外部pg.Pool由你提供的池构建客户端派生事务、流式与 LISTEN/NOTIFY 支持fromClient({ acquire, acquireForStream })外部pg.Client由你提供的客户端构建用信号量串行化共享访问makeWith(...)自定义连接获取器完全自定义的 acquirer / transactionAcquirer / listenAcquirer对应地有三个 Layerlayer(config)接收裸配置对象0.19.0 起采用layer/layerConfig命名约定layer直接收裸对象layerConfig(config: Config.WrapPgPoolConfig)接收Config.Config便于从环境变量等来源读取配置layerFrom(acquire)从任意的PgClient获取 Effect 构建 Layer。三者都会同时提供PgClient与通用SqlClient两个服务标签。layerConfig的失败通道是Config.ConfigError | SqlErrorlayer则是SqlError。2.4 连接生命周期与健壮性细节从 changelog 与源码对照连接管理经历了多轮打磨0.15.2「把连接测试纳入客户端构造」make在 acquire 阶段执行SELECT 1若失败则分类为SqlErrorreason 为connect并用Effect.timeoutOrElse兜底超时默认 5 秒0.24.3 起connectTimeout可配置beta.99「修复PgClient.makeClient的连接时序」单客户端路径在资源获取阶段即调用client.connect()确保拿到手的就是已连接对象beta.106「防止makeClient连接期间的未处理 error 事件」源码中通过client.on(error, onError)提前挂接空处理器onError() {}避免pg客户端在无人监听 error 时把异常抛向全局释放时再off(error, onError)关闭兜底pool/client 的关闭操作都套了Effect.timeoutOption(1000)防止资源释放被卡死。三、语句编译、类型化错误与 SQLSTATE 分类3.1 编译器$N占位符与 PostgreSQL 方言makeCompilerPgClient.ts构建方言编译器占位符统一为 PostgreSQL 的$N形式标识符用双引号转义defaultEscape(\)INSERT ... ON CONFLICT与RETURNING子句按 PostgreSQL 语法生成onCustom分支处理PgJson自定义片段——这正是sql.json(value)的底层实现。3.2 reason-based 错误模型0.37.0 将SqlError重构为「reason-based」结构所有 SQL 驱动把数据库原生失败归类为结构化 reason拿不到原生错误码时回退Unknown。在effect/sql-pg中这个映射由classifyErrorPgClient.ts基于 PostgreSQL 的 SQLSTATE 代码完成SQLSTATE 前缀/值分类结果reason08*ConnectionError连接失败28*AuthenticationError认证失败42501AuthorizationError权限不足42*SqlSyntaxError语法错误23505UniqueViolation唯一约束违反见下23*ConstraintError其余约束违反40P01DeadlockError死锁40001SerializationError序列化失败55P03LockTimeoutError锁等待超时57014StatementTimeoutError语句超时其他/无码UnknownError3.3UniqueViolation的细化4.0.0-beta.65 新增UniqueViolation作为独立错误 reason受支持的唯一约束冲突从宽泛的ConstraintError中拆出适用于 PostgreSQL、PGlite、MySQL、MSSQL 以及 SQLite 家族共享的分类。UniqueViolation.constraint字段承载「能拿到的最佳约束/索引/键标识」拿不到可靠标识时精确回退为字符串unknown。源码中pgConstraintFromCausePgClient.ts负责从pg错误对象读取constraint字段并做 trim 归一化。四、LISTEN/NOTIFY订阅式消息通道listen/notify是PgClient最典型的 PostgreSQL 专属能力0.8.2 首次加入其实现历经三次关键改造0.8.2新增listen/notify4.0.0-beta.38notify改用pg_notify($1, $2)函数通道与负载都作为参数传递而非拼接成NOTIFY语句字符串从根上消除了通道名/负载注入 SQL 的隐患。源码印证见 makeWith 的 notify 实现SELECT pg_notify($1, $2)4.0.0-beta.37LISTEN / UNLISTEN订阅改为使用专用 PostgreSQL 客户端而不是占用一个池化连接在整个监听生命周期内——这样订阅不再挤占连接池配额也不会因池连接被回收而中断监听。源码中fromPool通过RcRef懒加载一个独立new Pg.Client(pool.options)作为listenAcquirerPgClient.ts订阅结束的 finalizer 中执行UNLISTEN并移除notification监听器。实际使用形态listen(channel)返回Stream.Streamstring, SqlError你可以在 Effect 程序中订阅并消费notify(channel, payload)是Effectvoid, SqlError。五、事务、流式查询与资源获取5.1 事务期间持有连接许可4.0.0-beta.104 明确「为整个事务生命周期持有共享的 PostgreSQL 客户端许可」。在fromClient路径中可以看到对应实现普通查询经semaphore.withPermit串行化而事务获取使用Effect.uninterruptibleMask先semaphore.take(1)再把semaphore.release(1)注册为 Scope finalizerPgClient.ts——信号量许可伴随整个事务作用域而不是查询结束即释放。5.2 事务连接获取失败保持在错误通道内4.0.0-beta.44 修复PgClient.fromPool的事务连接获取pool.connect回调中的失败统一转换为SqlErrorreason 为acquireConnection保证失败始终落在类型化错误通道而不会以未处理异常的形式泄漏。reserveRawPgClient.ts即此路径的实现它还处理了「回调返回空客户端」「已结束但仍回调」等边界。5.3 流式结果与取消executeStream基于pg-cursor实现每条流式查询先reserve一个连接创建Cursor以 128 行为批次cursor.read推送数据结束时cursor.close()PgClient.ts。与之配套的makeCancel使用pg_cancel_backend(processId)做尽力而为的查询取消带 5 秒超时取消失败不报错。六、v4 新增的低层协议栈PgProtocol / PgTypes / PgAuth4.0.0-rc.112是本包最重要的里程碑之一新增了低层 PostgreSQL 协议、二进制类型编解码与认证 codec对应的三个新模块组成一条完整、自洽的「裸协议栈」6.1PgProtocolprotocol 3.0 的消息编解码PgProtocol.ts负责 protocol 3.0 的编码与增量解析全部为纯函数「bytes in, bytes or plain data out」。关键设计源码顶部注释可印证消息格式1 字节类型 4 字节int32长度长度字段包含自身但不包含类型字节 负载整数大端序字符串为 NUL 结尾的 UTF-8makeParser提供有状态增量解析器push(chunk)返回当前完整的所有消息未凑整的尾部消息保留到后续字节到达默认maxMessageSize为 16 MiBdefaultMaxMessageSize常量解析或字段读取错误是终态错误——parser 抛错后不可复用且当次 push 已解码的消息会被丢弃缓冲池机制已交给调用方的字节永不重写因此DataRow字段可以零拷贝地以view 形式返回每缓冲一次分配而非每列一次分配池上限 64 KiB翻倍增长代价是持有 view 会连带持有整个池缓冲凡是要活得比消息更久的数据必须拷贝启动握手前特殊应答无类型字节的 SSL 响应由decodeSslResponse单独处理不进入通用 parser。6.2PgTypes按 OID 的二进制编解码PgTypes.ts实现二进制线格式format 1的标量与一维数组 codec布局对齐 rust-postgres 的postgres-types包含 infinity 哨兵假设服务端以integer_datetimes构建PostgreSQL 10 起唯一受支持的配置。要点不做类型推断OID 必须显式给出直接传 OID或通过int4这类自带 OID 的构造器错误模型公开 codec 返回类型化Result失败PgTypesCodecError而 parser 的字段读取器走内部抛异常的快路径timestamp在线路上无时区双向均按 UTC 处理解码向零截断亚毫秒精度性能取向用预分配 scratch bufferscratch4/scratch8代替逐字节 DataView 包装用两位数字表避免padStartASCII 字符串编码按 48 字符区分「逐字符循环」与encodeInto两条路径V8 实测交叉点约 50 字符。6.3PgAuthMD5 与 SCRAM-SHA-256PgAuth.ts实现协议认证交换中的 MD5 与 SCRAM-SHA-256均返回类型化ResultPgAuthError。SASL 帧结构属于PgProtocol本模块只负责帧内部的计算createHash/createHmac/pbkdf2Sync XOR。两个明确边界源码注释SCRAM-SHA-256-PLUS通道绑定未实现因为通道绑定需要 TLS socket 而 codec 不持有它密码按 UTF-8 直接使用、不做 SASLprep 归一化因此需要归一化的非 ASCII 密码不受支持。明文认证无需本模块——直接发送PasswordMessage即可。重要澄清rc.112 中PgClient本身保持原样运行时依然走pg新协议栈是独立交付的低层能力供需要自行实现客户端、或希望脱离pg的定制场景使用。七、迁移工具PgMigrator与语句辅助能力4.0.0-beta.8实现PgMigrator同时修复ChildProcess选项类型。PgMigrator.ts复用effect/unstable/sql/Migrator暴露run与layerrun用当前 SQL 客户端执行待应用的迁移文件schema dump 走pg_dump子进程附带--no-owner --no-privileges并通过PGHOST/PGPORT/PGUSER/PGPASSWORD环境变量传连接信息因此run依赖ChildProcessSpawner、FileSystem、Path等服务。4.0.0-beta.86新增Statement.valuesUnprepared——把未预处理的 SQL 语句行以数组形式返回与executeValues的rowMode: array对应见 PgClient.ts。0.1.11新增sql\....unprepared执行不尝试PREPARE的查询并加入 SQL 事务 tracing span、把 span 属性对齐语义约定0.2.9 起改用opentelemetry/semantic-conventions常量0.43.0 又随上游把属性名升级为db.system.name、db.namespace等新一代命名——PgClient.ts中的 span 属性常量ATTR_DB_SYSTEM_NAME db.system.name、ATTR_DB_NAMESPACE db.namespace 正是这一演进的结果。0.1.17PgClientConfig增加prepare与types。八、API 与模块演进的代表性节点从 changelog 可以梳理出几条贯穿始终的设计主线方言无关化0.2.0effect/sql改为方言无关客户端共享同一Context.Tag需要方言特定能力时再用实现包专属 Tag如PgClient或用sql.onDialect({ pg: ... })按方言分支。扁平导入与命名约定0.4.0 扁平化0.19.0layer/layerConfig约定导入路径与构造器命名走向统一规范。模块重命名4.0.0-beta.44ServiceMap模块重命名为Context贯穿导出、文档与测试。入口点精简4.0.0-beta.103移除显式./index入口点。v4 大版本4.0.0-beta.0以v4 beta标记的 Major Changes 开启 4.0 系列随后 beta功能推进→ rc候选发布两个阶段直至4.0.0-rc.112。九、测试与基准验证仓库为上述能力提供了完备的测试与基准支撑见 test/ 与 benchmark/PgProtocol.test.ts/PgTypes.test.ts/PgAuth.test.ts覆盖协议解析、二进制编解码与认证交换fixtures 目录goldens.ts保存黄金样本SqlErrorClassification.test.ts/TransactionAcquire.test.ts验证 SQLSTATE 分类映射与事务连接获取的错误通道Client.integration.test.ts、KeyValueStore.integration.test.ts、Persistence.integration.test.ts等集成测试基于testcontainers/postgresql起真实 PostgreSQL 容器见 package.json 的 devDependencies基准pnpm benchmark:codec运行 benchmark/PgCodec.ts基于 tinybench量化 codec 性能。十、总结effect/sql-pg的演进史本质上是一部「如何在保证类型安全与资源安全的前提下把成熟驱动pg全面纳入 Effect 生态」的工程实践记录从0.1.0的初版连接管理到0.19.0的统一layer约定再到 v4 时代原生协议栈PgProtocol/PgTypes/PgAuth的独立交付。理解这条脉络不仅能帮你正确配置PgClientConfig/PgPoolConfig并合理选用make/makeClient/fromPool等构造路径也能让你在遇到连接超时、唯一约束冲突、LISTEN/NOTIFY 通道行为异常等问题时快速定位到对应的 SQLSTATE 分类逻辑与资源获取实现真正做到「知其然更知其所以然」。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考