SQLite PoolとTransaction

std.db.sqlite はNagi 0.2.0に含まれ、0.1.11には含まれません。SF05で旧Db/db_*を廃止したため、更新前に移行を参照してください。

Docs目次 · SQLiteと移行 · SQLの事前検査

Rustからcompilerの標準module/resource/operation metadata enumを網羅matchする組込み利用者は、新しいQuery/literal variantへの対応が必要です。

何ができるか

Pool は複数のSQLite接続を管理し、Tx は一つの接続を専有します。SQL構造はopaque Query、実値はtyped owned Parametersで渡します。旧Db/db_*、runtime public Db/Sql、動的文字列factoryは削除し、旧Nagi入口はSF05 migration診断にします。旧APIとの併走fallbackはありません。

まず動かす

必要なもの

• Rust toolchain（rustc と cargo）とRust crateをビルドできるC toolchain。
• このページとexamples/sqlite_pool.nagi、Nagi 0.2.0のソースcheckout（取得したソースの作業用フォルダー）。手順はrepository rootで実行します。
• SQLiteのコマンドラインツールは不要です。SQLiteはNagi runtimeに同梱されます。

ソースの取得方法はソースからcompilerをbuildする手順を参照してください。この手順は0.2.0のソースとcompilerを使います。インストール済み0.2.0を使う場合は、下記の./target/release/nagicをnagicに置き換え、compilerのbuildを省略できます。

cargo build がnative dependencyで止まる場合は、Rust toolchainに加えてOS向けC compiler/linkerが使えることを確認してください。nagic が見つからない場合は、下のrelease binaryを直接実行するか target/release をPATHへ追加します。

コンパイラとサンプルを実行する

repository root（Cargo.toml があるdirectory）で、compilerをbuildし、サンプルをcheckしてから実行します。

cargo build --release --locked -p nagic
./target/release/nagic check examples/sqlite_pool.nagi
./target/release/nagic run examples/sqlite_pool.nagi

check が成功すると診断なしで終了し、run は次を標準出力へ表示します。

7
closed

Windowsでは同じrepository rootでrelease executableを指定します。PATHに追加済みなら nagic.exe だけを使えます。

cargo build --release --locked -p nagic
./target/release/nagic.exe check examples/sqlite_pool.nagi
./target/release/nagic.exe run examples/sqlite_pool.nagi

このsampleは :memory: DBを一接続で開き、tableを作り、7 を保存して読み直し、最後にpoolをcloseします。query は0行なら None、1行以上なら先頭行を Some にします。sampleの main が成功したときの出力は 7 と closed です。失敗時に nagic run がどのerror文面を表示するかはAPI契約ではありません。

sampleの std.result.map_error は、異なるerror型をアプリの AppFailure に明示変換します。options と bind_f64 は通常の Error を返し、DB操作は sqlite.Failure を返します。Failure は Error へ暗黙変換されません。

import std.db.sqlite as sqlite
import std.result as result

class Total:
    amount: i64

enum AppFailure:
    Configuration(cause: Error)
    Database(cause: sqlite.Failure)

def configuration_error(cause: Error) -> AppFailure:
    return AppFailure.Configuration(cause)

def database_error(cause: sqlite.Failure) -> AppFailure:
    return AppFailure.Database(cause)

async def write_and_read(pool: view[sqlite.Pool]) -> Result[i64, sqlite.Failure]:
    tx = try await sqlite.begin(pool, sqlite.BeginMode.DEFERRED)
    try await sqlite.exec(tx, sqlite.literal("CREATE TABLE IF NOT EXISTS amounts(amount INTEGER NOT NULL)"), sqlite.parameters())
    values = sqlite.bind_i64(sqlite.parameters(), 7)
    try await sqlite.exec(tx, sqlite.literal("INSERT INTO amounts VALUES (?)"), values)
    try await sqlite.commit(tx)
    tx = try await sqlite.begin(pool, sqlite.BeginMode.DEFERRED)
    row = try await sqlite.query[Total](tx, sqlite.literal("SELECT amount FROM amounts"), sqlite.parameters())
    try await sqlite.rollback(tx)
    match row:
        case Some(total):
            return ok(total.amount)
        case None:
            return ok(0)

async def main() -> Result[unit, AppFailure]:
    config = try result.map_error(sqlite.options(1, 2, 1000, 0), configuration_error)
    pool = try result.map_error(await sqlite.open(":memory:", config), database_error)
    work = await write_and_read(view(pool))
    ending = await sqlite.close(pool, 1000)
    # Observe close even when the transaction failed; preserve the work error first.
    amount = try result.map_error(work, database_error)
    try result.map_error(ending, database_error)
    print(amount)
    return ok(print("closed"))

write_and_read が失敗しても main はcloseをawaitしてからworkのErrを返します。workとcloseが両方失敗した場合、このsampleはwork側を優先しclose側のErrを返しません。業務アプリでは両方をログや独自errorに記録してください。

手順が失敗したら

