🗄️ Turso × SvelteKit 完全ソースコード徹底解説

Turso は libSQL（SQLite のオープンフォーク）を基盤とするエッジ対応のクラウドデータベースサービスです。 ChiselStrike 社（現 Turso 社）が SQLite をサーバーサイド・分散環境で使えるように拡張した libSQL に、クラウドホスティング・レプリケーション・エッジ実行能力を重ねたのが Turso の本質です。

なぜ SQLite（libSQL）か

SQLite は「単一ファイルで完結する」「ゼロ運用（サーバープロセス不要）」「ACID トランザクション」という3つの特性を持つ唯一の組み込みデータベースです。 Postgres や MySQL のように常駐デーモンを立てる必要がなく、開発環境でもファイルを1つ置くだけで本番同等の SQL が動きます。 Turso はこの超軽量な特性を保ちながら、クラウド上での HTTP/WebSocket プロトコル越しアクセスと複数リージョンへのレプリケーションを実現しています。

競合サービス比較

Turso 独自機能

• Embedded Replicas — アプリケーションプロセスと同じホスト上にローカル SQLite ファイルとして DB を複製し、読み取りをマイクロ秒単位で完結させる機能。 VM・VPS・モバイルアプリで特に有効。Reads are served from the local file; writes propagate to the remote primary（公式ドキュメント準拠）。
• Multi-DB-per-organization — 1 つの Turso 組織アカウントで複数（無料プランは 100 個、上位プランは無制限）の独立した DB を管理できる。マルチテナント SaaS に最適。
• DB Branching — 本番 DB をブランチとして分岐させ、スキーマ変更のテストや PR ごとのプレビュー環境を作成できる（Neon の branching に相当する機能）。
• Groups — 複数 DB を1つのグループにまとめ、同一ロケーション設定・共有 WAL ファイルで管理する機能。グループ単位でロケーションを追加すると全 DB にレプリカが展開される。

料金プラン（2025年5月時点・公式ページ準拠）

出典: https://turso.tech/pricing（2025年5月時点）

Turso CLI インストール

Turso CLI は Homebrew（macOS）または curl スクリプト（Linux / WSL）でインストールします。Windows ネイティブ（WSL なし）の場合は PowerShell スクリプトを使います。

macOS（Homebrew）

brew install tursodatabase/tap/turso

Linux / WSL（curl スクリプト）

curl -sSfL https://get.tur.so/install.sh | bash

Windows ネイティブ（PowerShell）

irm get.tur.so/install.ps1 | iex

サインアップ / ログイン

初回はブラウザが開き、GitHub や Google アカウントで認証します。

# 新規登録（ブラウザが開く）
turso auth signup

# 既存アカウントでログイン
turso auth login

# ログイン状態確認
turso auth whoami

データベース作成

--location フラグでリージョンを指定します。 指定しない場合は CLI の実行地点に最も近いリージョンが自動選択されます。 日本からアクセスする場合は nrt（東京）を明示するのがベストプラクティスです。

# 東京リージョンで DB を作成
turso db create my-svelte-db --location nrt

# DB 一覧を確認
turso db list

# 特定グループ内の DB だけ確認
turso db list --group my-group

主要リージョンコード

全ロケーション一覧: turso db locations コマンドで確認可能。

接続 URL と認証トークンの取得

SvelteKit の環境変数に設定する2つの値を取得します。

# DB の詳細情報（URL を含む）を表示
turso db show my-svelte-db

# URL だけを取り出す（環境変数にコピーしやすい形式）
turso db show my-svelte-db --url

# 認証トークン生成（デフォルトは無期限）
turso db tokens create my-svelte-db

# 有効期限付きトークン（例: 7日間）
turso db tokens create my-svelte-db --expiration 7d

インタラクティブシェルで動作確認

CLI から直接 SQL を実行して DB の動作確認ができます。

# シェルに接続
turso db shell my-svelte-db

# シェル内で SQL を実行（例）
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
INSERT INTO users VALUES (1, 'Alice');
SELECT * FROM users;

# シェルを終了
.quit

