本文へ移動
Hikari 仕様

std:db — RDB アクセスのドライバー横断契約

標準ライブラリの契約文書 (index.md)。本書中の裸の §N は本書の節を指す。言語の意味論は ../language-spec.md を参照。

本書は RDB ドライバー (std:db/<driver>) が共通に従う契約 — プレースホルダー・行と値の写像・エラー kind・トランザクション — を定める。実装は db/sqlite.md のみ。

std:db 自体は import 可能なモジュールとして提供しない (import x := "std:db" は未知モジュールとして静的検査で弾かれる。static-analysis.md §1)。本書は文書上の契約であり、値・型はすべて各ドライバーが export する。ドライバー横断の構造的 interface を export するモジュールも持たない。

export {}  # ハンドルは多重度型なので公開メンバーに入れられない ([static-analysis.md](../static-analysis.md#2-静的型検査))
import sqlite := "std:db/sqlite"

# NULL を許す列だけ Option とし、問い合わせへ行の型を渡す。
type UserRow := { name: String, age: Option(Int) |}

db := sqlite.open(":memory:")!.unwrap!
db.exec("create table users (name text not null, age integer)", [])!.unwrap!
db.exec("insert into users (name, age) values (?, ?)", ["Alice", 30])!.unwrap!
db.exec("insert into users (name, age) values (?, ?)", ["Bob", None])!.unwrap!

rows: List(UserRow) := db.query("select name, age from users where age > ?", [20], type UserRow)!.unwrap!
rows.each { r: UserRow |
  println "${r.name}: ${r.age.or 0}"
}
db.close()!.unwrap!

1. スコープと位置づけ

契約が定めるのは「SQL 文字列とバインド値を渡し、行 / 変更数を受け取る」ドライバー水準の最小の APIである。SQL 方言の吸収・クエリビルダー・ORM・マイグレーションは契約の外で、pkg: エコシステムに委ねる (index.md の能力宣言と同じく、本契約はその契約点になる — std:http の Handler と同じ思想)。

std:db/<driver> の import 自体が「このコードはデータベースに触れる」ことの能力宣言になる。

2. プレースホルダー

バインドは ? (位置指定) に統一する。? の個数とバインド値 List の長さは一致しなければならない (不一致はバグ層 → Error)。

  • ドライバーは自 DB の記法へ変換する義務を負う (sqlite / mysql は ? ネイティブ、postgres ドライバーは $N へ変換する)。利用者コードはドライバーを跨いで同じ SQL 記法で書ける (記法をドライバーごとに変えると、DB を替えるたびに利用者コードの SQL を書き直すことになる)。
  • 値の埋め込みはプレースホルダーのみが正道。SQL 文字列への値の連結は injection の温床であり、本契約は連結を助ける機能 (quote 関数等) を提供しない。
  • 名前付きプレースホルダーは持たない。

3. 行の表現

query(sql, params, type T) は行の対象型 T を受け取り、Future(Result(List(T))) を返す。
T は列名をフィールド名に持つ record 型で、各行をその型へ復号し、型を満たすか実行時に照合する。
対象型と結果型は同じ型変数で結ばれるので、成功値の静的型は List(T) になる。

  • 列の欠け・許されない NULL・型違いは Err (kind decode)。入力データの復号の失敗であり、型の panic ではない。
  • 対象型に無い列は読み捨てる。record の幅部分型と同じく、対象型は読みたい列だけを書けばよい。
  • 0 行は Ok([])。行の List は全件実体化され、ストリーミング読みは持たない。
  • record のフィールドに使う列名は Hikari の識別子である。必要なら SQL の AS で別名を付ける。
    形の分からない行は文字列のキーを持つ Row で扱う (§4)。

4. 値の写像 (読み)

型付きの問い合わせでは、非 NULL の列を宣言型へ復号する。
NULL を許す列は Option(T) で書く。NULL は None、非 NULL は Some(v) になる。
Option(T) でない列の NULL、および対象型に必要な列の欠けは Err(decode) である。

row.name  # name: String なら Option で包まない
row.age.or 0  # age: Option(Int) なら NULL にデフォルト値
match row.age {
  Some(n) => n.to_string!
  None => "不明"
}

NULL 許容列のデフォルト値・変換は Option メソッド (or / map / and_then) で書ける
(prelude.md §12.1)。
各ドライバーの型対応表が、非 NULL の列値に対応する型を定める
(sqlite は db/sqlite.md §6)。

4.1 形の分からない行

ドライバーは次の値の enum と Row を公開し、Future(Result(List(Row))) を返す問い合わせを提供する。

enum Value := {
  export { Null, Int(value), Float(value), Text(value), Blob(value) },
  Null := {},
  Int := { value: Int |},
  Float := { value: Float |},
  Text := { value: String |},
  Blob := { value: Bytes |}
| OneOf(Null, Int, Float, Text, Blob) }
type Row := InsertionMap(String, Value)

キーは SQL の列名を文字列のまま持ち、エントリは SELECT の列順に並ぶ。
値は Value のタグで種類を判定して payload を取り出す。
識別子でない列名もキーにできる。
Db と Tx の両方が query_rows(sql, params) を提供する。
sql: String と params: List(Any) は省略できず、効果は Fs である。

