
グローバルなアプリケーションで5ms未満のデータアクセスレイテンシーを達成するには、データをユーザーに近づける必要があります。従来の集中型データベースアーキテクチャでは、リードレプリカを使用しても、エッジではネットワークオーバーヘッドが許容できないレベルになります。libSQL(SQLiteのフォーク)上に構築されたTursoは、組み込みレプリカを備えた分散SQLiteという魅力的なソリューションを提供します。このアーキテクチャにより、ローカルでの低レイテンシー読み取りが可能になり、プライマリ委任を通じて書き込みの強力な一貫性が維持されます。このガイドでは、Tursoと組み込みレプリカの実践的な実装について、デプロイ、レイテンシー測定、書き込み処理、オフライン同期、移行戦略を網羅して詳しく説明します。
Generate tuned WAL, busy_timeout, cache & mmap configs
Fine-tune SQLite for high concurrency. Configure WAL mode, 5000ms busy timeout, 64MB cache, and generate production connection snippets for Python, Node.js, Go, and Rust.
Tursoの核となる強みは、プライマリ・レプリカモデルにあります。単一のプライマリデータベースがすべての書き込みを処理し、ACID準拠と強力な一貫性を保証します。一方、リードレプリカは、エッジワーカー内に直接組み込むなど、グローバルにデプロイできます。この組み込みは非常に重要です。読み取り操作のネットワークホップを排除し、ローカルディスク速度でのアクセスを実現します。
まず、Turso CLIをインストールし、データベースを作成します。
# Install Turso CLI
curl -sSfL https://get.tur.so/install.sh | bash
# Authenticate
turso auth login
# Create a database in a primary region (e.g., 'ord' for Chicago)
turso db create my-edge-app-db --location ord
# Create a read replica in an edge region (e.g., 'syd' for Sydney)
turso db replicate my-edge-app-db --location syd
# Get connection URL and auth token for the primary
turso db shell my-edge-app-db
# In the shell, run:
# .connection-url
# .auth-token
# Exit the shell
プライマリデータベースのURLと認証トークンは安全に保管してください。組み込みレプリカには、別の接続文字列を使用します。
libsql-clientライブラリは、必要なインターフェースを提供します。
// src/lib/turso.ts
import { createClient, Client } from '@libsql/client';
let tursoClient: Client | null = null;
export function getTursoClient(
url: string = process.env.TURSO_DATABASE_URL!,
authToken: string = process.env.TURSO_AUTH_TOKEN!
): Client {
if (!tursoClient) {
if (!url || !authToken) {
throw new Error('TURSO_DATABASE_URL and TURSO_AUTH_TOKEN must be set.');
}
tursoClient = createClient({
url,
authToken,
});
}
return tursoClient;
}
// Example usage (e.g., in an API route)
// const db = getTursoClient();
// const result = await db.execute('SELECT * FROM users');
エッジアプリケーション向けのTursoの真の力は、レプリカを組み込むことにあります。これは、SQLiteデータベースファイルがエッジワーカーによってローカルで管理され、プライマリと同期することを意味します。
Cloudflare Workersはステートフルアプリケーション向けにDurable Objectsを提供しますが、単純な組み込みレプリカの場合、Workerのファイルシステム(利用可能な場合、または一時的なレプリカ向けにローカルのインメモリ/一時ファイルシステム)を活用するか、より実用的にlibsql-clientのローカルレプリカ機能を使用できます。
libsql-clientは、「ローカルレプリカ」モードで動作するように構成でき、ローカルのSQLiteファイルを維持し、リモートのTursoプライマリと同期します。
// src/lib/turso-edge.ts
import { createClient, Client } from '@libsql/client';
import { fileURLToPath } from 'url';
import path from 'path';
// For Cloudflare Workers, you might need to use a different storage mechanism
// or rely on the remote replica for reads if true local file system access is limited.
// This example assumes a Node.js-like environment where file system access is possible.
// For Workers, consider using a remote replica URL directly or Durable Objects for state.
// In a Node.js environment (e.g., Vercel Edge Functions with Node.js runtime)
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const DB_PATH = path.join(__dirname, '../../data/local.db'); // Path to store the local SQLite file
let edgeTursoClient: Client | null = null;
export function getEdgeTursoClient(
syncUrl: string = process.env.TURSO_DATABASE_URL!, // Primary URL for synchronization
authToken: string = process.env.TURSO_AUTH_TOKEN!,
localDbPath: string = DB_PATH // Path for the local SQLite file
): Client {
if (!edgeTursoClient) {
if (!syncUrl || !authToken) {
throw new Error('TURSO_DATABASE_URL and TURSO_AUTH_TOKEN must be set for edge client.');
}
// Initialize the client in local replica mode
edgeTursoClient = createClient({
url: `file:${localDbPath}`, // Connect to a local SQLite file
syncUrl, // URL of the primary database for synchronization
authToken,
syncInterval: 5000, // Sync every 5 seconds (adjust as needed)
});
// Start synchronization immediately
edgeTursoClient.sync();
}
return edgeTursoClient;
}
// Example usage in an edge function
// import { getEdgeTursoClient } from '../lib/turso-edge';
//
// export default async function handler(req: Request) {
// const db = getEdgeTursoClient();
// try {
// const start = performance.now();
// const result = await db.execute('SELECT * FROM products WHERE category = ?', ['electronics']);
// const end = performance.now();
// console.log(`Read latency: ${end - start}ms`);
// return new Response(JSON.stringify(result.rows), { status: 200 });
// } catch (error) {
// console.error('Edge DB error:', error);
// return new Response('Internal Server Error', { status: 500 });
// }
// }
エッジ環境における重要な考慮事項:
libsql-clientを構成して、最も近いTursoリードレプリカURLに直接接続します。「組み込み」ではありませんが、地理的には近いです。/tmpに書き込むことができます。これは一時的ですが、レプリカがリクエストごとに初期化および同期される場合(効率は低い)、単一の関数呼び出しには十分です。永続的な状態には、外部ストレージまたはリモートレプリカが推奨されます。syncIntervalは、ローカルレプリカがプライマリから変更をプルする頻度を定義します。重要な読み取りの場合、読み取り前に手動でdb.sync()をトリガーするかもしれませんが、これはレイテンシーを追加します。エッジ読み取りでは、最終的な一貫性が標準です。5ms未満のレイテンシーを実証するには、getEdgeTursoClientの例を、ローカルファイルシステムアクセスをサポートする環境(例:ローカルのNode.jsサーバー、または一時データ用の/tmpパスを持つVercel Edge Function)にデプロイします。
// src/pages/api/products.ts (Example Vercel Edge Function)
import type { NextRequest } from 'next/server';
import { getEdgeTursoClient } from '../../lib/turso-edge';
export const config = {
runtime: 'edge', // This ensures it runs on the Vercel Edge Network
};
export default async function handler(req: NextRequest) {
const db = getEdgeTursoClient(); // This will initialize and sync the local replica
try {
const start = performance.now();
// Ensure your database has a 'products' table with some data
await db.execute(`
CREATE TABLE IF NOT EXISTS products (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
category TEXT NOT NULL,
price REAL NOT NULL
);
`);
await db.execute(`
INSERT OR IGNORE INTO products (id, name, category, price) VALUES
(1, 'Laptop Pro', 'electronics', 1200.00),
(2, 'Mechanical Keyboard', 'peripherals', 150.00);
`);
const result = await db.execute('SELECT * FROM products WHERE category = ?', ['electronics']);
const end = performance.now();
const latency = end - start;
console.log(`Edge Read Latency: ${latency.toFixed(2)}ms`);
return new Response(JSON.stringify({
data: result.rows,
latency: `${latency.toFixed(2)}ms`,
source: 'edge_replica'
}), {
status: 200,
headers: {
'Content-Type': 'application/json',
},
});
} catch (error: any) {
console.error('Edge DB error:', error);
return new Response(JSON.stringify({ error: error.message }), {
status: 500,
headers: {
'Content-Type': 'application/json',
},
});
}
}
これをローカルで実行するか、Vercel Edgeにデプロイすると、クエリの複雑さと環境に応じて、読み取りレイテンシーが5ms未満、場合によっては1ms未満になることがよくあります。これは、データがネットワーク経由ではなく、ローカルファイルから読み取られているためです。
すべての書き込み操作は、強力な一貫性を維持するためにTursoプライマリデータベースに指示される必要があります。libsql-clientは、ローカルレプリカのsyncUrlを指定できるようにすることで、これを簡素化します。これは書き込みに使用されます。
createClientをfile: URLとsyncUrlで使用すると、クライアントは書き込みをsyncUrl(プライマリ)に自動的に委任します。
// src/lib/turso-write.ts
import { getEdgeTursoClient } from './turso-edge'; // Re-use the edge client setup
export async function createProduct(name: string, category: string, price: number) {
const db = getEdgeTursoClient(); // This client is configured to delegate writes
try {
const start = performance.now();
const result = await db.execute(
'INSERT INTO products (name, category, price) VALUES (?, ?, ?)',
[name, category, price]
);
const end = performance.now();
console.log(`Write operation to primary latency: ${end - start}ms`);
return result;
} catch (error) {
console.error('Write error:', error);
throw error;
}
}
// Example usage in an API route:
// import { createProduct } from '../../lib/turso-write';
//
// export default async function handler(req: Request) {
// if (req.method !== 'POST') {
// return new Response('Method Not Allowed', { status: 405 });
// }
// const { name, category, price } = await req.json();
// try {
// await createProduct(name, category, price);
// return new Response('Product created successfully', { status: 201 });
// } catch (error) {
// return new Response('Failed to create product', { status: 500 });
// }
// }
書き込み操作のレイテンシーは、プライマリデータベースへのネットワークラウンドトリップを伴うため、ローカル読み取りよりも自然に高くなります。これは、強力な一貫性のための本質的なトレードオフです。
組み込みレプリカモデルは、オフラインファースト機能を本質的にサポートしています。エッジワーカーまたはクライアントアプリケーションがネットワーク接続を失った場合でも、ローカルレプリカから読み取りを継続できます。接続が復元されると、libsql-clientはプライマリとの同期を自動的に試行します。
クライアントサイドアプリケーション(例:Electron、モバイルアプリ)の場合、libsql-clientを直接使用して、Tursoと同期するローカルSQLiteデータベースを管理できます。
// Example: Client-side offline-first setup (e.g., in an Electron app)
import { createClient } from '@libsql/client';
import path from 'path';
import { app } from 'electron'; // Assuming Electron context
const userDataPath = app.getPath('userData');
const localDbPath = path.join(userDataPath, 'my-app-offline.db');
const offlineClient = createClient({
url: `file:${localDbPath}`,
syncUrl: process.env.TURSO_DATABASE_URL!,
authToken: process.env.TURSO_AUTH_TOKEN!,
syncInterval: 10000, // Sync every 10 seconds when online
});
// Start synchronization
offlineClient.sync();
// Application logic can now read/write to offlineClient
// Writes will be queued and sent to primary when online.
// Reads will be served from local DB.
このセットアップは、断続的なネットワークアクセスでも回復力とスムーズなユーザーエクスペリエンスを提供します。
NeonやSupabaseのようなPostgreSQLベースのサービスからTursoへの移行には、スキーマ変換とデータ転送が含まれます。
SQLiteのSQL方言はPostgreSQLとほぼ互換性がありますが、違いがあります。
TEXT、VARCHAR、INTEGER、BOOLEANはうまくマッピングされます。UUIDはTEXTになります。JSONBはTEXTになります(JSON文字列として保存)。ARRAY型はシリアル化する必要があります(例:JSON文字列)。SERIALまたはGENERATED BY DEFAULT AS IDENTITYを使用します。SQLiteはINTEGER PRIMARY KEY AUTOINCREMENTを使用します。GEN_RANDOM_UUID()、NOW())は、SQLiteの同等物またはアプリケーションレベルの処理が必要です。CHECK制約、FOREIGN KEY制約はサポートされていますが、動作が若干異なる場合があります。CREATE INDEX構文は互換性があります。スキーマ変換の例:
-- PostgreSQL Schema
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email TEXT UNIQUE NOT NULL,
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- Turso (SQLite) Schema
CREATE TABLE users (
id TEXT PRIMARY KEY, -- UUIDs stored as TEXT
email TEXT UNIQUE NOT NULL,
created_at TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')) -- ISO 8601 format
);
PostgreSQLからのエクスポート: pg_dumpを使用して、インポートに適した形式でデータをエクスポートします。CSVが最も簡単な場合が多いです。
pg_dump -d your_db_name -t users --data-only --column-inserts > users_data.sql
または、CSVの場合:
COPY users TO '/tmp/users.csv' WITH (FORMAT CSV, HEADER);
Tursoへのインポート:
CSVインポート: CSVにエクスポートした場合、CSVを読み取り、Tursoに挿入するスクリプトを作成できます。
// src/scripts/importUsers.ts
import fs from 'fs';
import csv from 'csv-parser';
import { getTursoClient } from '../lib/turso'; // Use the primary client
async function importUsers() {
const db = getTursoClient();
const users: any[] = [];
fs.createReadStream('/tmp/users.csv')
.pipe(csv())
.on('data', (row) => {
users.push(row);
})
.on('end', async () => {
console.log(`Importing ${users.length} users...`);
for (const user of users) {
await db.execute(
'INSERT INTO users (id, email, created_at) VALUES (?, ?, ?)',
[user.id, user.email, user.created_at]
);
}
console.log('Users imported successfully.');
});
}
importUsers().catch(console.error);
SQLインポート: pg_dumpをINSERTステートメントで使用した場合、SQLiteの互換性のためにSQLを手動で調整する必要があるかもしれません(例:IDの場合、UUIDをTEXTに、NOW()をstrftimeに)。その後、Turso CLIまたはlibsql-clientを介してSQLファイルを実行できます。
# Via Turso CLI
turso db shell my-edge-app-db < users_data_sqlite_compatible.sql
| 機能 | Turso (libSQL) | PostgreSQL (Neon/Supabase) |
|---|---|---|
| アーキテクチャ | プライマリ・レプリカ、組み込みエッジレプリカ | プライマリ・レプリカ、論理レプリケーション |
| 読み取りレイテンシー (エッジ) | 5ms未満 (ローカルファイルアクセス) | 10-50ms以上 (最寄りのレプリカへのネットワーク) |
| 書き込みレイテンシー | 20-100ms以上 (プライマリへのネットワーク) | 20-100ms以上 (プライマリへのネットワーク) |
| 一貫性モデル | 強力 (書き込み)、最終的 (レプリカからの読み取り) | 強力 (すべての操作) |
| データモデル | リレーショナル (SQLite方言) | リレーショナル (PostgreSQL方言)、JSONB |
| オフラインサポート | 非常に優れている (ローカルファイル同期) | 限定的 (クライアントサイドのキャッシュ/同期レイヤーが必要) |
| スケーラビリティ | 読み取りはレプリカで水平にスケール | 読み取りはレプリカで水平にスケール |
| 複雑さ | エッジ向けにシンプル、レプリケーションを内部で管理 | エッジ向けに複雑、オフラインには外部同期が必要 |
| コストモデル | 使用量ベース (読み取り/書き込み/ストレージ) | 使用量ベース (コンピューティング/ストレージ/データ転送) |
libsql-clientインスタンスが1つだけであることを確認してください。createClient({ url: 'file:my.db?busy_timeout=5000' })。syncIntervalが高すぎるか、レプリカが最近同期されていない。syncIntervalを減らしてください。db.sync()をトリガーしてください。TURSO_DATABASE_URLまたはTURSO_AUTH_TOKENが見つからない:
file: URLの問題:
/tmpは書き込み可能ですが一時的です。これは、レプリカがコールドスタートごとに再同期され、最初の数リクエストのレイテンシーが増加することを意味します。file: URLの代わりにリモートのTursoリードレプリカURLに直接接続してください。これにより、地理的な近接性は維持されます。グローバルなEコマースアプリケーションがTursoを使用しており、プライマリデータベースは「us-east」にあり、埋め込みレプリカが世界中のエッジワーカーにデプロイされています。シドニー、オーストラリアのユーザーがカートにアイテムを追加し(書き込み操作)、その後すぐにカートページに移動します(読み取り操作)。これら2つの操作の最も可能性の高いレイテンシプロファイルは何ですか?
ALTER TABLEステートメントを使用できます。より複雑な移行には、sqldefのようなツールやカスタムスクリプトを検討してください。AI CLIログの整形、Cron式の作成、JWTの解析、chmod権限の計算をオフラインで実行。

PrismaとTypeScriptを使った最新のデータベースシーディング戦略を網羅的に解説。冪等性、Faker.js連携、複雑なリレーショナルデータの扱い、大規模なシードスクリプトのパフォーマンス最適化について探ります。
続きを読む
Node.jsからBun 1.2への本番環境移行を網羅したガイドで、フルスタックHTTP、SQLite、パッケージパフォーマンスを本番環境レベルのアーキテクチャとコード例で解説します。
続きを読む
WarpStream、Redpanda、KafkaのZero-Disk S3イベントストリーミングにおけるコストとレイテンシを、本番環境レベルのアーキテクチャとコード例で比較する包括的なガイド。
続きを読む