Instruction file imported from dumblepy/nim-basolato (.cursor/rules/branch/bulk-update.mdc). Copyright stays with the author.

fixブランチルール

このブランチで整理・実装することは以下の通りです。

• FrameworkBenchmarks の PostgreSQL シナリオで、DB 接続時に basolato の性能が大きく低下する要因を切り分ける。
• updates シナリオの verify fail / 実行失敗要因を、basolato 本体・allographer・ベンチマーク実装の3層に分けて整理する。
• 改善案を「即効性が高いもの」と「中長期で効くもの」に分けて記録し、実装順序を判断できる状態にする。

進捗

• basolato ベンチマーク実装（examples/benchmark/FrameworkBenchmarks/basolato）の DB / query / update / fortune 経路を確認した。
• allographer の PostgreSQL 実装（接続プール、findPlain、update、prepared statement、non-blocking wait）を確認した。
• TechEmpower FrameworkBenchmarks の update verify 条件を確認し、rows updated / executed queries / 実更新確認が失敗要因になりうることを整理した。
• 改善案を basolato 本体改善、allographer 改善、ベンチマーク測定コード改善の3分類で整理した。
• prepared_benchmark_controller.nim の query で、非同期クロージャがループ変数を参照して範囲外アクセスしうる問題（SIGSEGV）を修正した。
• basolato 側の updates を bulk update 化し、query / fortune / db を同一接続上の prepared statement 実行に寄せた。
• ベンチマークコードを steady-state を測れる形へ寄せ、updates2 を比較用の個別更新経路として残した。
• basolato の PostgreSQL 接続数を保守的な値へ調整した。
• allographer 側の silent failure と prepared statement 再利用性を改善する。
• 変更前後の実測値を取り、updates と updates2 の差を比較する。

参考資料

• /application/examples/benchmark/FrameworkBenchmarks/basolato/app/http/controllers/benchmark_controller.nim
• /application/examples/benchmark/FrameworkBenchmarks/basolato/config/database.nim
• /allographer/src/allographer/query_builder/models/postgres/postgres_exec.nim
• /allographer/src/allographer/query_builder/models/postgres/postgres_open.nim
• /allographer/src/allographer/query_builder/models/postgres/postgres_query.nim
• /allographer/src/allographer/query_builder/libs/postgres/postgres_impl.nim
• /allographer/documents/rdb/postgres_efficiency_report.md
• /allographer/.cursor/rules/branch/333-prepared-statement.mdc
• https://itsumura-h.github.io/FrameworkBenchmarks/
• https://raw.githubusercontent.com/TechEmpower/FrameworkBenchmarks/master/toolset/test_types/update/update.py
• https://raw.githubusercontent.com/TechEmpower/FrameworkBenchmarks/master/toolset/test_types/verifications.py

調査結果・設計まとめ

1. basolato自体の改善

• updates だけが 1 リクエスト内で countNum 本の Future を生成して all(futures).await している。queries は直列なのに、updates だけ内部 fan-out しているため、HTTP の同時接続数に加えて DB アクセスの同時実行数まで増幅している。
• 現状の updates は 1 件ごとに SELECT + UPDATE を個別実行している。TechEmpower の verify では「実際に更新された件数」と「クエリ数・更新行数」が見られるため、素直に 500 件分の個別更新を投げると接続待ちと DB 負荷が重くなりやすい。
• db / queries は毎回 rdb.table("World").findPlain(...) を通っており、同一 SQL を高頻度で繰り返すのに prepared statement を使っていない。
• maxConnections の決め方が強すぎる。(2000 div countProcessors()) - 2 は CPU 数が少ない環境で数百接続になりうるが、単一プロセスの async サーバでその数を使うと PostgreSQL 側の context switch と待機列が増えやすい。

改善方針:

• updates は「個別 SELECT を維持しつつ、UPDATE は 1 文の bulk update」に変える。候補は UPDATE ... FROM (VALUES ...) か CASE WHEN id = ... THEN ... END。
• db / queries / fortune はモジュールスコープで prepared statement を初期化し、リクエストごとに SQL 文字列組み立てと prepare をしない。
• updates のレスポンス生成用データは先に集め、DB 更新は id でソートした配列から bulk update を組み立てる。verify 上は JSON 順序は必須ではないが、更新 SQL は安定した順序にした方が観測しやすい。
• maxConnections はまず 32 または 64 に固定して計測し、そこから上げ下げする。接続数を増やすより、1 接続あたりの仕事量を増やす方が今回の構成には合う可能性が高い。

