Back to Details

turso-libsql

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Turso & libSQL

Turso & libSQL

Turso is a SQLite-compatible managed database platform built on libSQL — a production-ready, open-contribution fork of SQLite. libSQL adds native vector search, extensions, and async I/O while remaining fully backward-compatible with SQLite.
libSQL vs. Turso Database: libSQL is the battle-tested fork used by Turso Cloud today. Turso Database is a ground-up rewrite optimized for extreme density and concurrent writes (currently in beta). For new projects with stable workloads, use libSQL via Turso Cloud. For new projects targeting agents, on-device, or high-density use cases, consider Turso Database.
Turso 是一个兼容SQLite的托管数据库平台，基于libSQL构建——libSQL是SQLite的一个可用于生产环境、支持社区贡献的分支。libSQL在完全向后兼容SQLite的基础上，新增了原生向量搜索、扩展功能和异步I/O。
libSQL vs. Turso Database：libSQL是Turso Cloud当前使用的、经过实战检验的分支版本。Turso Database是从零开始重写的版本，针对极致密度和并发写入进行了优化（目前处于测试版）。对于工作负载稳定的新项目，通过Turso Cloud使用libSQL；针对Agent、设备端或高密度场景的新项目，可以考虑使用Turso Database。

Key Concepts

核心概念

TermMeaning
DatabaseA single libSQL database instance hosted on Turso Cloud
GroupA collection of databases sharing a region and auth tokens
Embedded ReplicaA local SQLite file that syncs with a remote Turso database
Auth TokenJWT used to authenticate SDK connections
libsql://The native Turso protocol (WebSocket-based, best for persistent connections)
https://HTTP-based access, better for single-shot serverless queries
术语含义
Database托管在Turso Cloud上的单个libSQL数据库实例
Group共享区域和认证令牌的数据库集合
Embedded Replica与远程Turso数据库同步的本地SQLite文件
Auth Token用于认证SDK连接的JWT
libsql://Turso原生协议（基于WebSocket，最适合持久连接）
https://基于HTTP的访问方式，更适合单次无服务器查询

Installation

安装

bash
undefined
bash
undefined

TypeScript / JavaScript

TypeScript / JavaScript

npm install @libsql/client
npm install @libsql/client

Python

Python

pip install libsql-client
pip install libsql-client

Rust (Cargo.toml)

Rust (Cargo.toml)

libsql = "0.6"

libsql = "0.6"

Go

Go

go get github.com/tursodatabase/go-libsql

go get github.com/tursodatabase/go-libsql

undefined
undefined

Connecting to Turso

连接到Turso

Always load credentials from environment variables. Never hardcode tokens.
ts
import { createClient } from "@libsql/client";

const client = createClient({
  url: process.env.TURSO_DATABASE_URL!,    // libsql://[DB]-[ORG].turso.io
  authToken: process.env.TURSO_AUTH_TOKEN!, // JWT from Turso CLI or Platform API
});
Protocol selection:
  • Use 
    libsql://
    for persistent connections (WebSockets) — best for servers and long-lived processes
  • Use 
    https://
    for single serverless invocations — fewer round-trips per cold start
  • Use 
    file:path/to/db.db
    for local SQLite files (no 
    authToken
    needed)
  • Use 
    :memory:
    for in-memory databases in tests
始终从环境变量加载凭证，切勿硬编码令牌。
ts
import { createClient } from "@libsql/client";

const client = createClient({
  url: process.env.TURSO_DATABASE_URL!,    // libsql://[DB]-[ORG].turso.io
  authToken: process.env.TURSO_AUTH_TOKEN!, // 来自Turso CLI或平台API的JWT
});
协议选择:
  • 使用
    libsql://
    进行持久连接（WebSocket）——最适合服务器和长期运行的进程
  • 使用
    https://
    进行单次无服务器调用——冷启动时往返次数更少
  • 使用
    file:path/to/db.db
    访问本地SQLite文件（无需
    authToken
    ）
  • 使用
    :memory:
    在测试中创建内存数据库

Executing Queries

执行查询

Always use parameterized queries. Never interpolate user input into SQL strings.
ts
// Simple query
const result = await client.execute("SELECT * FROM users");

// Positional placeholders (preferred for brevity)
const user = await client.execute({
  sql: "SELECT * FROM users WHERE id = ?",
  args: [userId],
});

// Named placeholders
const inserted = await client.execute({
  sql: "INSERT INTO users (name, email) VALUES (:name, :email)",
  args: { name: "Iku", email: "iku@example.com" },
});
ResultSet fields:
  • rows
    — array of row objects
  • columns
    — column names in order
  • rowsAffected
    — for write operations
  • lastInsertRowid
    — 
    bigint | undefined
    for INSERT
始终使用参数化查询，切勿将用户输入直接插入SQL字符串。
ts
// 简单查询
const result = await client.execute("SELECT * FROM users");

// 位置占位符（推荐使用，更简洁）
const user = await client.execute({
  sql: "SELECT * FROM users WHERE id = ?",
  args: [userId],
});

