Python 레퍼런스

원문 보기 위키 갱신 2026.10.11

Turso의 Python용 패키지 세 가지를 정리한 레퍼런스예요. 어떤 패키지를 골라야 할지 아래 표로 한눈에 비교하고, 각 패키지의 설치·연결·쿼리·동기화 기능을 살펴봐요.

출처: 문서

본문

Turso가 제공하는 Python 패키지는 다음과 같아요:

	`pyturso`	`turso_serverless`	`libsql`
Use case	로컬/임베디드 데이터베이스, sync	원격 Turso 데이터베이스 (over-the-wire)	원격 libSQL 데이터베이스, 기존 libSQL 코드베이스
Engine	Turso (rewrite)	Turso (rewrite)	libSQL (SQLite fork)
Concurrent writes	Yes (MVCC)	Yes (MVCC)	Not supported
Sync	push/pull (local-first)	—	Embedded Replicas (쓰기는 클라우드 primary로)
API	Python `sqlite3`-compatible	Python `sqlite3`-compatible	Python `sqlite3`-compatible

새 프로젝트를 시작하나요? pyturso를 사용해요. Turso 엔진 기반이라 동시 쓰기와 로컬 우선 동기화를 지원해요. 네트워크를 통한 원격 접근이 필요하다면 데이터베이스 엔진에 맞춰 드라이버를 고르면 돼요. Turso 데이터베이스에는 turso_serverless, libSQL 데이터베이스에는 libsql.

pyturso

로컬 및 임베디드 용도를 위한 패키지예요. 동시 쓰기(MVCC)와 비동기 I/O를 지원하는 Turso Database 엔진을 기반으로 해요.

설치

pip install pyturso

연결

import turso

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

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

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

쿼리

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)

암호화

encryption 옵션을 사용해 로컬 데이터베이스를 저장 시점에 암호화할 수 있어요.

from turso import connect, EncryptionOpts

conn = connect("encrypted.db",
               experimental_features="encryption",
               encryption=EncryptionOpts(cipher="aegis256",
                                         hexkey="b1bbfda4f589dc9daaf004fe21111e00dc00c98237102f5c7002a5669fc76327"))

지원하는 암호: aegis256, aegis256x2, aegis128l, aegis128x2, aegis128x4, aes256gcm, aes128gcm.

암호화된 데이터베이스는 표준 SQLite 데이터베이스로는 읽을 수 없어요. 반드시 Turso Database 엔진으로 열어야 해요.

참고: Turso Cloud 데이터베이스도 bring-your-own-key 방식으로 암호화할 수 있어요 — 자세히 알아보기.

libsql (libSQL)

libsql 패키지는 오늘날 Turso Cloud를 떠받치고 있는 SQLite의 오픈소스 포크인 libSQL을 기반으로 만들어졌어요. 프로덕션 준비와 검증이 끝난 상태이고, 기존 libsql 기반 코드베이스를 다룰 때 적합해요.

참고: libsql의 임베디드 레플리카에서는 읽기가 로컬에서 처리되고 쓰기는 클라우드 primary로 전송된 뒤 레플리카에 반영돼요. 임베디드 레플리카는 완전히 지원돼요. 동기화가 필요한 새 프로젝트라면 turso.sync를 추천해요 — 퀵스타트를 참고하세요.

임베디드 레플리카

참고: 오프라인 쓰기, 양방향 동기화, 다중 라이터 수렴이 필요한 워크로드라면 turso.sync를 추천해요. 읽기와 쓰기가 모두 로컬에서 일어나고, push() / pull()로 명시적으로 동기화할 수 있어요. 퀵스타트를 참고하세요.

원격 데이터베이스에서 로컬 SQLite 파일로 동기화하고, 쓰기는 원격 primary 데이터베이스에 위임하는 임베디드 레플리카를 사용할 수 있어요.

import os

import libsql

conn = libsql.connect("local.db", sync_url=os.getenv("LIBSQL_URL"),
                      auth_token=os.getenv("LIBSQL_AUTH_TOKEN"))
conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER);")
conn.execute("INSERT INTO users(id) VALUES (1);")
conn.commit()

print(conn.execute("select * from users").fetchall())

경고: 임베디드 레플리카의 로컬 파일에는 데이터 전체가 저장되므로, 공유 스토리지나 컨테이너 이미지에 포함하지 않도록 주의하세요. 필요하지 않은 환경에서는 레플리카를 만들지 않는 편이 좋아요.

주기 동기화 (Periodic Sync)

sync_interval 옵션에 초 단위 시간을 넘기면 일정 간격으로 자동 동기화할 수 있어요. 예를 들어 1분마다 동기화하려면 다음 코드를 사용해요.

conn = libsql.connect("local.db", sync_interval=60, sync_url=os.getenv("LIBSQL_URL"),
                      auth_token=os.getenv("LIBSQL_AUTH_TOKEN"))

수동 동기화 (Manual Sync)

Sync 함수를 쓰면 로컬 데이터베이스를 원격 데이터베이스와 직접 동기화할 수 있어요.

conn.execute("INSERT INTO users(id) VALUES (2);")
conn.commit()
conn.sync()

암호화

경고: 새 프로젝트라면 로컬 암호화에는 pyturso를 추천해요. Turso Database 엔진 기반이라 성능이 더 좋고 동시 쓰기도 지원하거든요.

SQLite 파일에 암호화를 켜려면 encryption_key 옵션에 암호화 시크릿을 전달해 주세요.

conn = libsql.connect("encrypted.db", sync_url=os.getenv("LIBSQL_URL"),
                      auth_token=os.getenv("LIBSQL_AUTH_TOKEN"),
                      encryption_key=os.getenv("ENCRYPTION_KEY"))

참고: 암호화된 데이터베이스는 원시 데이터처럼 보이고 표준 SQLite 데이터베이스로는 읽을 수 없어요. 모든 작업에 libSQL 클라이언트를 사용해야 해요 — 자세히 알아보기.

더 알아보기 (Learn more)

Python 퀵스타트 — 패키지 선택부터 동기화까지 빠르게 시작하기
SQLAlchemy 연동 — SQLAlchemy ORM과 함께 Turso 쓰기
임베디드 레플리카 — 로컬 replica 개념과 동기화 동작 이해하기
클라우드 암호화 — bring-your-own-key 암호화 설정 방법