turso

Turso 数据库

适用于现代应用、AI Agent 和边缘计算的 SQLite 兼容嵌入式数据库。

链接

• 文档
• 更新日志
• GitHub

快速导航

主题	参考资料
安装	installation.md
加密	encryption.md
授权	auth.md
同步	sync.md
Agent 数据库	agents.md

适用场景

• 支持云同步的嵌入式 SQLite 数据库
• AI Agent 状态管理和多 Agent 协调
• 离线优先型应用
• 加密数据库（AEGIS、AES-GCM）
• 边缘计算和 IoT 设备

核心概念

libSQL

Turso 基于 libSQL 构建。libSQL 是 SQLite 的开源分支，具备以下特性：

• 原生加密（AEGIS-256、AES-GCM）
• 异步 I/O（Linux io_uring）
• 云同步功能

部署选项

1. 嵌入式 — 在应用中本地运行
2. Turso Cloud — 提供分支和备份功能的托管平台
3. 混合模式 — 本地运行并与云同步（推送/拉取）

常见模式

加密数据库

openssl rand -hex 32  # Generate key
tursodb --experimental-encryption "file:db.db?cipher=aegis256&hexkey=YOUR_KEY"

云同步

import { connect } from "@tursodatabase/sync";

const db = await connect({
  path: "./local.db",
  url: "turso://...", // also accepts "libsql://..." — both schemes work
  authToken: process.env.TURSO_AUTH_TOKEN,
});

await db.push(); // local → cloud
await db.pull(); // cloud → local

Agent 数据库

import { connect } from "@tursodatabase/database";

// Local-first
const db = await connect("agent.db");

// Or with sync
const db = await connect({
  path: "agent.db",
  url: "https://db.turso.io",
  authToken: "...",
  sync: "full",
});

版本

基于产品版本：0.7.2

发布说明

0.7.1 – 0.7.2

• JS/无服务器 SDK：transactionAsync() 是新的闭包安全事务 API。transaction() 现已弃用——事务可以并发运行时，其闭包语义并不可靠，因为通过外层 db/conn 实例捕获的语句可能会乱序调度。请将事务回调迁移为使用传入 transactionAsync() 的 txn 句柄，而不是闭包引用外层实例（参见 references/agents.md）。
• 重大变更：Connection.execute() 已从无服务器驱动的原生镜像接口（connect()）中移除。该接口现已与 @tursodatabase/database 一致，并改为公开 run/get/all/iterate/exec/batch/transaction(Async)。兼容 libsql 的 createClient() 层仍保留自己的 execute()，不受影响（参见 references/auth.md）。
• 修复了 execute()/batch() 后 inTransaction 标志未更新的问题，该问题可能导致服务端写事务在约束错误后仍保持打开状态。
• 通过尾部查询选项参数传入的每查询 requestHeaders，可让你为单次调用附加自定义标头（例如请求身份标头），而不必仅在连接级别设置。
• 同步引擎：现在会在首次连接时自动检测远程拉取协议（基于页面的 WAL 与 MVCC 逻辑日志），因此旧的 logical_mvcc_pull 标志从必需项变为可选的手动覆盖项。WAL 模式的本地副本与 MVCC 远程端同步时，会自动就地转换为 MVCC 日志模式。
• 同步绑定（Rust、Python、JavaScript、Go、React Native）现在可互换使用 turso:// 和 libsql:// 远程 URL。
• 核心修复：修复了导致 InSeek 退化为全表扫描的 IN (...) 列表查询成本回归、因约束检查前索引变更而遗留的 UPSERT 缺失索引、MVCC 下序列导致的变更计数泄漏，以及针对具有复合主键或非 rowid 主键表的 DELETE/upsert 重放错误。

0.7.0

• SQL 层：符合 SQL 标准的标量函数及与 PostgreSQL 兼容的别名、PostgreSQL 风格的序列、支持 MVCC 的 AUTOINCREMENT、窗口函数相关工作（在 VDBE 聚合机制上实现 row_number()，以及窗口子句中的 FILTER），还有 WITHIN GROUP 有序集聚合。
• MVCC/持久性：用于 MVCC 的被动检查点、适用于 Turso 同步的可移植逻辑日志元数据，以及 Aristo WAL 验证。
• 排序规则：核心自定义排序规则支持，以及基于区域设置的排序规则。
• .NET / 平台：NativeAOT 静态链接、远程事务和批处理、Turso EF Core SQLite 提供程序、NuGet 原生目标，以及 Windows ARM64 CLI 发行版。

早期版本（0.6.0）

JS/无服务器超时、交互式事务、Python SQLAlchemy 改进（sqlalchemy-libsql）、基于 npm 的 CLI 分发，以及面向本地优先/Agent 工作负载的更广泛 SQL 功能——这些仍然有效，详见 references/agents.md 和 references/installation.md。