Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.turso.tech/llms.txt

Use this file to discover all available pages before exploring further.

In this Rust quickstart we will learn how to:
  • Install the Turso crate
  • Connect to a local or remote database
  • Execute a query using SQL
  • Sync changes to the cloud
turso is the recommended crate for running a local database, including synchronizing it to and from Turso Cloud. It is built on the Turso Database engine — a ground-up rewrite of SQLite with concurrent writes (MVCC), async I/O, and native Rust async/await support.
1

Install

cargo add turso tokio --features tokio/full
2

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(())
}
3

Sync (push and pull)

If you need to sync your local database with Turso Cloud, enable the sync feature:
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(())
}
All reads and writes happen against the local database file — fast, offline-capable. push() sends your changes to the cloud. pull() brings remote changes down. See the reference for checkpoint, stats, and encryption. See Turso Sync for details on conflict resolution and more.
You can test sync locally without a Turso Cloud account by starting a local sync server:
tursodb :memory: --sync-server 127.0.0.1:8080
Then use http://127.0.0.1:8080 as the remote URL (no auth token needed). See Turso Database quickstart for how to install tursodb.

​
Remote Access (Over-the-Wire)

If your application needs to query a Turso Cloud database directly over the network (e.g., from a web server or serverless function), use the libsql crate with the remote feature. It connects over HTTP — no local file needed, no C compiler required.
For most applications, we recommend running a local database with sync (turso::sync) instead — it gives you faster reads, offline support, and lower latency. Remote access is useful when you cannot store a local database file (e.g., stateless serverless environments).
1

Retrieve database credentials

You will need an existing database to continue. If you don’t have one, create one.Get the database URL:
turso db show --url <database-name>
Get the database authentication token:
turso db tokens create <database-name>
Assign credentials to the environment variables inside .env.
TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=
You will want to store these as environment variables.
2

Install

cargo add libsql --features remote
3

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(())
}

​
Legacy: libsql (Embedded Replicas)

Usage of embedded replicas is strongly discouraged. With embedded replicas, reads are local but writes are sent to the remote database — this means writes fail when offline, have higher latency, and don’t support concurrent writes. Use the turso crate with turso::sync instead: all reads and writes are local, and you explicitly sync with push() / pull().
See the reference for legacy documentation on embedded replicas if you have an existing libsql codebase.