プロジェクト作成

Bun または npm でプロジェクトを作成します。本ガイドでは Bun を推奨します（Windows でもほぼ同等に動作）。

Bun（推奨）

bun create svelte@latest my-app
cd my-app
bun install

npm（代替）

npm create svelte@latest my-app
cd my-app
npm install

対話式セットアップで以下を選択します:

• Which Svelte app template? → Skeleton project（最小構成）
• Add type checking with TypeScript? → Yes, using TypeScript syntax
• Add ESLint? → Yes
• Add Prettier? → Yes
• Add Vitest? → プロジェクト規模に応じて任意

Turso クライアント・ORM のインストール

@libsql/client は Turso（libSQL）へ接続するための公式 TypeScript クライアントです。 Drizzle ORM を使う場合は追加で drizzle-orm と drizzle-kit をインストールします。

# Turso 公式クライアント（必須）
bun add @libsql/client

# Drizzle ORM（スキーマ型安全化・マイグレーション管理に推奨）
bun add drizzle-orm
bun add -D drizzle-kit

推奨フォルダ構成

DB 接続ロジックは必ず src/lib/server/ 配下に置きます。 SvelteKit は src/lib/server/ をサーバー専用ディレクトリとして扱い、 クライアントバンドルへの混入を ビルド時に静的に防止 します （公式: server-only-modules）。 接続文字列・シークレットが意図せずブラウザに送信されるリスクをゼロにできます。

my-app/
├── src/
│   ├── lib/
│   │   └── server/          ← クライアントに絶対渡らない領域
│   │       ├── db.ts        ← createClient() の初期化
│   │       └── schema.ts    ← Drizzle テーブル定義
│   └── routes/
│       └── +page.server.ts  ← load() / actions() からのみ db を参照
├── drizzle/                 ← drizzle-kit が生成するマイグレーションファイル
├── drizzle.config.ts        ← drizzle-kit の設定
├── .env                     ← シークレット（gitignore 必須）
└── svelte.config.js

svelte.config.js でエイリアス設定

長い相対パスを避けるため、kit.alias でショートカットを定義します。 以下の設定で import { db } from '$db' のように参照できます。

// svelte.config.js
import adapter from '@sveltejs/adapter-auto';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type { import('@sveltejs/kit').Config } */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter(),
    alias: {
      $db: 'src/lib/server/db.ts',
      $schema: 'src/lib/server/schema.ts'
    }
  }
};

export default config;

.env ファイルの設定

プロジェクトルートに .env ファイルを作成し、SEC2 で取得した2つの値を書き込みます。 このファイルは必ず .gitignore に含め、リポジトリにコミットしてはなりません。

# .env  （git に絶対コミットしない）
TURSO_DATABASE_URL="libsql://my-svelte-db-yourname.turso.io"
TURSO_AUTH_TOKEN="eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."

# .gitignore に必ず含めること
.env
.env.local
.env.*.local

SvelteKit の4種環境変数モジュール

SvelteKit は Node.js の process.env を直接使うのではなく、 型安全かつセキュリティ境界が明確な4種類のモジュールを提供しています （参照: svelte.dev/docs/kit/$env-static-private）。

Turso では $env/static/private を使う

$env/static/private はビルド時に値を定数として埋め込みます。 これにより3つのメリットが得られます:

• 型安全: TypeScript の型推論が効き、変数名の typo をビルド時に検出できる
• クライアント完全除外: SvelteKit がビルド時にサーバー専用と判定し、バンドルから削除する（$env/static/private を +page.svelte からインポートするとビルドエラーになる）
• デッドコード除去: 値が定数になるため、未使用の環境変数参照が最適化される

// src/lib/server/db.ts
import { createClient } from '@libsql/client';
import { TURSO_DATABASE_URL, TURSO_AUTH_TOKEN } from '$env/static/private';

export const client = createClient({
  url: TURSO_DATABASE_URL,
  authToken: TURSO_AUTH_TOKEN
});

$env/dynamic/private を使うべきケース

