本文へ移動
Hikari 仕様

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

  • Db 1 個は単一接続である。同じ 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)。