SQLite를 글로벌 분산 DB로 — Turso + libSQL이 서버리스 엣지 아키텍처를 바꾸는 방식

// libSQL 클라이언트 — HTTP 모드 (서버리스/엣지 환경)
import { createClient } from "@libsql/client";
 
const client = createClient({
  // 실제 형식: libsql://[db명]-[org명].turso.io
  // https:// 프로토콜도 HTTP 폴백으로 동작하지만, libsql://이 표준 형식
  url: "libsql://my-db-myorg.turso.io",
  authToken: process.env.TURSO_AUTH_TOKEN,
});
 
const result = await client.execute(
  "SELECT * FROM users WHERE active = 1 LIMIT 10"
);
console.log(result.rows);

// libSQL 클라이언트 — 임베디드 레플리카 모드 (Node.js 서버/Fly.io 등)
import { createClient } from "@libsql/client";
 
const client = createClient({
  url: "file:local.db",                          // 로컬 SQLite 파일
  syncUrl: "libsql://my-db-myorg.turso.io",      // 원격 프라이머리
  authToken: process.env.TURSO_AUTH_TOKEN,
  syncInterval: 60,                              // 60초마다 자동 동기화
});
 
// 읽기: 로컬 디스크 속도 (~200나노초)
const result = await client.execute("SELECT * FROM products");
 
// 쓰기: 자동으로 원격 프라이머리에 전달
await client.execute(
  "INSERT INTO orders (user_id, total) VALUES (?, ?)",
  [userId, total]
);

// Cloudflare Workers + D1
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { results } = await env.DB.prepare(
      "SELECT * FROM posts WHERE published = 1 ORDER BY created_at DESC LIMIT 20"
    ).all();
 
    return Response.json(results);
  },
};

// Turso Platform REST API로 테넌트별 DB 자동 프로비저닝
// 공식 관리 SDK(@turso/api)도 제공되므로 최신 문서에서 패키지명 확인 권장
async function provisionTenantDatabase(tenantId: string, region: string) {
  const org = process.env.TURSO_ORG!;
  const apiToken = process.env.TURSO_API_TOKEN!;
  const baseUrl = "https://api.turso.tech/v1";
 
  // 테넌트 DB 생성
  const createRes = await fetch(`${baseUrl}/organizations/${org}/databases`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: `tenant-${tenantId}`,
      group: "production",
      location: region, // 테넌트 위치에 맞는 리전
    }),
  });
  const { database } = await createRes.json();
 
  // 접속 토큰 발급 (테넌트별 격리)
  const tokenRes = await fetch(
    `${baseUrl}/organizations/${org}/databases/${database.Name}/auth/tokens`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${apiToken}` },
    }
  );
  const { jwt } = await tokenRes.json();
 
  return {
    url: `libsql://${database.Hostname}`,
    authToken: jwt,
  };
}
 
// 테넌트 접속 정보는 별도 메타DB(예: PostgreSQL, Redis)에 보관
// 최초 프로비저닝 시 저장하고, 이후 요청마다 조회
async function getTenantCredentials(tenantId: string): Promise<{ url: string; authToken: string }> {
  const meta = await metaDb.findOne({ tenantId });
  if (!meta) throw new Error(`테넌트 ${tenantId}의 DB 정보를 찾을 수 없습니다.`);
  return { url: meta.dbUrl, authToken: meta.dbToken };
}
 
// 테넌트 요청 처리
async function handleTenantRequest(tenantId: string, query: string) {
  const { url, authToken } = await getTenantCredentials(tenantId);
  const client = createClient({ url, authToken });
  return await client.execute(query);
}

// 스키마 마이그레이션 — 모든 테넌트에 일괄 적용
async function migrateAllTenants(migrationSql: string) {
  const tenants = await getAllTenants();
 
  await Promise.allSettled(
    tenants.map(async (tenant) => {
      const client = createClient({
        url: tenant.dbUrl,
        authToken: tenant.dbToken,
      });
      await client.executeMultiple(migrationSql);
    })
  );
}

pnpm add @libsql/client drizzle-orm
pnpm add -D drizzle-kit

// lib/db.ts — Drizzle + libSQL 설정
import { drizzle } from "drizzle-orm/libsql";
import { createClient } from "@libsql/client";
 
const client = createClient({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});
 
export const db = drizzle(client);

// schema.ts
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
 
export const posts = sqliteTable("posts", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  title: text("title").notNull(),
  content: text("content").notNull(),
  authorId: integer("author_id").notNull(),
  publishedAt: integer("published_at", { mode: "timestamp" }),
});

// app/posts/page.tsx — Server Component (읽기)
import { db } from "@/lib/db";
import { posts } from "@/schema";
import { desc, isNotNull } from "drizzle-orm";
 
