turso-db

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Turso Database

Turso数据库

Turso is an in-process SQL database compatible with SQLite, written in Rust.

Never search the web for libsql or @libsql/client — those are outdated packages replaced by @tursodatabase. Read the SDK and reference files listed below — they have everything you need to write working code.

Turso是一款用Rust编写的进程内SQL数据库，与SQLite兼容。

请勿在网络上搜索libsql或@libsql/client相关内容——这些是已被@tursodatabase取代的旧版包。请阅读下方列出的SDK及参考文件，其中包含编写可运行代码所需的全部信息。

Critical Rules

重要规则

Before writing any Turso code, you MUST know these constraints:

BETA software — not all SQLite features are implemented yet
No multi-process access — only one process can open a database file at a time
No WITHOUT ROWID tables — all tables must have a rowid
No vacuum — VACUUM is not supported
UTF-8 only — the only supported character encoding
WAL is the default journal mode — legacy SQLite modes (delete, truncate, persist) are not supported
FTS requires compile-time
fts
feature — not available in all builds
Encryption requires
--experimental-encryption
flag — not enabled by default
MVCC is experimental and not production ready —
```
PRAGMA journal_mode = experimental_mvcc
```
Vector distance: lower = closer — ORDER BY distance ASC for nearest neighbors

在编写任何Turso代码前，你必须了解以下限制：

测试版软件——尚未实现所有SQLite功能
不支持多进程访问——同一时间仅能有一个进程打开数据库文件
无WITHOUT ROWID表——所有表必须包含rowid
不支持VACUUM命令——VACUUM操作未被实现
仅支持UTF-8编码——唯一支持的字符编码为UTF-8
默认日志模式为WAL——不支持SQLite传统日志模式（delete、truncate、persist）
全文搜索（FTS）需编译时开启
fts
特性——并非所有构建版本均支持
加密需使用
--experimental-encryption
参数——默认未启用
MVCC处于实验阶段，暂不适合生产环境——需通过
```
PRAGMA journal_mode = experimental_mvcc
```
开启
向量距离：值越小越接近——需使用ORDER BY distance ASC来获取最近邻结果

Feature Decision Tree

功能决策树

Use this to decide which reference file to load:

Need vector similarity search? (embeddings, nearest neighbors, cosine distance) → Read

references/vector-search.md

Need full-text search? (keyword search, BM25 ranking, tokenizers, fts_match/fts_score) → Read

references/full-text-search.md

Need to track database changes? (audit log, change feed, replication) → Read

references/cdc.md

Need concurrent write transactions? (multiple writers, snapshot isolation, BEGIN CONCURRENT) → Read

references/mvcc.md

Need database encryption? (encryption at rest, AES-GCM, AEGIS ciphers) → Read

references/encryption.md

Need remote sync / replication? (push/pull, offline-first, Turso Cloud, embedded replicas) → Read

references/sync.md

使用以下决策树选择对应的参考文件：

需要向量相似度搜索？（嵌入向量、最近邻、余弦距离） → 阅读

references/vector-search.md

需要全文搜索？（关键词搜索、BM25排序、分词器、fts_match/fts_score） → 阅读

references/full-text-search.md

需要追踪数据库变更？（审计日志、变更流、复制） → 阅读

references/cdc.md

需要并发写入事务？（多写入者、快照隔离、BEGIN CONCURRENT） → 阅读

references/mvcc.md

需要数据库加密？（静态加密、AES-GCM、AEGIS加密算法） → 阅读

references/encryption.md

需要远程同步/复制？（推送/拉取、离线优先、Turso Cloud、嵌入式副本） → 阅读

references/sync.md

SDK Decision Tree

SDK决策树

JavaScript / TypeScript / Node.js? → Read

sdks/javascript.md

Browser / WebAssembly / WASM? → Read

sdks/wasm.md

React Native / Mobile? → Read

sdks/react-native.md

Rust? → Read

sdks/rust.md

Python? → Read

sdks/python.md

Go? → Read

sdks/go.md

使用JavaScript/TypeScript/Node.js？ → 阅读

sdks/javascript.md

使用浏览器/WebAssembly/WASM？ → 阅读

sdks/wasm.md

使用React Native/移动端？ → 阅读

sdks/react-native.md

使用Rust？ → 阅读

sdks/rust.md

使用Python？ → 阅读

sdks/python.md

使用Go？ → 阅读

sdks/go.md

SDK Install Quick Reference

SDK安装速查

Language	Package	Install Command
JavaScript (Node.js)	`@tursodatabase/database`	`npm i @tursodatabase/database`
JavaScript Sync	`@tursodatabase/sync`	`npm i @tursodatabase/sync`
WASM (Browser)	`@tursodatabase/database-wasm`	`npm i @tursodatabase/database-wasm`
WASM + Sync	`@tursodatabase/sync-wasm`	`npm i @tursodatabase/sync-wasm`
React Native	`@tursodatabase/sync-react-native`	`npm i @tursodatabase/sync-react-native`
Rust	`turso`	`cargo add turso`
Python	`pyturso`	`pip install pyturso`
Go	`tursogo`	`go get turso.tech/database/tursogo`

