全部章节21
本页目录

HHY 扩展 · 当前版本 v1.7.1

数据库扩展使用指南

Database 1.0.0:MySQL/PostgreSQL 连接池、远程 TLS、事务、预处理、游标、精确类型与 HHY Stream,最低 HHY 1.5.0,已验证兼容 1.7.0。

1.7.1 受控并发与原子性

本版修复资源生命周期并交付七个默认关闭的实验接口。请先了解状态所有者、协作文件锁、严格事务以及有界任务的保证边界。

阅读完整指南与示例包含保证矩阵、错误处理和实际验收证据

版本与安装

下载 Database 1.0.0HHY 1.5.0 · Database 1.0.0
sh
hhy --version
# Extract the matching release archive and preserve bin/ and lib/
hhy install ./hhy-database-1.0.0-darwin-arm64
hhy list

# Or build from the repository root
make -C extensions/database
./build/hhy install ./extensions/database

连接配置与远程 TLS

config.local.json
{
  "driver": "mysql",
  "host": "127.0.0.1",
  "port": 3306,
  "user": "cms_test",
  "password": "CHANGE_ME",
  "database": "hhy_test",
  "allow": [
    "127.0.0.1:3306"
  ],
  "tls": "disabled",
  "max_open": 4,
  "max_idle": 2,
  "connect_ms": 5000,
  "acquire_ms": 1000,
  "timeout_ms": 30000
}

旧 URL 调用继续支持 loopback 地址;远程连接和池选项使用 Map。MySQL 占位符为 ?,PostgreSQL 为 $1、$2;标识符不能作为值参数。allow 是可信脚本策略,不是操作系统沙箱。

连接池与查询

query.hhy
import database
let cfg = read_text(path(args[0])) |> parse_json
database.query(cfg, "SELECT ? AS value", [42], { typed: true }) |> print
database.stats() |> print
sh
hhy run query.hhy ./config.local.json

连接池按数据源和扩展进程隔离。max_open 默认 4、max_idle 默认 2;多 Worker 的总连接数需要累加。支持空闲/寿命回收、连接重置、借用超时和统计。Duration 配置如 timeout_ms: 5s 可直接传给 DB。默认结果保持 String/null;typed 模式保留数值类型,Decimal/大整数用精确封装,二进制映射 BytesBuffer。

读写事务与流式查询

transaction.hhy
import database
let cfg = read_text(path(args[0])) |> parse_json
cfg |> database.with_transaction { tx ->
    database.execute(tx, "UPDATE pages SET title = ? WHERE id = ?", ["Hello HHY", 1])
    database.query(tx, "SELECT id, title FROM pages WHERE id = ?", [1])
} |> print
stream.hhy
import database
let cfg = read_text(path(args[0])) |> parse_json
database.stream(cfg, "SELECT id, title FROM pages ORDER BY id", [])
    |> take(100)
    |> collect
    |> print

Stream 按批拉取,take 会提前关闭结果。句柄不能跨请求、Worker 或 close 后使用;请求结束清理遗留资源。未读完的结果可能导致物理连接丢弃,在事务内提前结束流时需留意事务失效。

API 与边界

API用途
ping / query / execute连接检查、查询与写入
connection / begin / commit / rollback / close作用域连接和事务
with_transaction / savepoint / rollback_to / release_savepoint事务闭包与保存点
prepare / query_prepared / execute_prepared同一连接复用服务端预处理
transaction / execute_many1–100 条原子批量 DML
cursor / fetch / next_result / close_result / stream增量结果;next_result 支持 MySQL
stats / capabilities指标与版本能力

验收与安装场景

MySQL 8.4/PostgreSQL 17、本地与 CI、AST/Bytecode、双 Worker、TLS 正反例、取消、sanitizer、百万行本地流式已验收。install.hhy 数据库夹具覆盖失败恢复、重复安装、升级回滚和备份恢复;不是完整 CMS。每库本地持续测试 5 分钟,未宣称 24 小时长稳或 RDS 故障切换通过。

完整 API 与迁移说明HHY 1.5.0 · Database 1.0.0原始数据摘要与重现方式HHY 1.5.0 · Database 1.0.0查看通过的发行 ActionsHHY 1.5.0 · Database 1.0.0