// 命名占位符
const inserted = await client.execute({
  sql: "INSERT INTO users (name, email) VALUES (:name, :email)",
  args: { name: "Iku", email: "iku@example.com" },
});
ResultSet字段:
  • rows
    — 行对象数组
  • columns
    — 按顺序排列的列名
  • rowsAffected
    — 写入操作影响的行数
  • lastInsertRowid
    — INSERT操作返回的
    bigint | undefined
    类型值

Transactions

事务

Batch Transactions (preferred for multi-statement writes)

批量事务（多语句写入的首选方式）

All statements execute atomically. Any failure rolls back the entire batch.
ts
await client.batch(
  [
    { sql: "INSERT INTO orders (user_id) VALUES (?)", args: [userId] },
    { sql: "UPDATE inventory SET stock = stock - 1 WHERE id = ?", args: [itemId] },
  ],
  "write",
);
所有语句原子性执行，任何失败都会回滚整个批次。
ts
await client.batch(
  [
    { sql: "INSERT INTO orders (user_id) VALUES (?)", args: [userId] },
    { sql: "UPDATE inventory SET stock = stock - 1 WHERE id = ?", args: [itemId] },
  ],
  "write",
);

Interactive Transactions (for conditional logic)

交互式事务（用于条件逻辑）

Use when write decisions depend on reads within the same transaction. Note: interactive transactions lock the database for up to 5 seconds — prefer batch transactions where possible.
ts
const tx = await client.transaction("write");
try {
  const { rows } = await tx.execute({
    sql: "SELECT balance FROM accounts WHERE id = ?",
    args: [accountId],
  });
  if ((rows[0].balance as number) >= amount) {
    await tx.execute({
      sql: "UPDATE accounts SET balance = balance - ? WHERE id = ?",
      args: [amount, accountId],
    });
    await tx.commit();
  } else {
    await tx.rollback();
  }
} catch (e) {
  await tx.rollback();
  throw e;
}
当写入决策依赖于同一事务内的读取操作时使用。注意：交互式事务会锁定数据库最多5秒——尽可能优先使用批量事务。
ts
const tx = await client.transaction("write");
try {
  const { rows } = await tx.execute({
    sql: "SELECT balance FROM accounts WHERE id = ?",
    args: [accountId],
  });
  if ((rows[0].balance as number) >= amount) {
    await tx.execute({
      sql: "UPDATE accounts SET balance = balance - ? WHERE id = ?",
      args: [amount, accountId],
    });
    await tx.commit();
  } else {
    await tx.rollback();
  }
} catch (e) {
  await tx.rollback();
  throw e;
}

Transaction Modes

事务模式

ModeSQLite CommandUse When
write
BEGIN IMMEDIATE
Mix of reads and writes
read
BEGIN TRANSACTION READONLY
Read-only; can parallelize on replicas
deferred
BEGIN DEFERRED
Unknown upfront; may fail if a write is in flight
模式SQLite命令使用场景
write
BEGIN IMMEDIATE
混合读写操作
read
BEGIN TRANSACTION READONLY
只读操作；可在副本上并行执行
deferred
BEGIN DEFERRED
前期未知操作类型；如果有写入操作正在进行可能会失败

Local Development

本地开发

Use environment variables to switch between local and remote transparently:
ts
// .env.local
TURSO_DATABASE_URL=file:local.db
// No TURSO_AUTH_TOKEN needed for local files

// .env.production
TURSO_DATABASE_URL=libsql://my-db-myorg.turso.io
TURSO_AUTH_TOKEN=eyJ...
Run a local libSQL server with libSQL-specific features (extensions, etc.):
bash
turso dev --db-file local.db
使用环境变量透明切换本地和远程环境：
ts
// .env.local
TURSO_DATABASE_URL=file:local.db
// 本地文件无需TURSO_AUTH_TOKEN

// .env.production
TURSO_DATABASE_URL=libsql://my-db-myorg.turso.io
TURSO_AUTH_TOKEN=eyJ...
运行带有libSQL专属功能（扩展等）的本地libSQL服务器：
bash
turso dev --db-file local.db

Connects at http://127.0.0.1:8080

连接地址为 http://127.0.0.1:8080

undefined
undefined

Embedded Replicas

嵌入式副本

Embedded replicas sync a remote Turso database into a local file. Reads are microsecond-speed (local). Writes go to the remote primary and are reflected locally immediately (read-your-writes semantics).
ts
const client = createClient({
  url: "file:replica.db",         // local file path
  syncUrl: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
  syncInterval: 60,               // auto-sync every 60 seconds (optional)
});

// Manually trigger sync
await client.sync();
When to use embedded replicas:
  • VMs / VPS deployments where the process is long-lived
  • Mobile apps needing offline-capable local data
  • Edge deployments with filesystem access
Do not use embedded replicas in:
  • Serverless environments without a persistent filesystem (use 
    https://
    instead)
  • Multiple concurrent processes writing to the same local file (risk of corruption)