语言	包名	安装命令
JavaScript（Node.js）	`@tursodatabase/database`	`npm i @tursodatabase/database`
JavaScript同步包	`@tursodatabase/sync`	`npm i @tursodatabase/sync`
WASM（浏览器）	`@tursodatabase/database-wasm`	`npm i @tursodatabase/database-wasm`
WASM + 同步	`@tursodatabase/sync-wasm`	`npm i @tursodatabase/sync-wasm`
React Native	`@tursodatabase/sync-react-native`	`npm i @tursodatabase/sync-react-native`
Rust	`turso`	`cargo add turso`
Python	`pyturso`	`pip install pyturso`
Go	`tursogo`	`go get turso.tech/database/tursogo`

CLI Quick Reference

CLI速查

bash

undefined

bash

undefined

Install Turso CLI

安装Turso CLI

curl --proto '=https' --tlsv1.2 -LsSf
https://github.com/tursodatabase/turso/releases/latest/download/turso_cli-installer.sh | sh

Or via Homebrew

或通过Homebrew安装

brew install turso

Start interactive SQL shell

启动交互式SQL shell

tursodb

Open a database file

打开数据库文件

tursodb mydata.db

Read-only mode

只读模式

tursodb --readonly mydata.db

Start MCP server

启动MCP服务器

tursodb your.db --mcp

undefined

tursodb your.db --mcp

undefined

SQL Quick Reference

SQL速查

sql

-- Create table
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT);

-- Insert
INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');

-- Select
SELECT * FROM users WHERE name = 'Alice';

-- Update
UPDATE users SET email = 'new@example.com' WHERE id = 1;

-- Delete
DELETE FROM users WHERE id = 1;

-- Transactions
BEGIN TRANSACTION;
INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com');
COMMIT;

sql

-- 创建表
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT);

-- 插入数据
INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');

-- 查询数据
SELECT * FROM users WHERE name = 'Alice';

-- 更新数据
UPDATE users SET email = 'new@example.com' WHERE id = 1;

-- 删除数据
DELETE FROM users WHERE id = 1;

-- 事务处理
BEGIN TRANSACTION;
INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com');
COMMIT;

MCP Server

MCP服务器

Turso can run as an MCP (Model Context Protocol) server:

bash

tursodb your.db --mcp

This starts a server that exposes the database via the MCP protocol, allowing AI tools and agents to query and modify the database directly.

Turso可作为MCP（模型上下文协议）服务器运行：

bash

tursodb your.db --mcp

启动服务器后，将通过MCP协议暴露数据库，允许AI工具和Agent直接查询及修改数据库。

Complete File Index

完整文件索引

File	Description
`SKILL.md`	Main entry point — decision trees, critical rules, quick references
`references/vector-search.md`	Vector types, distance functions, semantic search examples
`references/full-text-search.md`	FTS with Tantivy: tokenizers, query syntax, fts_match/fts_score/fts_highlight
`references/cdc.md`	Change Data Capture: modes, CDC table schema, usage examples
`references/mvcc.md`	MVCC: BEGIN CONCURRENT, snapshot isolation, conflict handling
`references/encryption.md`	Page-level encryption: ciphers, key setup, URI format
`references/sync.md`	Remote sync: push/pull, conflict resolution, bootstrap, WAL streaming
`sdks/javascript.md`	@tursodatabase/database: connect, prepare, run/get/all/iterate
`sdks/wasm.md`	@tursodatabase/database-wasm: browser WASM, OPFS, sync-wasm
`sdks/react-native.md`	@tursodatabase/sync-react-native: mobile, sync, encryption
`sdks/rust.md`	turso crate: Builder, async execute/query, sync feature
`sdks/python.md`	pyturso: DB-API 2.0, turso.aio async, turso.sync remote
`sdks/go.md`	tursogo: database/sql driver, no CGO, sync driver

文件	描述
`SKILL.md`	主入口——决策树、重要规则、速查参考
`references/vector-search.md`	向量类型、距离函数、语义搜索示例
`references/full-text-search.md`	基于Tantivy的全文搜索：分词器、查询语法、fts_match/fts_score/fts_highlight
`references/cdc.md`	变更数据捕获：模式、CDC表结构、使用示例
`references/mvcc.md`	MVCC：BEGIN CONCURRENT、快照隔离、冲突处理
`references/encryption.md`	页级加密：加密算法、密钥设置、URI格式
`references/sync.md`	远程同步：推送/拉取、冲突解决、初始化、WAL流
`sdks/javascript.md`	@tursodatabase/database：连接、预处理、run/get/all/iterate方法
`sdks/wasm.md`	@tursodatabase/database-wasm：浏览器WASM、OPFS、sync-wasm
`sdks/react-native.md`	@tursodatabase/sync-react-native：移动端、同步、加密
`sdks/rust.md`	turso crate：Builder、异步execute/query、同步特性
`sdks/python.md`	pyturso：DB-API 2.0、turso.aio异步、turso.sync远程
`sdks/go.md`	tursogo：database/sql驱动、无CGO、同步驱动