2. allographer自体の改善

• getFreeConn がタイムアウトすると errorConnectionNum を返すが、その後の getRowPlain / exec / getAllRows は例外ではなくそのまま return している。結果として、更新できていなくてもアプリ側では成功レスポンスを返せてしまう。
• prepared statement は接続ごとに lazy prepare されるが、プール単位の cache がない。高頻度 SQL が複数接続に散ると、prepare の局所性が弱い。
• close() は使った接続全てに DEALLOCATE を送る実装なので、短寿命の prepared statement を多用すると warm 状態を毎回捨てる。
• DML 実行時の列型取得は現在は table 単位 cache になっているが、bulk update 用の raw SQL / prepared SQL を多用する場合は、そもそも query builder を通さない高速経路の価値が高い。

改善方針:

• errorConnectionNum に到達したときは no-op ではなく DbError を投げる。silent failure は benchmark だけでなく通常アプリでも危険。
• Connections に SQL 単位の prepared cache を持たせ、同一 SQL の physical prepare を接続ごとに 1 回へ寄せる。
• close() は論理 close に寄せ、物理 DEALLOCATE は明示 API に分離する。steady-state の benchmark では prepared state を維持できるようにする。
• 接続固定 API、あるいは transaction / prepared context を足し、同一 logical operation の複数クエリを同じ接続に寄せられるようにする。
• bulk update 用に raw(...).exec() だけでなく、prepared raw SQL を再利用できる経路を整える。今回のベンチマーク用途では query builder の汎用性よりも固定 SQL の再利用性が効く。

3. benchmark_controller.nim のベンチマーク測定コード自体の改善

• 現状のコントローラ実装は「フレームワークの素の書き方」に近いが、TechEmpower のような固定シナリオでは、一般用途向けの書き方をそのまま当てると不利になる。
• updates の内部並列は steady-state の測定というより、アプリ側で追加のキューイングとプール競合を作る測定になっている。
• db / queries / fortune / updates の全てで、レスポンス形成に不要なオブジェクト生成や JSON 変換の回数をまだ削れる。

改善方針:

• benchmark_controller.nim は「ベンチマーク専用実装」と割り切り、固定 SQL + prepared statement + 最小変換で書く。
• db は prepared SELECT id, randomnumber FROM World WHERE id = ? を 1 回作って再利用する。
• queries は countNum 回のランダム ID を集め、prepared SELECT を直列で回す。リクエスト内で DB fan-out はしない。
• fortune も prepared SELECT id, message FROM Fortune ORDER BY message ASC を使う。
• updates は次の順で行う。
• ランダム (id, randomNumber) を countNum 件作る。
• verify 用の query count を満たすために、各 id について個別 SELECT を行う。
• 取得後の更新値配列から 1 文の bulk update SQL を組み立てて実行する。
• JSON レスポンスは事前に確保した配列へ埋める。
• ベンチマーク用コードは basolato の一般的な DX を示す場所ではなく、TFB の測定コードとして最短経路を優先する。汎用 API の使い勝手改善と benchmark 用特殊化は分けて評価する。

4. update 改善の実装設計図

目的:

• updates の 1 リクエスト内 fan-out をやめ、接続プール競合を減らす。
• SELECT と UPDATE を同一 connection に寄せ、prepared statement の warm 状態を最大限再利用する。
• UPDATE の round trip 数を countNum 回から 1 回へ減らす。

採用方針:

• 1 リクエストにつき rdb.withConn を 1 回だけ呼び、その connection 上で countNum 件の SELECT を直列実行する。
• SELECT は verify 条件を満たすため維持する。
• UPDATE は individual update をやめ、UPDATE "World" AS w SET randomnumber = v.randomnumber FROM (VALUES ...) AS v(id, randomnumber) WHERE w.id = v.id の 1 文にまとめる。
• レスポンス JSON は DB 実行とは分離して先に配列へ格納し、DB 成功後にそのまま返す。

update の目標フロー:

