Tursoローカル開発完全ガイド - 3つの方法とDrizzle ORMとの連携

Turso を使った開発では、ローカル環境でデータベースを動作させる方法が複数あります。本記事では、3 つのローカル開発パターンと、Drizzle ORM を使ったマイグレーションの実行方法を詳しく解説します。

ローカル開発の 3 つのパターン

パターン	用途	特徴
SQLite ファイル直接使用	シンプルな開発	最も簡単、純粋な SQLite
`turso dev` コマンド	libSQL 機能が必要な場合	libSQL サーバーをローカル起動
Embedded Replicas	本番に近い環境	ローカル + リモート同期

パターン1: SQLite ファイルを直接使用（推奨）

最もシンプルで、多くの開発シナリオに適したアプローチです。

セットアップ

環境変数の設定

.env.local を作成します：

# ローカル開発用（SQLite ファイル）
TURSO_DATABASE_URL=file:local.db
TURSO_AUTH_TOKEN=dummy_token_for_local

重要: file: プレフィックスが必須です。これは libSQL クライアントの要件です。

データベース接続の設定

src/db/index.ts:

import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";
import * as schema from "./schema";

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

export const db = drizzle(client, { schema });

Drizzle Kit 設定

drizzle.config.ts:

import { defineConfig } from "drizzle-kit";

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

マイグレーションの実行

# マイグレーションファイルを生成
npx drizzle-kit generate

# マイグレーションを実行
npx drizzle-kit migrate

# Drizzle Studio でデータを確認
npx drizzle-kit studio

利点と注意点

利点:

セットアップが最も簡単
追加のサーバー起動が不要
高速な読み書き

注意点:

libSQL 固有の拡張機能は使用不可
.gitignore に local.db を追加すること

# .gitignore に追加
local.db
local.db-shm
local.db-wal

パターン2: `turso dev` コマンドでローカルサーバー起動

libSQL 固有の機能（拡張機能など）が必要な場合は、このパターンを使用します。

Turso CLI のインストール

# macOS (Homebrew)
brew install tursodatabase/tap/turso

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

ローカルサーバーの起動

基本的な起動（データは揮発性）

turso dev

サーバーが http://127.0.0.1:8080 で起動します。サーバーを停止するとデータは失われます。

データを永続化する起動（推奨）

turso dev --db-file local.db

local.db ファイルにデータが保存され、再起動後もデータが保持されます。

カスタムポートで起動

turso dev --db-file local.db --port 3001

環境変数の設定

.env.local:

# turso dev サーバーに接続
TURSO_DATABASE_URL=http://127.0.0.1:8080
TURSO_AUTH_TOKEN=dummy_token_for_local

データベース接続の設定

src/db/index.ts:

import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";
import * as schema from "./schema";

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

export const db = drizzle(client, { schema });

Drizzle Kit 設定

drizzle.config.ts:

import { defineConfig } from "drizzle-kit";

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

シェルでデータベースに接続

# ローカルサーバーにシェルで接続
turso db shell http://127.0.0.1:8080

SQL を直接実行できます：

.tables
SELECT * FROM users;
.quit

開発ワークフロー

ターミナルを 2 つ開いて作業します：

ターミナル 1: libSQL サーバー

turso dev --db-file local.db

ターミナル 2: 開発作業

# マイグレーションファイル生成
npx drizzle-kit generate

# マイグレーション実行
npx drizzle-kit migrate

# Next.js 開発サーバー起動
npm run dev

パターン3: Embedded Replicas（本番に近い環境）

ローカルにレプリカを持ちながら、リモートデータベースと同期するパターンです。本番環境に近い動作を確認したい場合に有用です。

環境変数の設定

.env.local:

# ローカルレプリカファイル
LOCAL_DB_PATH=file:local-replica.db

# リモート Turso データベース（本番 or ステージング）
TURSO_DATABASE_URL=libsql://your-database-org.turso.io
TURSO_AUTH_TOKEN=your-auth-token

データベース接続の設定

src/db/index.ts:

import { createClient, type Client } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";
import * as schema from "./schema";

function createDbClient(): Client {
  const isProduction = process.env.NODE_ENV === "production";

  if (isProduction) {
    // 本番: リモートデータベースに直接接続
    return createClient({
      url: process.env.TURSO_DATABASE_URL!,
      authToken: process.env.TURSO_AUTH_TOKEN,
    });
  }

  // 開発: Embedded Replica を使用
  return createClient({
    url: process.env.LOCAL_DB_PATH!, // ローカルファイル
    syncUrl: process.env.TURSO_DATABASE_URL, // リモート同期先
    authToken: process.env.TURSO_AUTH_TOKEN,
    syncInterval: 60, // 60秒ごとに自動同期
  });
}