Cloudflare Workers / Cloudflare Pages（adapter-cloudflare）にデプロイする場合、環境変数は wrangler.toml のバインディングとして実行時に注入されます。 この場合は ビルド時には値が存在しないため、$env/static/private では取得できません。 代わりに $env/dynamic/private または platform.env を使います。

// Cloudflare Pages 向け: +page.server.ts での例
import { createClient } from '@libsql/client';

export const load = async ({ platform }) => {
  // platform.env は Cloudflare Workers のバインディング
  const db = createClient({
    url: platform?.env?.TURSO_DATABASE_URL ?? '',
    authToken: platform?.env?.TURSO_AUTH_TOKEN ?? ''
  });
  const result = await db.execute('SELECT * FROM users');
  return { users: result.rows };
};

Turso との通信はすべて @libsql/client の createClient() から始まります。 SvelteKit では src/lib/server/db.ts に シングルトンとして配置するのが定石です。

// src/lib/server/db.ts
import { createClient, type Client } from '@libsql/client';
import { TURSO_DATABASE_URL, TURSO_AUTH_TOKEN } from '$env/static/private';

export const db: Client = createClient({‍
  url: TURSO_DATABASE_URL,
  authToken: TURSO_AUTH_TOKEN,
});

// 1. 本番: Turso クラウド（HTTPS + JWT 認証）
url: 'libsql://your-db-name.turso.io'

// 2. ローカル SQLite ファイル（開発・Embedded Replica のローカル側）
url: 'file:local.db'
url: 'file:/absolute/path/to/local.db'

// 3. ローカル sqld 開発サーバー（docker run ghcr.io/tursodatabase/libsql-server）
//    TLS なし → tls: false が必要
url: 'http://127.0.0.1:8080'

// 4. メモリ内 SQLite（テスト用、プロセス終了で消える）
url: ':memory:'

公式 TypeScript SDK Reference に定義された全 API を網羅します。libSQL クライアントが提供するメソッドは execute / batch / transaction / executeMultiple / sync / close の 6 つです。

// シンプル形（パラメータなし）
const result = await db.execute('SELECT * FROM users');

// positional バインド（? プレースホルダー）
const r2 = await db.execute({‍
  sql: 'SELECT * FROM users WHERE id = ? AND active = ?',
  args: [42, 1],
});

// named バインド（:name プレースホルダー）
const r3 = await db.execute({‍
  sql: 'SELECT * FROM users WHERE email = :email',
  args: { email: 'user@example.com' }‍,
});

// rows を型付きオブジェクトに変換
const users = result.rows.map((row) => ({‍
  id:    Number(row.id),
  name:  String(row.name),
  email: String(row.email),
}));

// CREATE TABLE + 複数 INSERT を 1 往復で実行
const results = await db.batch([
  {
    sql: `CREATE TABLE IF NOT EXISTS posts (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            title TEXT NOT NULL,
            body TEXT,
            created_at INTEGER NOT NULL
          )`,
    args: [],
  }‍,
  {
    sql: 'INSERT INTO posts (title, body, created_at) VALUES (?, ?, ?)',
    args: ['First Post', 'Hello Turso!', Date.now()],
  }‍,
  {
    sql: 'INSERT INTO posts (title, body, created_at) VALUES (?, ?, ?)',
    args: ['Second Post', 'SvelteKit is great.', Date.now()],
  }‍,
], 'write');
console.log('挿入行数:', results[1].rowsAffected); // 1
console.log('最初の rowid:', results[1].lastInsertRowid); // 1n

const tx = await db.transaction('write');
try {
  const stockRes = await tx.execute({‍
    sql: 'SELECT stock FROM products WHERE id = ?',
    args: [productId],
  });
  const stock = Number(stockRes.rows[0]?.stock ?? 0);
  if (stock < quantity) {
    await tx.rollback();
    return { error: '在庫不足' };
  }
  await tx.execute({‍
    sql: 'UPDATE products SET stock = stock - ? WHERE id = ?',
    args: [quantity, productId],
  });
  await tx.execute({‍
    sql: 'INSERT INTO orders (product_id, qty, created_at) VALUES (?, ?, ?)',
    args: [productId, quantity, Date.now()],
  });
  await tx.commit();
  return { success: true };
} catch (e) {
  await tx.rollback();
  throw e;
}

