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(kinddecode)。入力データの復号の失敗であり、型の 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 { … })!。)