HHY 扩展 · v1.1 已实现

数据库扩展使用指南

安装官方 database 0.2.0 扩展，通过 JSON 配置连接 MySQL/PostgreSQL，并完成查询、写入与事务。

当前支持范围

Callable	用途	当前边界
database.ping(url)	验证连接并返回数据库信息	每次调用建立短连接
database.query(url, sql, params, max_rows?)	执行有界参数化查询	结果包含 columns 与 rows
database.execute(url, sql, params)	执行参数化写入或受控 DDL	返回受影响行数
database.transaction(url, statements)	原子执行 1–100 条写语句	仅 INSERT/UPDATE/DELETE；失败整体回滚

构建并安装扩展

make -C extensions/database
./build/hhy install ./extensions/database
./build/hhy list

install 会校验 hhy.toml、HHY 版本范围、扩展命令和 SHA-256 完整性，并在安装前展示网络 capability。安装成功后，脚本中的 import database 会启动隔离扩展进程、完成 Protocol 1 握手并注册四个 callable。

使用 JSON 配置数据库地址

cd extensions/database/examples/hhy_extension_test
cp config.example.json config.local.json
chmod 600 config.local.json

{
  "url": "mysql://root:CHANGE_ME@127.0.0.1:3306/hhy_extension_test",
  "database": "hhy_extension_test",
  "max_rows": 1000
}

驱动	连接 URL 示例	参数占位符
MySQL	mysql://user:password@127.0.0.1:3306/hhy_extension_test	?
PostgreSQL	postgresql://user:password@127.0.0.1:5432/hhy_extension_test	$1、$2……

查询测试库有多少张表

./build/hhy run \
  extensions/database/examples/hhy_extension_test/read.hhy \
  extensions/database/examples/hhy_extension_test/config.local.json

import database
import { load_database_config } from "./lib/config.hhy"

let config = load_database_config(args[0])
let result = database.query(
    config.url,
    "SELECT COUNT(*) AS table_count FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE'",
    [config.database],
    1
)

print("Database", config.database)
print("Table count", result.rows[0].table_count)

仓库中的完整 read.hhy 还会列出每张表的名称、存储引擎和估算行数。SQL 值通过 params 传给驱动的 prepared statement，不会拼接进查询文本。

写入与事务

./build/hhy run extensions/database/examples/hhy_extension_test/write-demo.hhy \
  extensions/database/examples/hhy_extension_test/config.local.json --write

./build/hhy run extensions/database/examples/hhy_extension_test/transaction.hhy \
  extensions/database/examples/hhy_extension_test/config.local.json --write

database.transaction(config.url, [
    { sql: "INSERT INTO _hhy_transaction_test (id, message) VALUES (?, ?)", params: [1, "created"] },
    { sql: "UPDATE _hhy_transaction_test SET message = ? WHERE id = ?", params: ["committed", 1] }
]) |> print

错误排查与完整资料

现象	检查项
ModuleNotFoundError	先执行 install，并用 hhy list 确认 database 0.2.0 已安装
cannot open .../read.hhy	从仓库根目录运行完整路径，目录名是 hhy_extension_test
连接失败	检查服务、端口、用户名、密码、库名及 hhy.toml 声明的本机网络范围
SQL 参数错误	MySQL 使用 ?；PostgreSQL 使用 $1、$2……；标识符不能作为值参数

继续阅读扩展系统原理了解清单校验、权限声明、进程加载、Protocol 1 握手和扩展开发者约束。