See 
references/embedded-replicas.md
for sync patterns and deployment guides.
嵌入式副本将远程Turso数据库同步到本地文件。读取操作速度极快（本地）。写入操作提交到远程主库后会立即同步到本地（读己所写语义）。
ts
const client = createClient({
  url: "file:replica.db",         // 本地文件路径
  syncUrl: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
  syncInterval: 60,               // 自动同步间隔（可选，单位：秒）
});

// 手动触发同步
await client.sync();
何时使用嵌入式副本:
  • 进程长期运行的VM/VPS部署
  • 需要离线本地数据的移动应用
  • 具有文件系统访问权限的边缘部署
请勿在以下场景使用嵌入式副本:
  • 无持久文件系统的无服务器环境（改用
    https://
    ）
  • 多个并发进程写入同一本地文件（存在损坏风险）
同步模式和部署指南请参考
references/embedded-replicas.md
。

Vector Search

向量搜索

libSQL includes native vector search — no extension required. Use 
F32_BLOB
for embeddings (best balance of precision and storage).
sql
-- Schema
CREATE TABLE documents (
  id    INTEGER PRIMARY KEY,
  text  TEXT,
  embedding F32_BLOB(1536)  -- match your embedding model's dimensions
);

-- Create vector index (DiskANN-based ANN search)
CREATE INDEX documents_idx ON documents (libsql_vector_idx(embedding));

-- Insert with embedding
INSERT INTO documents (text, embedding)
VALUES ('Hello world', vector32('[0.1, 0.2, ...]'));

-- Query top-K nearest neighbors
SELECT d.id, d.text
FROM vector_top_k('documents_idx', vector32('[0.1, 0.2, ...]'), 5)
JOIN documents d ON d.rowid = id;
See 
references/vector-search.md
for index settings, distance functions, and RAG patterns.
libSQL内置原生向量搜索——无需扩展。使用
F32_BLOB
存储嵌入向量（精度和存储的最佳平衡）。
sql
-- 表结构
CREATE TABLE documents (
  id    INTEGER PRIMARY KEY,
  text  TEXT,
  embedding F32_BLOB(1536)  -- 匹配嵌入模型的维度
);

-- 创建向量索引（基于DiskANN的近似最近邻搜索）
CREATE INDEX documents_idx ON documents (libsql_vector_idx(embedding));

-- 插入带嵌入向量的数据
INSERT INTO documents (text, embedding)
VALUES ('Hello world', vector32('[0.1, 0.2, ...]'));

-- 查询Top-K最近邻
SELECT d.id, d.text
FROM vector_top_k('documents_idx', vector32('[0.1, 0.2, ...]'), 5)
JOIN documents d ON d.rowid = id;
索引设置、距离函数和RAG模式请参考
references/vector-search.md
。

Authentication & Security

认证与安全

  • Generate scoped auth tokens via the CLI: 
    turso db tokens create <db-name>
  • For group-level tokens: 
    turso group tokens create <group-name>
  • Rotate tokens with: 
    turso db tokens invalidate <db-name>
  • Use JWKS integration to let your auth provider (Clerk, Auth0) issue tokens directly
  • Apply fine-grained permissions to restrict tokens to specific tables or operations
See 
references/connection-and-auth.md
for token scoping, JWKS setup, and security checklist.
  • 通过CLI生成限定范围的认证令牌：
    turso db tokens create <db-name>
  • 生成组级令牌：
    turso group tokens create <group-name>
  • 轮换令牌：
    turso db tokens invalidate <db-name>
  • 使用JWKS集成，让你的认证提供商（Clerk、Auth0）直接颁发令牌
  • 应用细粒度权限，限制令牌只能访问特定表或执行特定操作
令牌范围、JWKS设置和安全检查清单请参考
references/connection-and-auth.md
。

CLI Quick Reference

CLI快速参考

bash
turso auth login                          # authenticate
turso db create my-db                    # create database
turso db show my-db                      # show URL and metadata
turso db tokens create my-db             # create auth token
turso db shell my-db                     # interactive SQL shell
turso db inspect my-db                   # storage stats and top queries
turso dev --db-file local.db             # local libSQL server
bash
turso auth login                          # 认证登录
turso db create my-db                    # 创建数据库
turso db show my-db                      # 查看URL和元数据
turso db tokens create my-db             # 创建认证令牌
turso db shell my-db                     # 交互式SQL shell
turso db inspect my-db                   # 存储统计信息和热门查询
turso dev --db-file local.db             # 启动本地libSQL服务器

Additional Resources

更多资源

  • references/connection-and-auth.md
     — Auth tokens, JWKS, fine-grained permissions, security checklist
  • references/vector-search.md
     — Vector types, index settings, distance functions, RAG query patterns
  • references/embedded-replicas.md
     — Sync strategies, encryption at rest, deployment guides
  • references/connection-and-auth.md
     — 认证令牌、JWKS、细粒度权限、安全检查清单
  • references/vector-search.md
     — 向量类型、索引设置、距离函数、RAG查询模式
  • references/embedded-replicas.md
     — 同步策略、静态加密、部署指南