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

Turso SDK 소개

원문 보기 위키 갱신

Turso SDK를 고를 때는 두 가지 규칙만 기억하면 거의 모든 경우를 커버할 수 있어요. 로컬 데이터베이스가 등장하는지, 아니면 클라우드 데이터베이스와 네트워크로만 통신하는지에 따라 패키지가 갈려요. 이 문서는 언어별·상황별로 어떤 패키지를 쓰면 되는지 안내해요.

출처: 문서

본문

어떤 패키지를 써야 할까요?

두 가지 규칙이 거의 모든 경우를 커버해요:

  1. 로컬 데이터베이스가 관련되면 Turso 패키지를 사용하세요. 완전히 로컬인 데이터베이스(임베디드, 온디바이스, 오프라인)와 클라우드와 동기화하는 로컬 데이터베이스 모두 여기에 해당해요. 반대편 데이터베이스가 libSQL인 경우에도 마찬가지예요.
  2. 애플리케이션이 클라우드 데이터베이스와 네트워크로만 통신한다면, 드라이버를 데이터베이스 엔진에 맞추세요. Turso 데이터베이스는 serverless 드라이버를, libSQL 데이터베이스는 libSQL 클라이언트를 사용해요.
Use case TypeScript Python Go Rust
Local database (embedded, on-device, offline) @tursodatabase/database pyturso tursogo turso
Local database + cloud sync (push/pull) @tursodatabase/sync pyturso (with sync) tursogo (with sync) turso (with sync feature)
Remote Turso database (over-the-wire) @tursodatabase/serverless turso_serverless tursogo-serverless turso_serverless
Remote libSQL database (over-the-wire) @libsql/client libsql libsql-client-go libsql (with remote feature)

새 프로젝트를 시작하나요? @tursodatabase/database(TypeScript), pyturso(Python), tursogo(Go), turso(Rust)를 사용해요. 이 패키지들은 Turso 엔진 기반이에요. SQLite를 완전히 새로 작성한 엔진으로, 동시 쓰기와 비동기 I/O, 로컬 우선 동기화를 지원해요.

동기화가 필요한가요? Turso Sync를 사용하면 로컬에서 읽고 쓰면서 push() / pull()로 Turso Cloud에 명시적으로 동기화할 수 있어요.

ORM을 사용하나요?

  • TypeScript — Drizzle과 Prisma는 @libsql/client 위에서 동작하고, 생태계의 주요 ORM들이 프로덕션 수준 지원을 제공해요.
  • Rust — Tokio 프로젝트의 비동기 ORM인 Toasty는 turso 크레이트 기반 네이티브 Turso 드라이버를 갖고 있어요.
  • Python — SQLAlchemy 가이드를 참고해 주세요.

SQLite에서 마이그레이션하나요? Turso는 드롭인 대체재예요. 기존 SQL, 스키마, 쿼리는 그대로 동작해요.

이미 @libsql/client, libsql, go-libsql을 사용 중인가요? 이 패키지들은 수년간 Turso Cloud를 떠받쳐 온 SQLite 오픈소스 포크인 libSQL을 기반으로 만들어졌어요. 프로덕션 준비와 검증이 끝난 상태이고, libSQL 데이터베이스에 원격 접근하는 추천 방식으로 남아 있어요. 다만 워크로드에 동시 쓰기, push/pull 동기화, 로컬 우선 쓰기(오프라인 / 멀티 라이터 / 양방향)가 필요하다면 Turso 데이터베이스와 그 패키지를 고려해 보세요.

serverless 드라이버

serverless 드라이버는 HTTP 위에서 SQL을 주고받아요. 영속적인 연결도, 네이티브 라이브러리도 필요 없어요. 서버, Docker 컨테이너, serverless 함수, edge 런타임처럼 해당 언어가 동작하는 어디에서든 쓸 수 있어요. 각 드라이버는 임베디드 버전과 API가 같아서 코드를 로컬↔원격 사이에서 최소한의 수정만으로 옮길 수 있어요.

참고: 동기화가 필요한가요? 새 프로젝트라면 Turso Sync를 사용해요. 로컬 읽기·쓰기에 클라우드로의 명시적 push() / pull()을 제공해요. 아래의 libSQL 기반 SDK들도 임베디드 레플리카를 지원하는데, 이 경우 읽기는 로컬에서 처리되고 쓰기는 클라우드 primary로 전송돼요.

공식 SDK

Turso가 공식으로 유지보수하는 SDK는 TypeScript, Python, Go, Rust 등 주요 언어를 아우르고, 상황별 패키지 조합은 위 표를 참고하면 돼요. 각 언어별 퀵스타트와 레퍼런스 문서는 이 문서집의 해당 페이지에서 확인할 수 있어요.

커뮤니티 SDK

아래 SDK들은 커뮤니티가 주도해서 만든 것으로, Turso의 공식 지원은 제공되지 않아요.

SQL over HTTP

SDK를 설치할 수 없거나 원격 데이터베이스를 가장 가볍게 다루고 싶다면 SQL over HTTP를 사용할 수 있어요. @tursodatabase/serverless와 @libsql/client 같은 serverless SDK와, 아무 HTTP 클라이언트에서나 쓸 수 있는 Raw HTTP 방식이 준비되어 있어요. 자세한 내용은 HTTP 퀵스타트와 HTTP 레퍼런스에서 확인해 주세요.

더 알아보기 (Learn more)