본문 바로가기
WIKI 기술 지식 베이스

Turso 퀵스타트

원문 보기 위키 갱신

Turso 퀵스타트 (TypeScript)

TypeScript에서 Turso를 시작하는 방법을 몇 단계로 정리해 드릴게요. 패키지 선택부터 로컬·원격 연결, SQL 쿼리, 클라우드 동기화까지 차근차근 따라오세요.

출처: 문서

본문

이 TypeScript 퀵스타트에서 우리는 다음을 배워요:

  • Turso 패키지 설치하기
  • 로컬 또는 원격 데이터베이스에 연결하기
  • SQL로 쿼리 실행하기
  • 변경 사항을 클라우드에 동기화하기

@tursodatabase/database는 로컬·임베디드 용도(Node.js, Electron, 모바일, IoT)에 추천하는 패키지예요. Turso Database 엔진 기반이고요 — SQLite를 완전히 새로 쓴 엔진으로, 동시 쓰기(MVCC)와 비동기 I/O를 지원해요.

Install

npm install @tursodatabase/database

Connect

import { connect } from "@tursodatabase/database";

const db = await connect("app.db");

Execute

const createTable = db.prepare(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username TEXT NOT NULL
  )
`);
await createTable.run();

const insertUser = db.prepare("INSERT INTO users (username) VALUES (?)");
await insertUser.run("alice");

const stmt = db.prepare("SELECT * FROM users");
const users = await stmt.all();
console.log(users);

Sync (push and pull)

로컬 데이터베이스를 Turso Cloud와 동기화해야 한다면 @tursodatabase/sync를 사용하세요:

npm install @tursodatabase/sync

import { connect } from "@tursodatabase/sync";

const db = await connect({
  path: "./app.db",
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

await db.exec("INSERT INTO users (username) VALUES ('bob')");

// Push local writes to Turso Cloud
await db.push();

// Pull remote changes to local database
const changed = await db.pull();

모든 읽기와 쓰기는 로컬 데이터베이스 파일을 대상으로 일어나요 — 빠르고, 오프라인에서도 동작하죠. push()는 변경 사항을 클라우드로 보내고, pull()은 원격 변경을 내려받아요. 충돌 해결, checkpointing 등 자세한 내용은 Turso Sync를 보세요.

Remote Turso database: @tursodatabase/serverless

@tursodatabase/serverless는 네트워크를 넘어 Turso Cloud의 원격 Turso 데이터베이스에 연결하는 애플리케이션용 패키지예요. Node.js 서버, Docker 컨테이너, serverless 함수, 엣지 런타임(Cloudflare Workers, Vercel Edge, Deno Deploy)까지 다 포함되고요. fetch만 사용하기 때문에 네이티브 의존성이 전혀 없고 어디서든 동작해요.

Retrieve database credentials

계속하려면 기존 Turso 데이터베이스가 필요해요. 없다면 turso db create --tursodb로 하나 만드세요(자세한 건 퀵스타트).

데이터베이스 자격 증명을 받아서 환경 변수로 저장해 두시면 좋아요.

Install

npm install @tursodatabase/serverless

Connect to your database

import { connect } from "@tursodatabase/serverless";

const conn = connect({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

@libsql/client API와의 호환성이 필요하면 compat 모듈을 쓰세요:

import { createClient } from "@tursodatabase/serverless/compat";

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

Execute a query using SQL

const stmt = await conn.prepare("SELECT * FROM users");
const rows = await stmt.all();

값에 플레이스홀더가 필요하다면 이렇게 할 수 있어요:

const stmt = await conn.prepare("SELECT * FROM users WHERE id = ?");
const row = await stmt.get([1]);

Remote libSQL database: @libsql/client

@libsql/client는 Turso Cloud의 원격 libSQL 데이터베이스에 연결하는 애플리케이션용 패키지예요. ORM 연동(Drizzle, Prisma)에도 이 패키지를 쓰고요. 전체 문서는 레퍼런스에서 확인하세요.

Install

@libsql/client 패키지를 설치하면 돼요: npm install @libsql/client

Connect

import { createClient } from "@libsql/client";

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

Execute

await turso.execute("SELECT * FROM users");

Sync

로컬 데이터베이스를 원격 Turso Cloud 데이터베이스와 동기화해야 한다면(로컬 읽기·쓰기 + 클라우드로 push/pull), Turso Sync를 사용하세요. Turso Sync는 Turso Database 엔진 기반이고, 명시적인 push()와 pull() 연산을 제공하는 local-first sync예요.

더 알아보기 (Learn more)