std:db/sqlite — SQLite ドライバー
標準ライブラリモジュール (../index.md)。本書中の裸の §N は本書の節を指す。ドライバー横断の契約 (プレースホルダー・行と値・エラー kind・トランザクション) は ../db.md を正とし、本書は SQLite 固有の部分のみを定める。言語の意味論は ../../language-spec.md を参照。
import sqlite := "std:db/sqlite" はコンストラクター open と不透明ハンドル型 Db / Tx、列値の enum Value と Row を持つ namespace object を sqlite に束縛する。std:db/sqlite の import 自体が「このコードはデータベース (ファイル) に触れる」ことの能力宣言になる (../index.md)。
std:fs と同じ外部リソース I/O であり、操作は Future(Result(...)) を返す (prelude.md §9.4)。
export {} # ハンドルは多重度型なので公開メンバーに入れられない ([static-analysis.md](../../static-analysis.md#2-静的型検査)) import sqlite := "std:db/sqlite" type UserRow := { name: String, age: Option(Int) |} db := sqlite.open(":memory:")!.unwrap! db.exec("create table if not exists users (id integer primary key, 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! # None → NULL 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.transaction { tx | tx.exec("update users set age = age + 1 where name = ?", ["Alice"])!? Ok(()) })!.unwrap! db.close()!.unwrap!
1. コンストラクター
| 名前 | 形 | 効果 | 意味 |
|---|---|---|---|
open |
sqlite.open(path) |
Fs |
DB ファイルを開く (不在なら作成) → Future(Result(Db)) |
pathは String。非 String は静的エラー。- 相対パスは プロセスの cwd 基準 (fs.md §12 と同じ)。
":memory:"でオンメモリ DB (close で消える)。 - URI ファイル名 (
file:...?mode=ro等)・read-only オープンは持たない。 - 権限不足・親ディレクトリ不在・ファイルが DB でない等の失敗は
Err(§11)。 - 空のパス (
"") はErr(io_error)— 開くファイルが無い。SQLite は空の名前を一時 DB として開くが、それは":memory:"と違って書いた名前から読み取れない振る舞いである。 file:で始まるパスも URI ではなくパスとして読む (上の URI ファイル名を持たないことの帰結)。
2. Db のメソッド
| メソッド | 形 | 効果 | 返り |
|---|---|---|---|
query |
db.query(sql, params, type T) |
Fs |
Future(Result(List(T))) (§3) |
query_rows |
db.query_rows(sql, params) |
Fs |
Future(Result(List(Row))) (§3.1) |
exec |
db.exec(sql, params) |
Fs |
Future(Result({changes, last_insert_rowid})) (§4) |
transaction |
db.transaction(block) |
Fs(ブロックを透過) |
Future(Result(T)) — T は block の Ok payload (§5) |
close |
db.close() |
Fs |
Future(Result(()))。閉じた時点でハンドルは封印され、以降どのメソッドも Error (use after close)。トランザクションが接続を握っていれば解放を待ってから閉じる (§5) |
ハンドル規律は fs.md §11 の File と同一 (可変 scratch ハンドル: 束縛 immutable・内部状態のみ前進・値型ではない・== / compare なし・std:map / std:set のキー不可)。Db は std:db/sqlite の型メンバーとして export される (sqlite.Db)。
transaction が block へ渡すハンドルの型 Tx も型メンバーとして export される (sqlite.Tx)。transaction の宣言型がブロックパラメーターの型として Borrowed(Tx) を持ち (../db.md §9)、その綴りが注釈位置にも現れるためである。Db と同じ不透明ハンドル型で、内部表現は露出しない。
Db と transaction が渡すトランザクションハンドル Tx は非 Copyable である (../../language-spec.md の複製の節)。ホストの接続を持つ可変ハンドルで、作り直しても同じものにならないためである。copy の直接の呼び出しは静的エラーになり、spawn / std:parallel の捕獲検査も弾く。
Db はExactlyOnce の多重度型である (../../language-spec.md の多重度型の節)。close が Consuming メソッドで、query / query_rows / exec / transaction は借用である。
3. query
- 引数:
(sql, params, type T)。sqlは String、paramsはList(Any)、
Tは行の record 型 (db.md §3)。
paramsは省略できない。束縛が無いなら[]と書く。
バインドの受理集合は db.md §5 に従う。 - プレースホルダーは
?。個数とparamsの長さの不一致はバグ層のErrorで、!で表面化する。 - resolve 値は
Result(List(T))。成功時は対象型へ復号した全行のOk(rows)、0 行はOk([])。
失敗時はErr({ kind, message |})(§11)。 - 値の storage class (§6) を対象型と照らして復号する。
カラム宣言型 (affinity) は基準にしない。列の欠け・許されない NULL・型違いはErr(decode)。
NULL を許す列はOption(T)と書く。 - SELECT 以外の文も実行できる (行を返さない文は
Ok([]))。 sqlは 1 文に限る。;で区切った 2 文以上を含むsqlはErr(sql_error)— 2 文目以降を知らせずに捨てると、書いた文が走らなかったことに気づけない。空の文 (;だけ) は数えないので、末尾の;(続けて書いたものを含む)・空白・コメントは 1 文に数える。文が 1 つも無いsql(空白・コメント・;だけ) もErr(sql_error)である。NUL (U+0000) を含むsqlもErr(sql_error)である — SQLite は NUL までしか読まないので、通すと NUL より後ろを知らせずに捨てる。query_rows/execも同じ規則である。
3.1 query_rows
query_rows(sql, params) は形の分からない行を読み、Future(Result(List(Row))) を返す。
sql: String と params: List(Any) は省略できず、効果は Fs である。
バインド・SQL の失敗・封印後の利用は query と同じ規則に従う。
Row は InsertionMap(String, Value) で、SQL の列名を文字列のまま SELECT の列順に保持する。
識別子でない列名もキーにできる。重複する列名は Error である。
INTEGER / REAL / TEXT / BLOB / NULL は §6 の Value のタグに写す。
SELECT 以外の行を返さない文を含め、0 行は Ok([]) である。
export {} import sqlite := "std:db/sqlite" import assert := "std:assert" db := sqlite.open(":memory:")!.unwrap! rows: List(sqlite.Row) := db.query_rows("select 1 + 1, null as missing", [])!.unwrap! assert.equal(rows.0.get "1 + 1", Some(sqlite.Value.Int(2))) assert.equal(rows.0.get "missing", Some(sqlite.Value.Null)) db.close()!.unwrap!
4. exec
- 引数:
(sql, params)。sql: String/params: List(Any)の検査規則はqueryと同じ。 - resolve 値は
Result(record): - 成功時:
Ok({changes, last_insert_rowid})— closed・immutable なレコード: changes— 行を変えうる文 (INSERT / UPDATE / DELETE) が変えた行数 (Int)。db.md §6 の契約スロット。1 行も該当しなければ0になるlast_insert_rowid— 直近に INSERT された rowid (Int)。INSERT 以外では意味を持たない (SQLite のsqlite3_last_insert_rowidに対応する sqlite 拡張スロット)- 失敗時:
Err(e)—{ kind, message |}(§11)。 - 行を返す文 (SELECT 等) も実行できる (行は捨てられる)。
- 行を変えられない文 (SELECT・DDL・PRAGMA 等) の後の
changesは、その接続で最後に行を変えうる文が出した値のままである (この接続の計数は行を変えうる文だけが更新する)。last_insert_rowidが「INSERT 以外では意味を持たない」のと同じ規律で、0へ戻りはしない。読むのは行を変えうる文の直後に限ること。
5. transaction
契約は db.md §9 に従う。tx.query(sql, params, type T) の結果は Future(Result(List(T))) で、復号規則と Err(decode) は Db と同じ。
tx.query_rows(sql, params) も Future(Result(List(Row))) を返し、Db と同じ規則で行を組む。
問い合わせは Tx を借用する。終了後の Tx は sealed になり、
query_rows を呼ぶと transaction is finished の Error になる。
SQLite 固有の規定:
- BEGIN の種別は実装既定 (DEFERRED 相当)。種別を指定する手段は持たない。
- ネスト:
txはtransactionメソッドを持たない (呼べば静的エラー)。block 内で同じDbのdb.transactionを再度呼ぶと、接続の直列化 (§7) により待ちの期限超過でErr(busy)になる (内側の BEGIN には到達しない)。 - トランザクション中の
db直接操作:transactionの実行中、同じDbへの直接のquery/query_rows/exec/close(block 内・他フローを問わず) は接続の解放を待ち、実装既定の待ち時間 (§7) を超えるとErr(busy)で resolve する。block 内の操作はtx経由が正道。 txは block の評価が終わった時点で封印され、block の外へ持ち出して使うとError(use after close と同じ規律)。
6. 型対応
読み (SQLite storage class → Hikari)。
型付き問い合わせでは、列値に対応する型へ復号する。
Option(T) の位置では非 NULL を Some に包み、NULL を None にする。
形の分からない行では Value のタグで表す。
| storage class | 型付き問い合わせの値 | Value |
|---|---|---|
| INTEGER | Int | Value.Int(n) |
| REAL | Float | Value.Float(n) |
| TEXT | String | Value.Text(s) |
| BLOB | Bytes | Value.Blob(b) |
| NULL | Option(T) の位置だけ None |
Value.Null |
Value / Row は sqlite.Value / sqlite.Row として公開する。
定義は db.md §4.1 のとおり。
書き (Hikari → SQLite)。生値と Some(v) の v に適用 (db.md §5):
| Hikari | SQLite |
|---|---|
| Int | INTEGER。64bit に収まらない Int は Error (SQLite の INTEGER は 64bit。Hikari の Int は任意精度、language-spec.md §7.1) |
| Float | REAL。NaN は Error (SQLite は NaN を NULL に変換するため、暗黙の None 化に当たる。±Inf は格納可) |
| String | TEXT |
| Bytes | BLOB |
None |
NULL |
| Bool ほか受理集合外 | Error (db.md §5。Bool は to_int 等で明示変換) |
書いた値が実際に格納される型は、列に宣言した型の規則 (SQLite の型の親和性) に従う — INTEGER の列へ書いた数字の String ("12") は整数として格納され、読むと Value.Int(12) である。宣言した型を持たない列は書いた型のまま格納する。
TEXT 列に UTF-8 として読めないバイト列が含まれる場合、そこを置き換え文字 U+FFFD に置き換えた String になる (fs.md §1 の read と同じ)。エンコーディングの不確かなデータは BLOB で扱う。
7. 並行モデルと busy
Db1 個は単一接続である。同じDbへの操作は (協調スケジューラー上の複数フローから同時に発行しても) 内部で直列化され、データ競合は起きない。- 他プロセスとのファイルロック競合、および接続の直列化待ち (§5) には実装既定の待ち時間 (5 秒相当の busy timeout) を適用し、超過は
Err(busy)。exec("pragma busy_timeout=...")で上書きできる。 - 複数接続・プールによる並列度の制御は提供しない。
- 操作の
Futureを取り消すと、まだ走り出していない操作は走らない (prelude.md §9.8)。接続の解放を待つ操作 (§5) と、受け付けた操作が捌けるのを待つtransaction・closeがこれにあたり、Futureはキャンセルの panic で解決する。Futureを!で待っているフローを取り消した場合も同じ扱いにする。 - 走り出した問い合わせと更新は打ち切らない。SQL は最後まで走り、
Futureはその転帰で解決する。取り消した後も、その操作が書いた結果は残りうる。
8. PRAGMA と設定
専用の設定 API は持たない。PRAGMA は exec でそのまま通す:
db.exec("pragma journal_mode=wal", [])!.unwrap!
journal mode 等は SQLite の既定のまま (本モジュールが変更するのは busy timeout の既定 §7 のみ)。
9. embed バイナリ (hikari build) での挙動
SQLite エンジン (C 実装を同梱ビルドする) の同梱は条件付きである。hikari build (build.md) は import グラフを静的解決するため、std:db/sqlite を import するプログラムに限りエンジンを link する。import しないプログラムの生成バイナリは 1 byte も増えない。開発用 hikari CLI 本体には常時同梱され、hikari run でいつでも使える。
10. 対応プラットフォーム
hikari build の検証済みターゲット (build.md「対応ターゲット」) をすべて支える。wasm では未提供 — import は解決するが open が常に Err(io_error) で resolve する。
11. エラー
失敗は Err({kind, message}) (db.md §7 の正規 kind)。SQLite との対応:
| kind | SQLite 側 |
|---|---|
sql_error |
SQL 構文エラー・実行時 SQL エラー |
constraint |
SQLITE_CONSTRAINT 系 (UNIQUE / NOT NULL / FOREIGN KEY / CHECK) |
busy |
SQLITE_BUSY / SQLITE_LOCKED・接続直列化待ちの期限超過 (§7) |
decode |
必要な列の欠け・許されない NULL・storage class と対象型の不一致 |
io_error |
open 失敗・ディスク I/O・DB ファイル破損ほか |
バインド値の受理集合・範囲違反、プレースホルダー個数不一致、重複する列名、封印後使用は Error (db.md §7)。