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

Turso 퀵스타트

원문 보기 위키 갱신

Turso 퀵스타트 (Python)

Python에서도 Turso를 간단히 시작할 수 있어요. 패키지 설치부터 로컬·원격 데이터베이스 연결, SQL 쿼리 실행, 로컬 동기화까지 차례대로 배워요.

출처: 문서

본문

이 Python 퀵스타트에서 배울 내용은 다음과 같아요:

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

추천: pyturso (로컬 / 임베디드)

pyturso는 로컬 및 임베디드 용도에 추천되는 패키지예요. SQLite를 완전히 새로 작성한 Turso Database 엔진을 기반으로 하며, 동시 쓰기(MVCC)와 비동기 I/O를 지원해요. API는 표준 Python sqlite3 인터페이스를 따르기 때문에 드롭인 대체재로 동작해요.

1. 설치

uv add pyturso

또는 pip을 사용할 수도 있어요.

pip install pyturso

2. 연결

import turso

db = turso.connect("app.db")

인메모리 데이터베이스도 지원해요.

db = turso.connect(":memory:")

3. 실행

db.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
db.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
db.commit()

for row in db.execute("SELECT * FROM users"):
    print(row)

4. 동기화 (push와 pull)

로컬 데이터베이스를 Turso Cloud와 동기화해야 한다면 turso.sync를 사용해요.

import os
import turso.sync

db = turso.sync.connect(
    "app.db",
    remote_url=os.environ["TURSO_DATABASE_URL"],
    auth_token=os.environ["TURSO_AUTH_TOKEN"],
)

db.execute("INSERT INTO users (name) VALUES (?)", ("Bob",))
db.commit()

# Push local writes to Turso Cloud
db.push()

# Pull remote changes to local database
db.pull()

모든 읽기와 쓰기는 로컬 데이터베이스 파일을 대상으로 이뤄져서 빠르고 오프라인에서도 동작해요. push()는 변경 사항을 클라우드로 보내고, pull()은 원격 변경 사항을 내려받아요. 충돌 해결, 체크포인팅 등 세부 내용은 Turso Sync를 참고해 주세요.

원격 접근 (Over-the-Wire)

애플리케이션이 네트워크를 통해 Turso Cloud 데이터베이스를 직접 조회해야 한다면(웹 서버나 서버리스 함수 등), 사용하는 데이터베이스 엔진에 맞는 드라이버를 선택해요. Turso 데이터베이스라면 turso_serverless, libSQL 데이터베이스라면 libsql을 쓰면 돼요.

참고: 대부분의 애플리케이션에서는 Turso Sync (turso.sync)를 사용하는 로컬 데이터베이스를 추천해요. 더 빠른 읽기, 오프라인 지원, 낮은 지연 시간을 얻을 수 있거든요. 원격 접근은 로컬 데이터베이스 파일을 둘 수 없을 때(스테이트리스 서버리스 환경 등) 유용해요.

원격 Turso 데이터베이스: turso_serverless

turso_serverless는 HTTP를 통해 원격 Turso 데이터베이스에 연결해요. 영속적인 연결도, 네이티브 익스텐션도 필요 없이 표준 라이브러리만으로 동작해요. pyturso처럼 표준 DB-API 인터페이스를 구현해요.

1. 데이터베이스 자격 증명 가져오기

계속하려면 기존 Turso 데이터베이스가 필요해요. 없다면 turso db create --tursodb로 만들면 돼요(퀵스타트 참고). 자격 증명은 환경 변수로 저장해 두면 편해요.

2. 설치
uv add turso_serverless

또는 pip을 사용할 수도 있어요.

pip install turso_serverless
3. 연결과 쿼리
import os
import turso_serverless

conn = turso_serverless.connect(
    os.environ["TURSO_DATABASE_URL"],
    auth_token=os.environ["TURSO_AUTH_TOKEN"],
)

conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
conn.commit()

for row in conn.execute("SELECT * FROM users"):
    print(row)

conn.close()

원격 libSQL 데이터베이스: libsql

libsql은 HTTP를 통해 원격 libSQL 데이터베이스에 연결해요. 로컬 파일도 필요 없어요.

1. 데이터베이스 자격 증명 가져오기

계속하려면 기존 libSQL 데이터베이스가 필요해요. 없다면 만들어 주세요. 자격 증명은 환경 변수로 저장해 두면 편해요.

2. 설치
uv add libsql

또는 pip을 사용할 수도 있어요.

pip install libsql
3. 연결과 쿼리
import os
import libsql

conn = libsql.connect(
    database=os.environ["TURSO_DATABASE_URL"],
    auth_token=os.environ["TURSO_AUTH_TOKEN"],
)

conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
conn.commit()

rows = conn.execute("SELECT * FROM users").fetchall()
print(rows)

임베디드 레플리카 (libsql)

libsql 패키지도 임베디드 레플리카를 지원해요. 파일에서 로컬로 읽고, 쓰기는 클라우드 primary로 전송된 뒤 레플리카에 반영돼요. 임베디드 레플리카는 프로덕션에서도 완전히 지원돼요. 다만 동기화가 필요한 새 프로젝트라면 turso.sync를 추천해요. 읽기와 쓰기가 모두 로컬에서 일어나고, push() / pull()로 명시적으로 동기화할 수 있거든요.

임베디드 레플리카, 암호화, 주기 동기화의 전체 문서는 레퍼런스에서 확인할 수 있어요.

더 알아보기 (Learn more)