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

Turso 퀵스타트

원문 보기 위키 갱신

Turso 퀵스타트 (Rust)

Rust에서 Turso를 시작하는 방법을 몇 단계만에 정리해 드릴게요. 설치부터 로컬·원격 데이터베이스 연결, SQL 쿼리 실행, 클라우드 동기화까지 한 번에 훑어보니 차근차근 따라오세요.

출처: 문서

본문

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

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

turso는 로컬 데이터베이스를 구동하고 Turso Cloud와 동기화까지 하려면 추천하는 crate예요. Turso Database 엔진 기반이고요 — SQLite를 완전히 새로 쓴 엔진으로, 동시 쓰기(MVCC), 비동기 I/O, 네이티브 Rust async/await를 지원해요.

Install

cargo add turso tokio --features tokio/full

Connect

use turso::Builder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Builder::new_local("app.db").build().await?;
    let conn = db.connect()?;

    conn.execute(
        "CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL
        )",
        (),
    ).await?;

    conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",)).await?;

    let mut rows = conn.query("SELECT * FROM users", ()).await?;
    while let Some(row) = rows.next().await? {
        let id: i64 = row.get(0)?;
        let name: String = row.get(1)?;
        println!("User: {} {}", id, name);
    }

    Ok(())
}

Sync (push and pull)

로컬 데이터베이스를 Turso Cloud와 동기화해야 한다면 sync 피처를 활성화하세요:

cargo add turso --features sync

use turso::sync::Builder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Builder::new_remote("app.db")
        .with_remote_url(&std::env::var("TURSO_DATABASE_URL")?)
        .with_auth_token(&std::env::var("TURSO_AUTH_TOKEN")?)
        .build()
        .await?;

    let conn = db.connect().await?;

    conn.execute("INSERT INTO users (name) VALUES (?)", ("Bob",)).await?;

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

    // Pull remote changes to local database
    db.pull().await?;

    Ok(())
}

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

참고로, Turso Cloud 계정 없이도 로컬 sync 서버를 띄워서 동기화를 테스트할 수 있어요:

tursodb :memory: --sync-server 127.0.0.1:8080

그리고 http://127.0.0.1:8080을 원격 URL로 쓰면 됩니다(인증 토큰 불필요). tursodb 설치 방법은 Turso Database 퀵스타트를 보세요.

Remote Access (Over-the-Wire)

애플리케이션이 네트워크를 넘어 Turso Cloud 데이터베이스를 직접 쿼리해야 한다면(예: 웹 서버나 serverless 함수에서), 사용하는 데이터베이스 엔진에 맞는 crate를 고르세요: Turso 데이터베이스라면 turso_serverless, libSQL 데이터베이스라면 remote 피처를 켠 libsql이에요.

참고로, 대부분의 애플리케이션에서는 로컬 데이터베이스 + sync(turso::sync) 조합을 추천해요 — 읽기가 더 빠르고, 오프라인 지원에, 지연 시간도 낮거든요. 원격 접근은 로컬 데이터베이스 파일을 저장할 수 없을 때(예: 상태 없는 serverless 환경) 유용해요.

Remote Turso database: turso_serverless

turso_serverless는 HTTP로 원격 Turso 데이터베이스에 연결해요 — 영속 연결도 없고, C 컴파일러도 필요 없어요. API는 임베디드 turso crate를 그대로 따르기 때문에, 코드를 로컬과 원격 사이에서 최소한의 수정으로 옮길 수 있죠.

Retrieve database credentials

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

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

Install

cargo add turso_serverless tokio --features tokio/full

Connect and query

use turso_serverless::Builder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Builder::new_remote(std::env::var("TURSO_DATABASE_URL")?)
        .with_auth_token(std::env::var("TURSO_AUTH_TOKEN")?)
        .build()
        .await?;
    let conn = db.connect()?;

    let mut rows = conn.query("SELECT * FROM users", ()).await?;
    while let Some(row) = rows.next().await? {
        let id: i64 = row.get(0)?;
        let name: String = row.get(1)?;
        println!("User: {} {}", id, name);
    }

    Ok(())
}

Remote libSQL database: libsql

remote 피처를 켠 libsql crate는 HTTP로 원격 libSQL 데이터베이스에 연결해요 — 로컬 파일도 없어도 되고, C 컴파일러도 필요 없어요.

Retrieve database credentials

계속하려면 기존 libSQL 데이터베이스가 필요해요. 없다면 만드세요.

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

Install

cargo add libsql --features remote

Connect and query

use libsql::Builder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let url = std::env::var("TURSO_DATABASE_URL")?;
    let token = std::env::var("TURSO_AUTH_TOKEN")?;

    let db = Builder::new_remote(url, token).build().await?;
    let conn = db.connect()?;

    let mut rows = conn.query("SELECT * FROM users", ()).await?;
    while let Some(row) = rows.next().await? {
        let id: i64 = row.get(0)?;
        let name: String = row.get(1)?;
        println!("User: {} {}", id, name);
    }

    Ok(())
}

Using an ORM

Tokio 프로젝트의 비동기 ORM인 Toasty는 네이티브 Turso 드라이버를 갖고 있어요. turso crate와 직접 통신하기 때문에, 위 퀵스타트에서 쓴 것과 동일한 Turso Database 엔진 위에 타입이 있는 모델 레이어(#[derive(toasty::Model)], 파생 쿼리, 관계)를 얻게 돼요.

cargo add toasty --features turso

전체 워크스루는 Toasty + Turso 가이드를 보세요.

Embedded Replicas (libsql)

Embedded Replicas는 Rust 앱에 Turso Cloud 데이터베이스의 로컬 읽기 복제본을 제공해요. 읽기는 로컬에서 처리되고, 쓰기는 클라우드 primary로 향한 뒤 복제본에 반영돼요. Embedded Replicas는 프로덕션에서 완전히 지원돼요.

sync가 필요한 새 프로젝트에는 turso crate의 turso::sync를 추천해요: 읽기와 쓰기가 모두 로컬에서 일어나고, push() / pull()로 명시적으로 동기화하며, 와이어 포맷은 페이지 프레임이 아니라 논리적 변경 데이터 캡처예요(벤치마크).

libsql로 Embedded Replicas를 쓰는 전체 문서는 레퍼런스에서 확인하세요.

더 알아보기 (Learn more)