用語と値の所有

Pool はnon-Copyです。共有handleを増やすときは sqlite.clone_pool(pool) を使います。各cloneはclose開始・failureを共有します。Tx はnon-Copy/non-Clone/non-sharedで、task境界を越えず、class fieldへ保存できません。同じtask内のlocal、Option / Result、owned関数委譲では使えます。通常のSQLite operationは view[Tx] として暗黙に借ります。自作関数が view[Tx] を受け取る場合は、呼出し側で view(tx) を明示します。

commit(tx) と rollback(tx) は引数の Tx をconsumeします。Futureを作った時点で所有権が移るため、await後に同じhandleを使えません。読み取りを終えた後でtransactionを続けるなら、古いTxを再利用せず新しく begin します。

設定とpath

options(connections, queue_capacity, acquire_ms, busy_ms) の4引数は省略できません。数値のdefaultはありません。

capacity超過、負数、時間変換範囲外は options の Error です。0msは「必ずtimeout」ではなく待たない指定です。要求時点で条件が満たされていれば成功します。

open(path, options) は空pathと file: URIを拒否します。:memory: はconnectionごとに別DBになるため、connections は1だけです。それ以外は通常のfilesystem pathを使い、相対pathは実行時current working directoryを基準にします。open はpathをFuture作成時に所有しますが、native connectionはlazyに begin 時に作ります。したがってfilesystem/native openの失敗が open ではなく最初の begin の WORKER failureとして返る場合があります。自動WAL、URI解釈、共有memory URIはありません。

sqlite.literal("SELECT id FROM items WHERE id = ?") はcanonical identityにより直接literalだけを受理します。変数・view・連結・format・関数返却strは元位置付きで拒否します。同名のユーザー関数は占有しません。QueryはCopyでlocal/field/返却値に使えますが、SQL文字列を取り出せず、JSON・Eq・直接構築はできません。query/all/execはQuery必須です。通常checkはSQL parserを持たず、SQLのshapeはruntimeまたは明示SQL事前検査が確認します。

型付き引数とSQLの形

parameters()で空の値列を作り、builderの戻り値を次のbuilderへ渡します。追加した順番が、SQLの匿名placeholder ? に対応します。

新APIは一度に一つのSQL文と匿名?だけを受け付けます。名前付きの:name / @nameや番号付きの?1は使えません。bind数、値型、NULLの読み取りはruntimeで検査します。通常のcheckが実DBの値を使ってSQLを実行することはありません。値はSQL文字列へ連結せず、Parametersで渡します。

query・all・execの使い分け

RETURNING付きの書き込みは、readonlyでもcolumnなしでもないため、上のどの操作も受け付けません。利用者SQLにBEGIN / COMMIT / ROLLBACKとそのvariant、SAVEPOINT、PRAGMA、ATTACH、DETACHを書かず、moduleの操作でtransactionを開始・終了します。virtual table、extension、raw connectionの公開はありません。

Tは標準FromRow生成が対応するfieldを持つclassです。scalarのi8/i16/i32/i64/u8/u16/u32/f32/f64/bool/str/bytes、そのOption、対応するowned[...] wrapperを使えます。field名を返却列名に合わせ、NULLを受け取るfieldにはT?を使います。enum、resource、任意generic、未対応fieldはcheckで拒否します。実データの値型・NULL・整数範囲はruntimeのResultで扱います。手書きRustのFromRowを用意しても、新APIのchecker制約は回避できません。

Public typesと操作一覧

このmoduleは9型と19操作を公開します。view[T] は値をborrowする型、Future[T] はawaitする非同期処理、Result[T, E] は成功値かerrorのどちらかです。tryは現在のfunctionからErrを返します。より詳しい言語規則はview、async、Resultを参照してください。

async operationではawait後にResultをtryまたはmatchで処理します。optionsとbind_f64の失敗はError、残りのDB operationはFailureを返します。

Parametersの使い方

bind_i64などは引数のParametersをmoveして返します。次のbindへ返却値を渡します。query / all / exec もParametersをconsumeするので、同じ値を二回渡せません。

def make_values() -> sqlite.Parameters:
    values = sqlite.parameters()
    values = sqlite.bind_i64(values, 4)
    values = sqlite.bind_text(values, "Nagi")
    return values

この値はSQLの匿名?へ順番にbindされます。queryに渡したあと別文にも値を渡したい場合は、文ごとにParametersを作るか、値を再構築してください。copyでParametersを複製することはできません。

複数行を読む

all[T]はrow classを指定し、全行を返します。例えば現在のTotal classでamountを読む処理は次の形です。

async def read_all(tx: view[sqlite.Tx]) -> Result[List[Total], sqlite.Failure]:
    return await sqlite.all[Total](tx, sqlite.literal("SELECT amount FROM amounts ORDER BY amount"), sqlite.parameters())