// executeMultiple — セミコロン区切り SQL を一括実行（マイグレーション用、パラメータ不可）
await db.executeMultiple(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT UNIQUE NOT NULL,
    created_at INTEGER NOT NULL
  );
  CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
`);

// sync — Embedded Replica のローカルコピーをリモートと手動同期
await db.sync();

// close — クライアントを終了し内部リソースを解放
db.close();

const newId = Number(result.lastInsertRowid); // 安全範囲内の場合
const safe = result.toJSON(); // BigInt が string に変換される

SQL Injection は「ユーザー入力を SQL 文字列に直接埋め込む」ことで発生する最も古典的かつ深刻な脆弱性です。 libSQL では パラメータバインドを使うことで根本的に防止できます。

// ❌ 文字列結合でクエリを組み立てる
const name = formData.get('name');
await db.execute(`SELECT * FROM users WHERE name = '$${name}'`);
// name に  ' OR 1=1 --  が入ると全件流出する

// ✅ positional バインド（? プレースホルダー）
await db.execute({‍
  sql: 'SELECT * FROM users WHERE name = ?',
  args: [name],
});

// ✅ named バインド（:プレースホルダー名）
await db.execute({‍
  sql: 'SELECT * FROM users WHERE email = :email AND active = :active',
  args: { email: userEmail, active: 1 }‍,
});

// ✅ INSERT でも同様
await db.execute({‍
  sql: 'INSERT INTO posts (title, body, user_id) VALUES (?, ?, ?)',
  args: [title, body, userId],
});

// ✅ ESCAPE 句でエスケープする
function escapeLike(str: string): string {
  return str
    .replace(/\/g, '\\')
    .replace(/%/g, '\%')
    .replace(/_/g, '\_');
}

await db.execute({‍
  sql: "SELECT * FROM products WHERE name LIKE ? ESCAPE '\\'",
  args: [`$${escapeLike(userInput)}%`],
});

// ❌ 文字列結合（危険）
// `WHERE id IN ($${ids.join(',')})`

// ✅ ? プレースホルダーを動的に生成
const ids = [1, 2, 3, 4, 5];
const placeholders = ids.map(() => '?').join(', ');

const result = await db.execute({‍
  sql: `SELECT * FROM posts WHERE user_id IN ($${placeholders})`,
  args: ids,
});

const ALLOWED_SORT_COLUMNS = ['name', 'created_at', 'email'] as const;
type SortColumn = typeof ALLOWED_SORT_COLUMNS[number];

function isSortColumn(col: string): col is SortColumn {
  return (ALLOWED_SORT_COLUMNS as readonly string[]).includes(col);
}

const sortBy = url.searchParams.get('sort') ?? 'created_at';
if (!isSortColumn(sortBy)) throw new Error('不正なソート列');
await db.execute(`SELECT * FROM users ORDER BY $${sortBy} DESC`);

libSQL は SQLite 互換のため、型システムも SQLite に準じます。 すべての値は 5 つのストレージクラスのいずれかに収まります （公式: Datatypes In SQLite）。

// Unix epoch ms で保存・取得する（推奨パターン）
await db.execute({‍
  sql: 'INSERT INTO posts (title, created_at) VALUES (?, ?)',
  args: ['Hello', Date.now()],
});
const result = await db.execute('SELECT * FROM posts ORDER BY created_at DESC');
const posts = result.rows.map((row) => ({‍
  title:     String(row.title),
  createdAt: new Date(Number(row.created_at)),
}));

-- 複合主キーで主キー検索が支配的な場合に有効
CREATE TABLE kv_store (
  namespace TEXT NOT NULL,
  key       TEXT NOT NULL,
  value     TEXT,
  PRIMARY KEY (namespace, key)
) WITHOUT ROWID;
-- 注意: INTEGER PRIMARY KEY は WITHOUT ROWID と併用できない（rowid の別名のため）

export const db: Client = createClient({‍
  url: TURSO_DATABASE_URL,
  authToken: TURSO_AUTH_TOKEN,
});
await db.execute('PRAGMA foreign_keys = ON');

-- 通常のインデックス
CREATE INDEX idx_users_email ON users(email);

-- 複合インデックス（user_id で絞り込み + created_at でソート）
CREATE INDEX idx_posts_user_date ON posts(user_id, created_at DESC);

-- 部分インデックス（active = 1 のユーザーのみ → インデックスが小さく高速）
CREATE INDEX idx_active_users ON users(email) WHERE active = 1;

-- UNIQUE 制約付きインデックス
CREATE UNIQUE INDEX idx_users_email_unique ON users(email);

Drizzle ORM は TypeScript-first の SQL クエリビルダー兼 ORM です。SQL 風の DSL でクエリを書くため「Drizzle 独自文法を覚える」コストが低く、生成されるクエリが予測しやすい点が特徴です。libSQL（Turso）に正式対応しており、Edge 環境でも動作します。

なぜ Drizzle を選ぶか

インストール

bun add drizzle-orm @libsql/client
bun add -d drizzle-kit

4ファイル構成の全体像

① drizzle.config.ts

// drizzle.config.ts
import 'dotenv/config';
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/lib/server/schema.ts',
  out: './drizzle',
  dialect: 'turso',
  dbCredentials: {
    url: process.env.TURSO_DATABASE_URL!,
    authToken: process.env.TURSO_AUTH_TOKEN!,
  },
});

dialect: 'turso' を指定することで Drizzle Kit が libSQL 向けの SQL を生成します。out に指定したディレクトリにマイグレーションファイルが出力されます。

② schema.ts — テーブル定義（users + posts・外部キー cascade）

// src/lib/server/schema.ts
import { sqliteTable, text, integer, index } from 'drizzle-orm/sqlite-core';
import { sql } from 'drizzle-orm';
import { relations } from 'drizzle-orm';

export const users = sqliteTable('users', {
  id: text('id').primaryKey(),
  email: text('email').notNull().unique(),
  name: text('name').notNull(),
  createdAt: integer('created_at', { mode: 'timestamp_ms' })
    .notNull()
    .default(sql`(unixepoch() * 1000)`),
}, (t) => ({
  emailIdx: index('users_email_idx').on(t.email),
}));

export const posts = sqliteTable('posts', {
  id: text('id').primaryKey(),
  userId: text('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  title: text('title').notNull(),
  body: text('body').notNull(),
  publishedAt: integer('published_at', { mode: 'timestamp_ms' }),
});

export const usersRelations = relations(users, ({ many }) => ({ posts: many(posts) }));
export const postsRelations = relations(posts, ({ one }) => ({
  user: one(users, { fields: [posts.userId], references: [users.id] }),
}));

export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert;

カラム型モード一覧

③ db.ts — Drizzle インスタンス生成

// src/lib/server/db.ts
import { drizzle } from 'drizzle-orm/libsql';
import { createClient } from '@libsql/client';
import { TURSO_DATABASE_URL, TURSO_AUTH_TOKEN } from '$env/static/private';
import * as schema from './schema';

const client = createClient({ url: TURSO_DATABASE_URL, authToken: TURSO_AUTH_TOKEN });
export const db = drizzle(client, { schema });

{ schema } を渡すことでリレーショナルクエリ（db.query.users.findMany）が使えます。渡さなければ通常の SQL 風クエリのみ利用可能です。

CLI 操作フロー

1. 1

   スキーマ変更後

   bunx drizzle-kit generate

   drizzle/0000_xxx.sql を生成。schema.ts との差分を自動検出して ALTER TABLE / CREATE TABLE を生成する。

2. 2

   開発・本番環境に適用

   bunx drizzle-kit migrate

   未適用のマイグレーション SQL を Turso DB に実行する。__drizzle_migrations テーブルで適用済みを追跡。

3. 3

   データ確認・デバッグ

   bunx drizzle-kit studio

   ローカル Web GUI（https://local.drizzle.studio）が起動し、テーブルの閲覧・編集ができる。本番 DB 確認時にも使える。

型安全 CRUD サンプル集

1. SELECT（where + orderBy + limit）

import { db } from '$lib/server/db';
import { posts, users } from '$lib/server/schema';
import { desc, like, and, eq } from 'drizzle-orm';

const rows = await db
  .select()
  .from(posts)
  .where(and(like(posts.title, '%Turso%'), eq(posts.userId, userId)))
  .orderBy(desc(posts.publishedAt))
  .limit(20);

2. INSERT returning

const [newPost] = await db
  .insert(posts)
  .values({ id: crypto.randomUUID(), userId, title, body, publishedAt: new Date() })
  .returning();

3. UPDATE

await db
  .update(posts)
  .set({ title: newTitle })
  .where(eq(posts.id, postId));

4. DELETE

await db
  .delete(posts)
  .where(eq(posts.id, postId));

5. JOIN（SELECT + innerJoin）

const rows = await db
  .select({
    postTitle: posts.title,
    authorName: users.name,
  })
  .from(posts)
  .innerJoin(users, eq(posts.userId, users.id));

6. リレーショナルクエリ（db.query API）

// schema に relations を定義済みで drizzle(client, { schema }) とした場合のみ使える
const usersWithPosts = await db.query.users.findMany({
  with: { posts: true },
  where: (u, { eq }) => eq(u.email, 'alice@example.com'),
});

SvelteKit の load 関数はページに必要なデータをサーバーまたはクライアントで取得します。Turso（DB）へ直接アクセスするには +page.server.ts を使います。

3種のロード関数の違い

posts 一覧ページの完全コード例

// src/routes/posts/+page.server.ts
import type { PageServerLoad } from './$types';
import { db } from '$lib/server/db';
import { posts, users } from '$lib/server/schema';
import { desc, eq } from 'drizzle-orm';

export const load: PageServerLoad = async ({ url, depends, setHeaders }) => {
  depends('app:posts');
  setHeaders({ 'cache-control': 'private, max-age=10' });

  const limit = Number(url.searchParams.get('limit') ?? 20);
  const rows = await db
    .select({
      id: posts.id,
      title: posts.title,
      author: users.name,
      publishedAt: posts.publishedAt,
    })
    .from(posts)
    .innerJoin(users, eq(posts.userId, users.id))
    .orderBy(desc(posts.publishedAt))
    .limit(limit);

  return { posts: rows };
};

params を使った詳細ページ（[id]）

// src/routes/posts/[id]/+page.server.ts
import { error } from '@sveltejs/kit';
import type { PageServerLoad } from './$types';
import { db } from '$lib/server/db';
import { posts } from '$lib/server/schema';
import { eq } from 'drizzle-orm';

export const load: PageServerLoad = async ({ params }) => {
  const [post] = await db.select().from(posts).where(eq(posts.id, params.id));
  if (!post) throw error(404, 'Post not found');
  return { post };
};

params.id は URL の [id] セグメントに対応します。throw error(404, ...) は SvelteKit のエラーページを表示します。

応用パターン

1. 1

   Streaming load

   重い処理は await しない

   Promise を return すると SvelteKit がストリーミングで解決します。return { fast: await fastQuery(), slow: slowQuery() } と書くと fast は即座にレンダリングし、slow は解決次第差し込まれます。

2. 2

   parent() で親データを取得

   レイアウトの load 結果を継承

   const { user } = await parent(); で +layout.server.ts が返したデータを取得できます。認証ユーザー情報などを共通で使い回すのに最適です。

3. 3

   クライアント側から再フェッチ

   invalidate('app:posts') で再取得

   フォーム送信後などに import { invalidate } from '$app/navigation' を使って invalidate('app:posts') を呼ぶと、ページ遷移なしで load 関数が再実行されます。

SvelteKit の form actions は HTML フォームをサーバーサイドで処理するための仕組みです。use:enhance ディレクティブを組み合わせることで、JavaScript が有効な環境では SPA-like な体験（ページリロードなし）に自動アップグレードされます。

+page.server.ts — actions 定義

// src/routes/posts/new/+page.server.ts
import type { Actions, PageServerLoad } from './$types';
import { fail, redirect } from '@sveltejs/kit';
import { db } from '$lib/server/db';
import { posts } from '$lib/server/schema';

export const actions: Actions = {
  create: async ({ request, locals }) => {
    const data = await request.formData();
    const title = data.get('title')?.toString().trim() ?? '';
    const body = data.get('body')?.toString().trim() ?? '';

    if (title.length < 3 || title.length > 200) {
      return fail(400, { title, body, error: 'タイトルは3〜200文字' });
    }
    if (!locals.user) {
      return fail(401, { error: '未ログイン' });
    }

    const id = crypto.randomUUID();
    await db.insert(posts).values({
      id,
      userId: locals.user.id,
      title,
      body,
      publishedAt: new Date(),
    });

    throw redirect(303, `/posts/$${id}`);
  },
};

+page.svelte — フォーム UI

<!-- src/routes/posts/new/+page.svelte -->
<script lang="ts">
  import { enhance } from '$app/forms';
  let { form } = $props();
</script>

<form method="POST" action="?/create" use:enhance>
  <input name="title" value={form?.title ?? ''}  required />
  {#if form?.error}<p class="text-red-600">{form.error}</p>{/if}
  <textarea name="body">{form?.body ?? ''}</textarea>
  <button type="submit">投稿</button>
</form>

各要素の解説

1. 1

   Progressive Enhancement

   use:enhance の動作

   JavaScript なし環境でも通常の HTML フォームとして動作します。JS が有効な場合は fetch でサブミット → ページリロードなしでレスポンスを処理します。

2. 2

   バリデーションエラー時

   fail() でフォーム値を保持する理由

   fail(400, { title, body, error } ) の第2引数が form プロパティとして返ってきます。これにより入力途中の値が消えず、ユーザーが修正しやすくなります。

3. 3

   成功時のリダイレクト

   redirect() を throw する理由

   throw redirect(303, url) は SvelteKit 内部での型安全な制御フローです。通常の return と区別するため throw を使います。303 は POST 後の GET リダイレクト（PRG パターン）に対応します。

4. 4

   CSRF 対策

   SvelteKit はデフォルトで origin チェック有効

   SvelteKit はリクエストの Origin ヘッダーを検証し、異なるオリジンからの POST を自動で拒否します。csrf.checkOrigin: false にしない限り追加対策は不要です。

複数アクションの定義

export const actions: Actions = {
  create: async ({ request }) => { /* ... */ },
  delete: async ({ request }) => {
    const data = await request.formData();
    const id = data.get('id')?.toString() ?? '';
    await db.delete(posts).where(eq(posts.id, id));
    return { success: true };
  },
  update: async ({ request }) => { /* ... */ },
};

フォーム側からは action="?/delete" のように ?/アクション名 で呼び分けます。複数アクションを1ファイルに集約することで、関連する操作をまとめて管理できます。

ファイルアップロードと BLOB 保存

const data = await request.formData();
const file = data.get('avatar') as File;

if (file && file.size > 0) {
  const buffer = Buffer.from(await file.arrayBuffer());
  // Turso BLOB に直接保存（小サイズ限定）
  await db.update(users).set({ avatar: buffer }).where(eq(users.id, userId));

  // 大サイズは R2 / S3 に委譲してURLだけ保存
  // const url = await uploadToR2(buffer, file.name);
  // await db.update(users).set({ avatarUrl: url }).where(eq(users.id, userId));
}

Embedded Replica は Turso が提供する最も強力な機能の一つです。アプリケーションサーバーと同じホスト上にローカル SQLite ファイルを置き、読み取りをネットワーク往復なしで完結させます。

仕組みの全体像

[SvelteKit Server / Bun / Node.js]
       │
       ├── 読み取り → ローカル SQLite ファイル (local-replica.db)
       │               ↑ ネットワーク往復なし / レイテンシ 0.1ms 以下
       │
       └── 書き込み → リモート Turso プライマリ
                       ↓ 自動同期（syncInterval または手動 sync()）
                  ローカルファイルへ反映

パフォーマンス比較

db.ts — Embedded Replica 版

// src/lib/server/db.ts（Embedded Replica 版）
import { createClient } from '@libsql/client';
import { TURSO_DATABASE_URL, TURSO_AUTH_TOKEN } from '$env/static/private';

export const db = createClient({
  url: 'file:local-replica.db',     // ローカルレプリカファイル
  syncUrl: TURSO_DATABASE_URL,      // 同期元リモート Turso
  authToken: TURSO_AUTH_TOKEN,
  syncInterval: 60,                  // 60秒ごとに自動同期
});

url: 'file:...' でローカルファイルを指定し、syncUrl にリモート Turso の URL を指定します。ファイルが存在しない初回起動時は自動でリモートから全データをコピーします。

Read your writes — 書き込み直後の整合性確保

// 書き込み
await db.execute({
  sql: 'INSERT INTO posts VALUES (?, ?, ?)',
  args: [id, title, body],
});

// 書き込み直後に読む場合は手動 sync() で整合性を保証
await db.sync();

// この時点でローカルファイルに書き込んだデータが反映されている
const rows = await db.execute({ sql: 'SELECT * FROM posts WHERE id = ?', args: [id] });

syncInterval vs 手動 sync() の使い分け

運用上の注意点

1. 1

   .gitignore

   local-replica.db をコミットしない

   レプリカファイルはリモートから自動生成されるため git 管理に含める必要はありません。.gitignore に local-replica.db を追加してください。

2. 2

   ディスク容量

   リモート DB と同サイズのディスクが必要

   Embedded Replica はリモート DB のフルコピーをローカルに持ちます。100MB の DB なら 100MB のディスクが必要です。VPS / Fly.io / Railway などのディスク付きプラットフォームで使用してください。

3. 3

   Cloudflare Workers / Pages Functions

   ローカルディスクが使えないため不可

   Cloudflare Workers はステートレスなエフェメラル環境のためローカルファイルを永続化できません。Cloudflare 環境ではリモートのみ構成を使い、Cache API や KV を読み取りキャッシュとして併用することを検討してください。

SvelteKit を Cloudflare Pages にデプロイするには公式アダプター @sveltejs/adapter-cloudflare を使います。Turso との組み合わせでは クライアントの版（web 版）の選択 が最重要ポイントです。

1. アダプターのインストール

bun add -D @sveltejs/adapter-cloudflare

2. svelte.config.js の設定

// svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

export default {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter({
      routes: {
        include: ['/*'],
        exclude: ['<all>'],
      },
    },
  },
};

3. Cloudflare Pages ダッシュボード — 環境変数設定

1. Settings → Environment variables を開く
2. Production / Preview それぞれに TURSO_DATABASE_URL と TURSO_AUTH_TOKEN を追加
3. 認証トークンは必ず Encrypted で登録（プレーンテキスト禁止）

4. ビルド設定

5. @libsql/client/web の使い分け

Cloudflare Workers / Pages のランタイムは Node.js の fs / net モジュールを持ちません。そのため fetch ベースの web 版だけが正常に動作します。

// src/lib/server/db.ts（Cloudflare Pages 用）
// Cloudflare Workers / Pages では必ず /web 版を import する
import { createClient } from '@libsql/client/web';
import { TURSO_DATABASE_URL, TURSO_AUTH_TOKEN } from '$env/static/private';

export const db = createClient({
  url: TURSO_DATABASE_URL,
  authToken: TURSO_AUTH_TOKEN,
});

クライアント版の比較

6. $env/dynamic/private 経由パターン

ビルド時に環境変数が確定しない場合（プレビュー環境など）は dynamic/private を使います。

import { env } from '$env/dynamic/private';

export const db = createClient({
  url: env.TURSO_DATABASE_URL,
  authToken: env.TURSO_AUTH_TOKEN,
});