Database Extension Guide

1.7.1 controlled concurrency and atomicity

This release fixes resource lifetimes and delivers seven experimental APIs, disabled by default. Review state ownership, cooperative file locks, strict transactions and bounded-task guarantees before enabling them.

Version and installation

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

Data sources and remote TLS

{
  "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
}

Legacy URLs remain supported for loopback. Use maps for remote endpoints and pool options. MySQL uses ? and PostgreSQL uses $1, $2; identifiers cannot be value parameters. The allow list is trusted-script policy, not an OS sandbox.

Pools and queries

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

hhy run query.hhy ./config.local.json

Pools are isolated by data source and extension process. Defaults are max_open=4 and max_idle=2; add worker budgets together. Idle/lifetime retirement, resets, acquire timeouts and metrics are supported. Duration options such as timeout_ms: 5s work directly. Results default to String/null; typed mode preserves numeric types, exact envelopes preserve decimals/large integers and binary maps to BytesBuffer.

Transactions and streaming

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

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

Streams pull batches; take closes results early. Handles cannot cross requests/workers or survive close; request completion cleans abandoned resources. Unread results can discard a physical connection, so early stream closure inside a transaction may invalidate that transaction.

API and limits

Acceptance and installation scenarios

MySQL 8.4/PostgreSQL 17 pass local/CI, AST/Bytecode, two-worker, TLS positive/negative, cancellation and sanitizer acceptance, plus local million-row streaming. An install.hhy database fixture covers failure recovery, repeat installation, failed upgrade rollback and backup restoration; it is not a full CMS. Local sustained tests ran five minutes per backend, not a 24-hour soak or RDS failover certification.