const client = createDbClient();

export const db = drizzle(client, { schema });

// 手動で同期する関数
export async function syncDatabase() {
  await client.sync();
}

手動同期の実行

import { syncDatabase } from "@/db";

// 必要なタイミングで同期
await syncDatabase();

オフラインモード

完全にオフラインで動作させる場合：

const client = createClient({
  url: "file:local-replica.db",
  syncUrl: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
  offline: true, // オフラインモード有効
});

オフラインモードでは、書き込みもローカルに行われます。オンラインに戻ったら sync() でリモートに反映できます。

環境ごとの設定切り替え

推奨する環境変数の構成

.env.local（ローカル開発用）:

# パターン1: SQLite ファイル直接
TURSO_DATABASE_URL=file:local.db
TURSO_AUTH_TOKEN=dummy_token_for_local

# または パターン2: turso dev サーバー
# TURSO_DATABASE_URL=http://127.0.0.1:8080
# TURSO_AUTH_TOKEN=dummy_token_for_local

.env.production（本番用）:

TURSO_DATABASE_URL=libsql://your-database-org.turso.io
TURSO_AUTH_TOKEN=your-production-token

接続設定

src/db/index.ts:

import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";
import * as schema from "./schema";

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

export const db = drizzle(client, { schema });

Drizzle Kit 設定

drizzle.config.ts:

import { defineConfig } from "drizzle-kit";

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

マイグレーションのベストプラクティス

開発時のワークフロー

# 1. スキーマを変更
# src/db/schema.ts を編集

# 2. マイグレーションファイルを生成
npx drizzle-kit generate

# 3. マイグレーションを実行
npx drizzle-kit migrate

# 4. 動作確認
npm run dev

本番デプロイ時のワークフロー

# 1. 本番 DB の URL を設定
export TURSO_DATABASE_URL=libsql://your-database-org.turso.io
export TURSO_AUTH_TOKEN=your-token

# 2. マイグレーションを実行
npx drizzle-kit migrate

package.json スクリプト例

{
  "scripts": {
    "dev": "next dev",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio",
    "db:local": "turso dev --db-file local.db"
  }
}

Drizzle Studio でデータを確認

Drizzle Studio は GUI でデータベースの内容を確認・編集できるツールです。

npx drizzle-kit studio

ブラウザで https://local.drizzle.studio が開き、テーブルの確認やデータの編集が可能です。

トラブルシューティング

`file:` プレフィックスを忘れた

# ❌ 間違い
TURSO_DATABASE_URL=local.db

# ✅ 正しい
TURSO_DATABASE_URL=file:local.db

`turso dev` が起動しない

Turso CLI が最新版かを確認：

turso --version
brew upgrade turso  # macOS の場合

マイグレーションが失敗する

データベース URL が正しいか確認
ローカルサーバーが起動しているか確認（パターン 2 の場合）
.env.local が正しく読み込まれているか確認

# 環境変数の確認
echo $TURSO_DATABASE_URL

ローカルとリモートでスキーマが異なる

Embedded Replicas 使用時は、まずリモートにマイグレーションを適用してから同期：

# 1. リモートにマイグレーション適用
TURSO_DATABASE_URL=libsql://... TURSO_AUTH_TOKEN=... npx drizzle-kit migrate

# 2. ローカルレプリカを同期
# アプリケーション起動時に自動同期される

推奨するローカル開発構成

ほとんどのプロジェクトでは、パターン 1（SQLite ファイル直接使用） が最もシンプルで効果的です。

project/
├── src/
│   ├── db/
│   │   ├── index.ts      # DB 接続
│   │   └── schema.ts     # スキーマ定義
│   └── app/
├── drizzle/
│   └── *.sql             # マイグレーションファイル
├── drizzle.config.ts
├── local.db              # ローカル DB（.gitignore に追加）
├── .env.local            # TURSO_DATABASE_URL, TURSO_AUTH_TOKEN
└── .gitignore

.gitignore:

# ローカルデータベース
local.db
local.db-shm
local.db-wal
local-replica.db
local-replica.db-shm
local-replica.db-wal

まとめ

用途	推奨パターン
一般的な開発	パターン 1: `file:local.db`
libSQL 拡張機能が必要	パターン 2: `turso dev`
本番データの同期テスト	パターン 3: Embedded Replicas

ローカル開発では、シンプルな SQLite ファイル直接使用から始め、必要に応じて turso dev や Embedded Replicas に移行することをお勧めします。Drizzle ORM の push コマンドを活用すれば、スキーマ変更を素早くローカル DB に反映でき、効率的な開発が可能です。

目次