Turso Embedded Replicaで書籍DBを移行した

edinet-apiリポジトリのドキュメント整理から始まって、book-knowledge-baseのTurso移行を一気に進めた。税法入門のPDF 107ページをOCRにかけ、Turso DBに流し込み、devサーバーで書籍一覧が表示されるところまで持っていった。ポート番号の衝突で3回やり直す羽目になったが、最終的にページナビゲーションもコンテンツ表示も動いている。

Embedded Replicaのドキュメント整理

edinet-apiリポジトリに turso-embedded-replica-windows-guide.md を作成した。前日までの試行錯誤で得た知見を整理する目的。Windows環境でのlibsqlパッケージ選定、接続コード、sync周りの挙動をまとめた。

これを書いている途中で、レプリカディレクトリの配置が気になり始めた。

レプリカディレクトリの配置見直し

当初は ~/.turso-replicas/ にレプリカDBファイルを置いていた。ホームディレクトリ直下のドットディレクトリ。設定ファイルと同じ感覚で置いたが、実際にはDBファイルは数十MBのデータであって設定ではない。

Git_repo/turso-replicas/ に移した。理由は2つ:

1. 開発リポジトリ群と同じ階層に置く: 他のリポジトリからの相対パスが予測しやすい
2. バックアップの対象に含めやすい: Git_repo配下なら既存のバックアップフローに乗る

サイズ確認

ローカルSQLiteのサイズを確認した。16冊分のOCRデータを含めて約20MB。Turso無料枠は5GB。余裕がある。当面はコスト面を気にせず使える。

turso-replicas リポジトリの初期化

Git_repo/turso-replicas/ を新規リポジトリとして初期化し、以下のファイルを作成した:

• .env: Turso URLとAuth Tokenの定義
• .gitignore: .env と *.db をトラッキング対象外に
• FTS5検証スクリプト: libsql経由でFTS5テーブルを作成し、全文検索が動くか確認するPythonスクリプト
• 計画書: 移行手順のステップを箇条書きで整理

FTS5検証スクリプトを回して、Turso上でも全文検索が問題なく動くことを確認した。前日のCodexレビューで「FTS5の互換性が未検証」と指摘されていた点を潰した形になる。

税法入門のOCRとDB格納

PDFのリネームとOCR

「税法入門 令和8年度版」のPDFをリネームしてからyomitoku OCRにかけた。

• 107ページ: テキスト抽出
• 14図ファイル: 図表の画像を個別に切り出し

yomitokuの処理自体は安定していた。107ページを通しで回して、途中でエラー落ちすることなく完走した。

Turso DBへの格納

OCR結果をパースして、ページ単位でTurso DBにINSERTした。書籍メタデータ（タイトル、著者、ページ数）と、各ページのテキストコンテンツを別テーブルに分けている。

格納完了後、FTS5インデックスの再構築を走らせた。「所得税」で検索すると該当ページがヒットすることを確認。

Chrome DevToolsでのdev表示確認

ここからが一番手間取った。book-knowledge-baseのdevサーバーを起動してChrome DevTools MCPで表示を確認しようとしたが、ポート番号で3回転んだ。

ポート3000: 既に使用中

Nuxtのデフォルトポート3000でdevサーバーを起動しようとしたら、既に別のプロジェクト（mdx-playground）が使っていた。エラーメッセージを見て即座にポートを変更。

ポート3001: これも塞がっていた

3001に切り替えて起動。今度は起動自体は通ったが、Chrome DevToolsで接続しようとするとタイムアウトした。調べると別プロセスが3001を掴んでいた。

ポート3003: ようやく通った

3003まで飛ばしてようやくdevサーバーが起動し、Chrome DevToolsからの接続も通った。ポートの空き状況を先に確認すべきだった。

# 次回からはこれを先に叩く
powershell "Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -lt 10000 }"

表示確認の結果

Chrome DevToolsで以下を確認した:

• 書籍一覧ページ: 登録済みの書籍がカード形式で並ぶ。税法入門が追加されている
• ページナビゲーション: 前後ページへの移動が動作する。107ページの最終ページまで辿れる
• コンテンツ表示: OCRテキストがページ単位で表示される。図の参照箇所も画像として埋め込まれている

全て正常動作を確認した。

学びメモ

• レプリカ配置はプロジェクト群の近くに: ホームディレクトリのドットフォルダに隠すと、存在を忘れる。目に入る場所に置いた方が管理が続く
• ポートの空き確認は起動前に: 「3000が空いてるだろう」という思い込みで3回サーバーを再起動した。Get-NetTCPConnection を先に叩くだけで数分節約できた
• FTS5の互換性は実際にクエリを投げて確かめる: ドキュメントに「対応」と書いてあっても、実環境で検索結果が返ってくるまでは安心しなかった。前日にCodexから指摘を受けていなければ、ここまで丁寧に検証しなかったと思う

今日の作業まとめ