queryは最初の1行だけ、allは全行です。readonly SQLの結果を1件だけ扱うならquery、複数件を走査するならallを選びます。execはrow結果を返さないDDLやwrite向けです。operation形の誤り、複数文、named/numbered placeholderはruntimeで拒否されます。

間違いと直し方

自作helperは次のようにborrowしたTxを受け取り、同じtask内で使えます。

async def read_total(tx: view[sqlite.Tx]) -> Result[Total?, sqlite.Failure]:
    return await sqlite.query[Total](tx, sqlite.literal("SELECT amount FROM amounts"), sqlite.parameters())

async def call_read_total(tx: sqlite.Tx) -> Result[Total?, sqlite.Failure]:
    return await read_total(view(tx))

SQLite authorizerはSQL内の BEGIN / COMMIT / ROLLBACK、SAVEPOINT、PRAGMA、ATTACH / DETACH も拒否します。transaction境界にはmodule operationを使います。

transactionと並行処理の境界

Poolのlogical slot待ちはTokioのFIFO semaphoreへ委譲されます。FIFOの説明はこのlogical permit waitに限ります。native workerの起動、native slot登録後のadmission、SQLite BEGIN 完了までの順序は保証しません。

acquire_ms はlogical permit待ちからnative record登録まで同じ取得予算を使います。connection startupと登録後のready/BEGIN SQL busy waitはこの予算に含みません。busy_ms がSQLite busy waitを制限します。SQL実行・commitに別のinterrupt deadlineはありません。

一つの Tx が一接続を専有します。Pool cloneは共有しても、Txをchild taskへmove/captureしたり、別taskから同じTxを使ったりできません。必要ならchild task内でPoolから独自に begin します。外側taskの TaskFailure（子自体の失敗）と、そのtaskの戻り値に入る Result[..., sqlite.Failure]（DB操作の失敗）は別の層です。

普通のSQL、bind、decode errorでもnative transactionがactiveだと確認できればTxは継続できます。ただし失敗したstatementが変更を一切していないとは限らず、同じtransaction内の先行効果が残る場合があります。SQLiteが自動rollbackした場合は ABORTED / ROLLED_BACK として後続操作を拒否します。cancelは受理済みSQLや外部副作用をundoしません。retryやrollbackが安全だと推測せず、業務のidempotencyと明示rollbackを設計してください。

Failureを読む

Failureの分類とtransaction結果を分けて読みます。outcome は観測できた状態であり、再実行の安全性を表しません。

ALLOCATION は明示的なfallible reservation失敗を分類します。すべてのOOMやallocator abortから回復する保証ではありません。

retired はそのFailureで接続のretirementが確認されたかを表します。false は「このfailureからretirementを確認できていない」だけで、workerやPoolが健全だと証明しません。特に REPLY_LOST + UNKNOWN から、rollback済み・connection再利用可能・retry安全を推論しないでください。Debug表示は kind / outcome / retired に限定されますが、公開 message の文字列は安定したprotocolではありません。

Failure.message は Failure ownerを借りる view[str] です。Failureより長く保持するなら copy(problem.message) で所有文字列を作ります。native causeをerrorとして保持したいときは copy_primary_error(problem) と copy_cleanup_error(problem) を明示的に使います。どちらも Option[Error] で、causeがなければ None、ある場合はkind/messageをコピーします。commitが完了してcleanupが失敗するなど、primaryとcleanupの情報が別々に存在するfailureがあります。

Poolを閉じる

close(pool, timeout_ms) はcloneすべてで共有するclosingを開始し、新しい begin を止め、active Txの終了とworkerのnative close/actual joinを待ちます。timeoutが0でも既に終了を確認済みなら成功できます。timeoutやclose Futureのcancel後もclosingは戻りません。active Txを強制終了せず、後の close でも完了を待てます。

Pool の最後のhandleをDropしても、非同期cleanupやworker joinの完了確認にはなりません。Dropは閉鎖を要求するだけです。終了を確認する必要がある処理では、所有者が close をawaitしてください。close成功はnative closeとworker threadのactual joinを確認した結果です。無期限にblockするSQL、process kill、allocator abortからcloseが必ず戻る保証はありません。

SQLの事前検査

通常checkはQueryのliteral境界、型・所有権・行fieldを検査し、SQLiteエンジンを起動しません。明示schemaによるopt-in検査は直接Query constructorのSQL形・schema・必要列をprepare-onlyで確認します。直接Parameters builder列のbind個数は照合し、変数/関数経由のQuery構造やParameters個数はruntime検査として表示します。実値型・NULL・数値範囲・DB内データはruntimeで確認します。SQL事前検査を参照してください。

使い分けと関連ページ

• 汎用typed parameters、複数文を跨ぐ明示Tx、複数接続とclose制御が必要なら、この新APIを選びます（使えるのはこのAPIを含む開発sourceからbuildしたcompiler）。
• API shapeをschemaと照合するoffline checkはSQL事前検査。Nagi Result、try、nullable、view、ownershipの規則はエラー処理、Optionとnullable、所有権、view、asyncを参照してください。