Turso

Turso ↗ は、SQLite のオープンソースフォークである libSQL ↗ をベースにした、エッジホスト型の分散データベースです。Turso は、世界中のどこからでもクエリが来るアプリケーション向けに、クエリ遅延を小さくする目的で設計されています。

Turso との連携を設定する

Turso との連携を設定するには、次の手順を行います。

データベースの作成と投入には Turso CLI が必要です。ターミナルで次のいずれか一方を実行し、Turso CLI をインストールします。
```
# On macOS and linux with homebrew
brew install tursodatabase/tap/turso

# Manual scripted installation
curl -sSfL https://get.tur.so/install.sh | bash
```
続いて次のコマンドを実行し、Turso CLI がインストールされていることを確認します。
```
turso --version
```
最初の Turso データベースを作成する前に、次を実行して GitHub アカウントで認証します。
```
turso auth login
```
```
Waiting for authentication...
✔  Success! Logged in as <YOUR_GITHUB_USERNAME>
```
認証後は、turso db create <DATABASE_NAME> でデータベースを作成できます。Turso はデータベースを作成し、最も近いロケーションを自動で選びます。
```
turso db create my-db
```
```
# Example:
Creating database my-db in Amsterdam, Netherlands (ams)

# Once succeeded:
Created database my-db in Amsterdam, Netherlands (ams) in 13 seconds.
```
最初のデータベースができたら、直接接続して SQL クエリを実行できます。
```
turso db shell my-db
```

開いたシェルに、次の SQL クエリをコピーします。

CREATE TABLE elements (
  id INTEGER NOT NULL,
  elementName TEXT NOT NULL,
  atomicNumber INTEGER NOT NULL,
  symbol TEXT NOT NULL
);

INSERT INTO elements (id, elementName, atomicNumber, symbol)
VALUES (1, 'Hydrogen', 1, 'H'),
  (2, 'Helium', 2, 'He'),
  (3, 'Lithium', 3, 'Li'),
  (4, 'Beryllium', 4, 'Be'),
  (5, 'Boron', 5, 'B'),
  (6, 'Carbon', 6, 'C'),
  (7, 'Nitrogen', 7, 'N'),
  (8, 'Oxygen', 8, 'O'),
  (9, 'Fluorine', 9, 'F'),
  (10, 'Neon', 10, 'Ne');

Worker に Turso データベースの認証情報を設定します。

Turso のデータベース URL と認証トークンを、シークレットとして Worker に追加する必要があります。先にデータベース URL を取得し、認証トークンを作成します。

# Get your database URL
turso db show my-db --url

# Create an authentication token
turso db tokens create my-db

続いて Wrangler で、これらを Worker のシークレットとして追加します。

# Add the database URL as a secret
npx wrangler secret put TURSO_URL
# When prompted, paste your database URL

# Add the authentication token as a secret  
npx wrangler secret put TURSO_AUTH_TOKEN
# When prompted, paste your authentication token

Worker に Turso クライアントライブラリをインストールします。
npm i @libsql/client
yarn add @libsql/client
pnpm add @libsql/client
bun add @libsql/client

次の例は、Worker から Turso データベースにクエリする方法です。Turso への接続に必要な認証情報は、シークレットとして Worker に追加済みです。

import { Client as LibsqlClient, createClient } from "@libsql/client/web";

export interface Env {
	TURSO_URL?: string;
	TURSO_AUTH_TOKEN?: string;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const client = buildLibsqlClient(env);

		try {
			const res = await client.execute("SELECT * FROM elements");
			return new Response(JSON.stringify(res), {
				status: 200,
				headers: { "Content-Type": "application/json" },
			});
		} catch (error) {
			console.error("Error executing SQL query:", error);
			return new Response(
				JSON.stringify({ error: "Internal Server Error" }),
				{
					status: 500,
				},
			);
		}
	},
} satisfies ExportedHandler<Env>;

function buildLibsqlClient(env: Env): LibsqlClient {
	const url = env.TURSO_URL?.trim();
	if (url === undefined) {
		throw new Error("TURSO_URL env var is not defined");
	}

	const authToken = env.TURSO_AUTH_TOKEN?.trim();
	if (authToken == undefined) {
		throw new Error("TURSO_AUTH_TOKEN env var is not defined");
	}

	return createClient({ url, authToken });
}

Cloudflare Workers で使う場合、libSQL クライアントライブラリのインポート @libsql/client/web は、表示どおり正確にインポートする必要があります。web 以外のインポートは Workers 環境では動きません。
Env インターフェイスには、手順 4 で Turso 連携を追加したときに定義した環境変数とシークレットが含まれます。
Env インターフェイスは、Worker への最初のリクエストで作成した libSQL クライアントオブジェクトとルーターもキャッシュします。
Worker は buildLibsqlClient を使い、elements データベースにクエリして、レスポンスを JSON オブジェクトとして返します。

環境の設定とコードの準備ができたら、デプロイ前に Worker をローカルでテストできます。

Turso の詳細は、Turso の公式ドキュメント ↗ を参照してください。