1. countNum を読む。
2. (id, randomNumber) の組を countNum 件生成する。
3. JSON レスポンス配列を同時に埋める。
4. rdb.withConn で connection を 1 本確保する。
5. その context 上で worldByIdStmt.firstPlain(ctx, ...) を countNum 回直列実行する。
6. bulk update SQL と引数列を組み立てる。
7. 同じ context 上で bulk update を 1 回だけ実行する。
8. connection 返却後、JSON を返す。

補助データ構造:

• type WorldUpdateRow = object
• id: int
• randomNumber: int
• updates: seq[WorldUpdateRow] を countNum サイズで事前確保する。
• bulk update SQL 構築用に seq[string] または seq[PreparedParam] を作る。

SQL 構築方針:

• 候補 1: VALUES ($1, $2), ($3, $4), ... を含む raw SQL を毎回組み立てる。
• 候補 2: CASE WHEN id = ... THEN ... END を組み立てる。
• 第一候補は UPDATE ... FROM (VALUES ...) とする。 理由:
• PostgreSQL で素直で速く、id と randomnumber のペアをそのまま渡せる。
• CASE WHEN より SQL が単純で、更新対象一覧との対応が追いやすい。

allographer 側の利用方針:

• 既存の worldByIdStmt はそのまま利用する。
• bulk update は query builder を通さず raw SQL 実行を優先する。
• bulk update も prepared statement 化できるなら理想だが、countNum に応じてプレースホルダ数が毎回変わるため、まずは raw SQL 実行を採用する。
• 将来的には「可変長 VALUES を binding できる prepared raw SQL API」があると望ましい。

withConn の使い方:

• 現在の update は 1 件ごとに withConn を呼んでいるが、改善版では request 単位で 1 回だけ呼ぶ。
• update2 型の「stmt ごとに connection を取り直す」経路は benchmark では使わない。
• queries も同じ思想で、必要なら request 単位の withConn + 直列 SELECT に寄せる。

期待する効果:

• getFreeConn / returnConn の回数が大幅に減る。
• request 内 DB fan-out がなくなり、HTTP concurrency と DB concurrency の二重増幅を防げる。
• prepared statement の接続局所性が上がる。
• UPDATE 往復回数が 1 回になり、PostgreSQL 側の parse/bind/execute 負荷も減る。

副作用と注意点:

• request 内部の並列性は落ちるが、もともと updates は DB 待ち主体なので、接続競合減少の効果が勝つ可能性が高い。
• bulk update SQL が長くなるため、countNum = 500 でも問題ない長さかを確認する。
• duplicate id が発生しうるので、verify への影響を確認する。
• SELECT 結果そのものはレスポンスに使わなくても、verify 上必要な「実際に read した事実」を崩さないように維持する。

実装ステップ:

1. benchmark_controller.nim に WorldUpdateRow と bulk update SQL 組み立て helper を追加する。
2. update を「request 単位で withConn 1 回」に書き換える。
3. update2 は比較用として残すか、意図がわかるコメントをつける。
4. queries についても内部 fan-out をやめる候補として別途比較する。
5. 実測して、現行 update / 改善版 update / update2 の差を確認する。

実装結果

• update は withConn で 1 接続に固定し、SELECT を直列実行したうえで、WITH ... DISTINCT ON の bulk update を 1 回だけ投げる実装に変更した。
• update2 は比較用の個別更新経路として、同じ withConn 上で SELECT + UPDATE を直列実行する形に変更した。
• db / query / fortune も withConn 上の prepared statement 実行へ寄せ、リクエスト内の接続移動をなくした。
• maxConnections は release 時に 64、debug 時に 16 へ引き下げた。

計測観点:

• RPS
• latency
• PostgreSQL の active connection 数
• pool timeout の有無
• verify pass / fail
• countNum=1, 20, 100, 500 での劣化カーブ

判断基準:

• countNum が大きいケースで改善版が安定して速いなら採用する。
• countNum=1 だけ微差で遅くても、TFB 全体スコアで勝つなら許容する。
• verify 安定性を落とす変更は採用しない。

実装優先順位

1. benchmark_controller.nim の updates を bulk update 化して verify fail を解消する。
2. db / queries / fortune を prepared statement 化し、HTTP あたりの SQL 構築コストを下げる。
3. config/database.nim の maxConnections を保守的な値へ調整し、再計測する。
4. allographer の silent failure を例外化する。
5. allographer の prepared cache / logical close / 接続固定 API を設計どおり進める。