5. バインド値 (書き)

exec / query / query_rows の params の型は List(Any) である。何でも受け取るパラメーターとして、
各要素がバインド可能かを API が判定する。受理する値は次のとおり:

バインド値 SQL 側
None NULL
Some(v) v を 1 段ほどいた値 (下行)
生値 v ドライバー型対応表の Hikari → SQL 写像 (sqlite は db/sqlite.md §6)
  • Some(v) を受理することで、query で読んだ列値をそのまま次の exec に渡して往復できる (読み書きの対称性)。
  • Bool は受理しない (Error)。SQL 標準に可搬な Bool リテラル表現がなく、0/1 への暗黙変換は「暗黙の型変換はない」原則 (prelude.md §2) に反する。to_int 等で明示変換する。
  • 受理集合外の型 (関数・record・List 等) は Error。

6. exec の結果

exec の成功値は changes (影響行数、Int) スロットを持つ record を最低保証とする。ドライバーは追加スロットで拡張してよい (構造的型の幅サブタイプ。sqlite は last_insert_rowid を加える。db/sqlite.md §4)。

7. エラーモデル

I/O・SQL・行の復号の失敗は Err({kind, message}) で運ぶ (fs.md §14 と同じ形)。正規 kind (閉じた一覧。全ドライバー共通):

kind 意味
sql_error SQL の構文・実行エラー
constraint 制約違反 (UNIQUE / NOT NULL / FOREIGN KEY / CHECK)
busy ロック競合・接続の取得待ちの期限超過 (ネストした transaction の失敗もここ。§9)
decode 対象型に必要な列の欠け・許されない NULL・列値の型違い
io_error その他 (ファイル・接続の I/O 失敗ほか)
  • constraint を独立させるのは、重複キー等の「想定内で分岐したい失敗」の代表だからである。
  • バインド値の受理集合・範囲違反、プレースホルダー個数不一致 (§2)、重複する列名、封印後使用は Error (バグ層、language-spec.md §16)。
  • 分岐は kind で行い、message の文字列マッチに依存しないこと。

8. ブロッキング I/O と Future

DB 操作はすべてブロッキング I/O であり、Future(Result(...)) を返す (prelude.md §9.4)。! で resolve 値 (Result) を待つ。root 終了時の未解決 Future の扱いは language-spec.md §13.3 のとおり。

9. トランザクション

db.transaction(block) は ブロック式のみを提供する (手動 begin / commit / rollback は提供しない — commit / rollback の対応漏れを構造的に排除する)。

  • block はトランザクションハンドル tx (query / exec と形の分からない行の問い合わせを持つ) を 1 引数で受け、Result を返す型を持つ。非 Result の返却は静的エラーになる。tx は借用としてブロックへ渡る(language-spec.md §17.8)— transaction 自身が最後に行う commit/rollback の対象を失わせないためである。この借用の規律は注釈の有無を問わず静的検査に働く — transaction の宣言型が持つブロックパラメーターの型 Borrowed(Tx) が、注釈の無いパラメーターへ流れるためである(static-analysis.md §2「注釈の無いブロックパラメーターへ型を流す」)。tx を束縛・コンテナーへ格納・別フローへ捕獲すると cannot-bind-borrowed になる。実行時の封印はこれとは独立に効く — block を抜けた後の tx は sealed になり、query / exec は transaction is finished の Error になる。
  • tx.query(sql, params, type T) も同じ型付き復号を行い、Future(Result(List(T))) を返す。
    列の欠け・許されない NULL・型違いは Err(decode) となる。
  • tx.query_rows(sql, params) は Future(Result(List(Row))) を返す。終了後の封印は query / exec と同じ規則である。
  • block が Ok(v) を返す → commit し、transaction は Ok(v) で resolve する (commit 自体の失敗は Err)。
  • block が Err(e) を返す → rollback し、Err(e) をそのまま透過する (rollback の失敗は結果を差し替えない)。
  • block の評価が panic する → rollback してから panic を伝播する (! の位置で表面化。language-spec.md §10.2)。
  • 途中の失敗 bail は ? (language-spec.md §16.5) がそのまま使える — tx.exec(...)!? は Err で block から脱出し、rollback される。
  • ネスト非対応。tx は transaction メソッドを持たない (呼べば静的エラー)。block 内で同じ Db の transaction を再度開く試みは、接続の直列化により待ちの期限超過で Err(busy) になる (sqlite は db/sqlite.md §5)。savepoint による部分 rollback は持たない。
export {}
import sqlite := "std:db/sqlite"

db := sqlite.open(":memory:")!.unwrap!
db.exec("create table accounts (id integer primary key, balance integer)", [])!.unwrap!
db.exec("insert into accounts values (1, 500), (2, 0)", [])!.unwrap!
from := 1
to := 2
result := (db.transaction { tx |
  tx.exec("update accounts set balance = balance - ? where id = ?", [100, from])!?
  tx.exec("update accounts set balance = balance + ? where id = ?", [100, to])!?
  Ok(())
})!
result.unwrap!
db.close()!.unwrap!

(後置 ! はブロックリテラル自体に結合するため、db.transaction { … } ! とは書けない — 適用全体を括弧で括ってから ! で await する。hikari format の正準形も (db.transaction { … })!。)