turso-libsql

用途

本技能在用户提出“连接 Turso”“使用 libSQL”“搭建 Turso 数据库”“用 TypeScript 查询 Turso”等需求时使用，提供 Turso 与 libSQL 的使用指导。

Turso 是基于 libSQL 的 SQLite 兼容托管数据库平台。libSQL 是 SQLite 的生产级、开放贡献分支，新增原生向量搜索、扩展与异步 I/O，同时保持与 SQLite 完全向后兼容。

libSQL 与 Turso Database 的区别：libSQL 是 Turso Cloud 当前使用的久经考验的分支；Turso Database 是从零重写、针对极高密度与并发写入优化的版本（目前处于 beta）。对于工作负载稳定的新项目，通过 Turso Cloud 使用 libSQL；对于面向智能体、端侧或高密度场景的新项目，可考虑 Turso Database。

主要能力

连接 Turso：支持 libsql://（基于 WebSocket，适合持久连接）、https://（基于 HTTP，适合单次无服务器查询）、file:（本地 SQLite 文件，无需 authToken）、:memory:（测试用内存数据库）。
执行查询：支持简单查询、位置占位符（?）与命名占位符（:name），返回 ResultSet 包含 rows、columns、rowsAffected、lastInsertRowid。
事务：批量事务（多语句写入首选，原子执行，任一失败则整体回滚）与交互式事务（写入决策依赖同一事务内读取时使用；交互式事务会锁定数据库最多 5 秒，尽量优先批量事务）。事务模式包括 write（BEGIN IMMEDIATE，读写混合）、read（BEGIN TRANSACTION READONLY，只读，可在副本上并行）、deferred（BEGIN DEFERRED，事先不确定，若有写入进行中可能失败）。
本地开发：通过环境变量在本地与远程之间透明切换；可用 turso dev --db-file local.db 运行带 libSQL 特性的本地服务器（连接地址 http://127.0.0.1:8080）。
嵌入式副本：将远程 Turso 数据库同步到本地文件，读取为微秒级本地速度，写入发往远程主库并立即在本地体现（读己之写语义）。适用于长期运行的 VM/VPS 部署、需要离线本地数据的移动应用、有文件系统访问的边缘部署；不适用于无持久文件系统的无服务器环境（改用 https://）或多个并发进程写同一本地文件（有损坏风险）。
向量搜索：libSQL 内置原生向量搜索，无需扩展。使用 F32_BLOB 存储嵌入，可创建基于 DiskANN 的 ANN 向量索引，支持 vector32 插入与 vector_top_k 查询最近邻。
认证与安全：可通过 CLI 生成限定范围的 auth token（turso db tokens create <db-name>、turso group tokens create <group-name>），支持令牌轮换（turso db tokens invalidate <db-name>）、JWKS 集成（让 Clerk、Auth0 等认证提供方直接签发令牌）以及细粒度权限限制到特定表或操作。

使用方式

安装：

# TypeScript / JavaScript
npm install @libsql/client

# Python
pip install libsql-client

# Rust (Cargo.toml)
# libsql = "0.6"

# Go
# go get github.com/tursodatabase/go-libsql

连接 Turso（始终从环境变量加载凭据，切勿硬编码令牌）：

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

执行查询（始终使用参数化查询，切勿将用户输入拼接进 SQL 字符串）：

// 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" },
});

批量事务：

await client.batch(
  [
    { sql: "INSERT INTO orders (user_id) VALUES (?)", args: [userId] },
    { sql: "UPDATE inventory SET stock = stock - 1 WHERE id = ?", args: [itemId] },
  ],
  "write",
);

交互式事务：

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;
}

本地开发环境变量切换：

// .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...

嵌入式副本：

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

向量搜索：

-- 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;

CLI 快速参考：

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

适用场景

需要 SQLite 兼容的托管数据库，并希望使用向量搜索、嵌入式副本等增强能力。
在 TypeScript/JavaScript、Python、Rust、Go 项目中连接并查询 Turso。
需要本地开发与远程生产环境透明切换。
长期运行的服务器、移动应用或边缘部署需要本地低延迟读取与离线能力。
需要为数据库连接配置限定范围的认证令牌与细粒度权限。

限制

交互式事务会锁定数据库最多 5 秒，应尽量优先使用批量事务。
嵌入式副本不适用于无持久文件系统的无服务器环境，也不适用于多个并发进程写同一本地文件。
Turso Database 目前处于 beta。
关于索引设置、距离函数、RAG 查询模式、同步策略、静态加密、部署指南、令牌范围、JWKS 设置与安全清单等更多细节，资料指向 references/connection-and-auth.md、references/vector-search.md、references/embedded-replicas.md 等参考文件，具体内容暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制