言库·象城

言库·象城（包名 言库象城，仓库 yanxu-postgres）是建立在 言库 1.x 协议上的生产级 PostgreSQL 驱动。它通过言序 ABI v2 原生扩展直接连接 PostgreSQL，提供参数化查询、预编译语句、事务、连接池、TLS、结构反射、迁移和言据/JSONB 集成。

当前稳定版本为 1.0.0。最低言序版本为 1.1.12，支持 PostgreSQL 14 至 18。

主要能力

• PostgreSQL 原生参数绑定、查询、执行、列元数据和稳定错误分类；
• 可复用预编译语句、绑定对象、显式关闭和父连接资源级联；
• 手动与托管事务、保存点、隔离级别、只读事务和事务超时；
• 查询超时、请求标识匹配和独立取消句柄；
• 最小/最大连接、取得超时、健康检查、生命周期和等待上限可配置的连接池；
• PostgreSQL 14 至 18 的 schema、表、列、主键、约束、索引和外键反射；
• JSONB、数组、UUID、数值、日期时间、枚举和枚举数组映射；
• 规范言据文本与 PostgreSQL JSONB 两种存储策略；
• 参数化 JSONB 路径条件、顶层键条件和 GIN 索引建议；
• 带 SHA-256 校验和、事务级 advisory lock、干运行、状态、回退和漂移拒绝的迁移；
• rustls TLS、系统信任根、自定义根证书和完整主机名验证；
• 可注入日志、指标、时钟，以及言据导入导出协议。

安装

在应用清单中锁定稳定标签：

[依赖]
言库象城 = { git = "https://github.com/yanxulang/yanxu-postgres.git", 修订 = "v1.0.0", 版 = "^1.0" }

[权限]
网络 = ["数据库主机:5432"]
原生扩展 = true

依赖不会替顶层应用授予网络或原生扩展权限。应用应把网络授权收紧到实际数据库主机和端口；从文件读取自定义根证书时，还须自行授予对应文件权限。

五分钟示例

引「包:言库象城」为 象城；

定 数据库 为 象城.打开配置（{
    「地址」：「postgresql://app@db.example/app」，
    「密码」：「由安全配置注入」，
    「TLS」：「验证完整」，
    「选项」：{「连接超时毫秒」：5000}
}）；

数据库.执行（
    「CREATE TEMP TABLE users(id BIGSERIAL PRIMARY KEY, name TEXT NOT NULL, profile JSONB NOT NULL)」，
    【】
）；

定 插入 为 数据库.预编译（
    「INSERT INTO users(name, profile) VALUES($1, $2) RETURNING id」
）；

定 编号 为 插入.查询（【「子衿」，{「等级」：10}】）.标量（）；
插入.关闭（）；

定 用户 为 数据库.查询（
    「SELECT id, name, profile FROM users WHERE id = $1」，
    【编号】
）.首行（）；

言 用户；
数据库.关闭（）；

SQL 模板与参数必须分开传入。表名、列名和排序表达式不能作为值参数绑定；动态标识符应先通过业务白名单，再由 数据库.方言（）.引名（名称） 引用。

仓库中的 examples/象城入门.yx 会连接真实 PostgreSQL，执行临时表、预编译写入、JSONB 查询和关闭流程。

连接与 TLS

打开配置 接受连接地址，也接受分离的 主机、端口、数据库、用户 和 密码。TLS 可取：

• 验证完整：默认值，要求 TLS，并校验证书链与连接主机名；
• 要求：与 验证完整 使用相同的完整验证；
• 优先：允许 PostgreSQL 客户端按服务端能力选择 TLS；
• 禁用：仅用于受控明文环境，例如本机隔离测试服务。

根证书PEM 可放在顶层或 选项 中；驱动会在系统信任根之外加载它。连接地址、密码和证书正文不会写入驱动错误消息或默认日志。

事务、超时与取消

引「包:言库」为 言库；

定 结果 为 数据库.托管事务（法（事务）则
    事务.执行（「UPDATE accounts SET balance = balance - $1 WHERE id = $2」，【10，甲】）；
    定 保存点 为 事务.保存点（）；
    保存点.执行（「UPDATE accounts SET balance = balance + $1 WHERE id = $2」，【10，乙】）；
    保存点.提交（）；
    归 「已提交」；
终，言库.事务选项（）.隔离（「可串行」）.超时（5000））；

单次执行可使用 言库.执行选项（）.超时（毫秒）.请求标识（标识）。数据库.取消（标识） 只匹配当前活跃请求；空闲取消不会污染下一次查询。超时或无法判定的取消竞态会丢弃连接，避免把不确定协议状态重新放回连接池。

错误处理

公开操作通过 言库 返回带稳定代码的错误。常见类别包括：

• YANKU_UNIQUE、YANKU_FOREIGN_KEY、YANKU_NOT_NULL、YANKU_CHECK：约束错误；
• YANKU_TIMEOUT、YANKU_CANCELLED：截止时间或显式取消；
• YANKU_SERIALIZATION、YANKU_DEADLOCK：可由业务重试策略处理的并发错误；
• YANKU_AUTHENTICATION、YANKU_CONNECTION：认证或连接错误；
• POSTGRES_CONNECT_TLS：TLS 握手、证书链或主机名验证失败；
• YANXIANG_*：驱动层配置、JSONB 路径、资源状态和迁移边界错误。

程序应按错误代码分类，不依赖完整中文消息，也不应把数据库连接地址或密码回显给终端用户。

兼容与限制

• 最低言序版本：1.1.12；
• 稳定依赖：言库 1.x；
• PostgreSQL：14、15、16、17、18；
• 原生制品目标：macOS、Linux、Windows 的 x86-64 与 ARM64；
• 驱动依赖 标准:原生，须通过字节码 VM/YXB 运行，树解释器不能载入；
• 单条 SQL 最大 1 MiB，参数最多 65,535 个；
• 单次查询最多 100,000 行、1,024 列和 16 MiB 解码结果；
• 同名结果列会被拒绝，查询应显式使用唯一别名；
• 当前不提供异步流式行读取、COPY 协议、LISTEN/NOTIFY、客户端证书认证或自动断线重放；
• 连接池剔除失效连接，但不会自动重放可能已提交的写请求。

完整说明见 使用指南、API 参考、兼容矩阵、迁移指南 与 安全模型。

本项目采用 MIT 许可证。