export default async function PostsPage() {
  const publishedPosts = await db
    .select()
    .from(posts)
    .where(isNotNull(posts.publishedAt))
    .orderBy(desc(posts.publishedAt))
    .limit(20);
 
  return (
    <ul>
      {publishedPosts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

// app/posts/actions.ts — Server Action (쓰기)
"use server";
 
import { db } from "@/lib/db";
import { posts } from "@/schema";
import { revalidatePath } from "next/cache";
 
export async function createPost(formData: FormData) {
  const title = formData.get("title") as string;
  const content = formData.get("content") as string;
 
  // 경계값 검증 — 실제 서비스에서는 zod 등 스키마 검증 라이브러리 사용 권장
  if (!title?.trim() || !content?.trim()) {
    throw new Error("제목과 내용을 입력해야 합니다.");
  }
 
  await db.insert(posts).values({
    title,
    content,
    authorId: 1, // 실제로는 세션에서 가져옴
  });
 
  revalidatePath("/posts");
}

// src/index.ts — Hono + D1
import { Hono } from "hono";
import { cors } from "hono/cors";
 
type Bindings = {
  DB: D1Database;
};
 
const app = new Hono<{ Bindings: Bindings }>();
 
app.use("/*", cors());
 
app.get("/api/products", async (c) => {
  const { results } = await c.env.DB.prepare(
    "SELECT id, name, price FROM products WHERE active = 1"
  ).all();
 
  return c.json(results);
});
 
// Sessions API — read-after-write 일관성 보장
// "first-primary"는 Cloudflare가 정의한 리터럴로,
// 해당 세션의 모든 쿼리를 프라이머리 노드에서 실행하도록 강제함
app.post("/api/orders", async (c) => {
  const body = await c.req.json();
 
  const session = c.env.DB.withSession("first-primary");
  await session
    .prepare("INSERT INTO orders (user_id, product_id, amount) VALUES (?, ?, ?)")
    .bind(body.userId, body.productId, body.amount)
    .run();
 
  // 같은 세션으로 읽기 — 방금 쓴 데이터 보장
  const { results } = await session
    .prepare(
      "SELECT * FROM orders WHERE user_id = ? ORDER BY created_at DESC LIMIT 1"
    )
    .bind(body.userId)
    .all();
 
  return c.json(results[0]);
});
 
export default app;

# wrangler.toml
name = "my-api"
main = "src/index.ts"
compatibility_date = "2026-01-01"
 
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-database-id-here"

// AI 에이전트 DB 설정 — 벡터 인덱스 포함
const initSchema = `
  CREATE TABLE IF NOT EXISTS agent_memory (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    agent_id TEXT NOT NULL,
    content TEXT NOT NULL,
    embedding F32_BLOB(1536),  -- OpenAI text-embedding-3-small
    created_at INTEGER DEFAULT (unixepoch())
  );
 
  CREATE INDEX IF NOT EXISTS memory_embedding_idx
    ON agent_memory (libsql_vector_idx(embedding));
`;
 
await client.executeMultiple(initSchema);

// 메모리 저장
async function storeMemory(
  agentId: string,
  content: string,
  embedding: number[]
) {
  await client.execute({
    sql: `
      INSERT INTO agent_memory (agent_id, content, embedding)
      VALUES (?, ?, vector32(?))
    `,
    args: [agentId, content, JSON.stringify(embedding)],
  });
}
 
// 유사 메모리 검색 (RAG)
// vector_top_k는 rowid와 distance를 반환하므로 alias로 컬럼 명확화
async function recallSimilarMemories(
  agentId: string,
  queryEmbedding: number[],
  topK = 5
) {
  const result = await client.execute({
    sql: `
      SELECT m.content, v.distance
      FROM vector_top_k('memory_embedding_idx', vector32(?), ?) AS v
      JOIN agent_memory AS m ON m.rowid = v.id
      WHERE m.agent_id = ?
      ORDER BY v.distance
    `,
    args: [JSON.stringify(queryEmbedding), topK, agentId],
  });
 
  return result.rows;
}

pnpm add @prisma/client
pnpm add -D prisma
npx prisma init

// prisma/schema.prisma
datasource db {
  provider     = "mysql"
  url          = env("DATABASE_URL")
  relationMode = "prisma" // Vitess에서는 FK 제약 대신 Prisma 레이어에서 참조 무결성 관리
}
 
generator client {
  provider = "prisma-client-js"
}
 
model Post {
  id          Int       @id @default(autoincrement())
  title       String
  content     String    @db.Text
  published   Boolean   @default(false)
  publishedAt DateTime?
  authorId    Int
 
  @@index([authorId])
}

# .env — PlanetScale 연결 문자열
DATABASE_URL="mysql://username:password@aws.connect.psdb.cloud/mydb?sslaccept=strict"

// lib/db.ts — PlanetScale + Prisma (서버리스 환경용 싱글톤)
import { PrismaClient } from "@prisma/client";
 
const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
 
export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient();
 
if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

// app/posts/page.tsx — Server Component
import { prisma } from "@/lib/db";
 
export default async function PostsPage() {
  const posts = await prisma.post.findMany({
    where: { published: true },
    orderBy: { publishedAt: "desc" },
    take: 20,
  });
 
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}