Turso入門 - Remote・Local・Sync用SDKの選び方

7分 で読める | 2024.12.30

公式ドキュメント
DB

TursoはSQLite互換のdatabaseとcloud serviceを提供します。現行のTypeScript SDKは、remote接続、local database、cloud syncでpackageが分かれます。libSQLはSQLiteをforkした先行projectで、@libsql/clientは既存コードやORMとの互換用途で引き続き利用できます。

SQLite本体との違い

記事情報: 2024年12月30日初出。TursoとlibSQLの公式資料を2026年7月25日に再確認しています。

SQLite本体の用途と制約は、**SQLiteの選び方**へ分離しました。ここではTurso・libSQL固有の導入だけを扱います。

Turso Database engine、libSQL、SQLite本体は同一productではありません。使用するdriver、extension、pragma、replication機能の対応は、選んだSDKの資料で確認します。

Remote Databaseへ接続する

Turso CLIでdatabaseを作り、接続URLとtokenを取得できます。command名や認証手順はCLI versionで変わるため、現在のquickstartを基準にしてください。

新規のremote接続では、server、container、serverless、edgeに対応する@tursodatabase/serverlessが公式の案内です。

npm install @tursodatabase/serverless

import { connect } from "@tursodatabase/serverless";

const db = connect({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

const statement = await db.prepare(
  "SELECT id, title FROM notes WHERE id = ?",
);
const note = await statement.get([1]);
console.log(note);

値はplaceholderで渡し、user inputをSQL文字列へ連結しません。URLとtokenをbrowser bundleへ埋め込まず、serverのsecret管理に置きます。

tokenはpermissionと有効期限を必要最小限にし、漏えい時にrevoke・rotateできる運用を用意します。frontendから直接databaseへ接続する設計では、認証・認可境界を特に慎重に確認します。

Schema migration

application起動時に全instanceが同時にDDLを実行する構成は避け、deployment jobなど1つの経路へ集約します。

CREATE TABLE notes (
  id INTEGER PRIMARY KEY,
  title TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

ORMを使う場合も、生成SQLをreviewし、stagingで適用時間とrollback方針を確認します。SQLite互換だからlocal SQLite fileのmigrationを無条件に流用できるとは限りません。

Local DatabaseとCloud Sync

新規projectでapplication内のlocal databaseだけを使う場合は@tursodatabase/database、localでread・writeしながらTurso Cloudと明示的にpush・pullする場合は@tursodatabase/syncを選びます。両者を同じpackageとして扱わず、offline時のwriteとconflict処理を要件に含めてください。

既存のlibSQL clientとEmbedded Replica

@libsql/clientは、既存コードやDrizzle・PrismaなどのORMとの互換性が必要な場合に使います。従来のEmbedded Replicaではlocal replicaからreadし、writeをremoteへ送ります。新規の同期用途では、local writeと明示的なpush・pullに対応する@tursodatabase/syncを先に評価してください。

npm install @libsql/client

import { createClient } from "@libsql/client";

const db = createClient({
  url: "file:local.db",
  syncUrl: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

await db.sync();

これは互換経路の例です。利用可能なoptionと同期単位は、使用するclient versionの公式referenceを確認してください。

Consistencyを設計する

local dataはcloud側の最新状態と常に一致するとは限りません。write直後に別processや別regionから読む場合、同期前の値が見える可能性を考えます。

次を要件として明確にします。

  • write後に同じrequestで何を読むか
  • replicaをいつsyncするか
  • offline時にreadを許すか
  • remote write失敗をどう表示するか
  • local fileを失ったとき再作成できるか

「edge replicaだから自動的に高速かつstrong consistency」とは限りません。read latencyとdata freshnessのtradeoffをtestします。

Transactionとbatch

複数statementをまとめる必要がある場合はclientが提供するbatch・transaction APIを使います。remote接続ではnetwork failureやtimeoutがあるため、処理が成功したか不明な状態も考えます。

再試行するwriteにはidempotency keyやunique constraintを用意し、同じ処理が二重適用されないようにします。長いtransaction内で外部APIを待たないことも重要です。

ORMとの統合

DrizzleやPrismaなど、libSQL driverを持つORMでは@libsql/clientを使います。新しいTurso Database SDKのORM対応は同一ではないため、使用するORMとadapterの公式資料を確認してください。

  • transaction API
  • migration tool
  • RETURNING
  • relation query
  • binary・date型の変換
  • edge runtimeでの接続方法

ORMの一般記事ではなく、使用versionのlibSQL adapter資料を確認します。まずclient単体で接続・error・transactionを理解してからORMを重ねると問題を切り分けやすくなります。

Platform機能を分けて考える

Tursoのgroup、location、branch、organization、billingなどはmanaged platformの機能です。提供範囲や料金は変更されるため、固定値を記事へ埋め込まず公式dashboard・pricingを確認してください。

branchをtest databaseとして使う場合も、production dataの複製範囲、個人情報のmask、削除期限を決めます。regionを増やす場合は、read経路だけでなくwrite primaryまでのlatencyも測ります。

導入チェックリスト

  1. SQLite本体ではなくTursoが必要な理由を決める
  2. remote、local、cloud sync、ORM互換のどれが必要かを選ぶ
  3. URL・tokenをsecretとして管理する
  4. schema migrationの単一実行経路を作る
  5. write後readと同期遅延をtestする
  6. network分断、timeout、token失効をtestする
  7. backup・restore・export方法を確認する
  8. 利用量と料金をmonitorする

Tursoは、SQLite互換のSQLをremote、local、cloud syncの用途で使う選択肢です。remoteやsyncを選ぶと、SQLite fileを直接使う構成にnetwork、authentication、同期、service運用が加わります。その追加要素がapplication要件に必要かで判断してください。

production導入前には、現在のservice仕様とclient versionを固定し、障害時に通常のSQLiteへ戻せると仮定せず復旧手順を確認します。

参考リソース

おすすめ記事

← 一覧に戻る
PR
PR
PR
PR