# @drizzle-adapter/libsql 中文文档

规范地址：https://npmcn.com/package/%40drizzle-adapter/libsql/

版本：1\.1\.5
npm 元数据更新时间：2026-09-26T22:03:51.374Z
中文译文更新时间：2026-11-12T20:12:41.712Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40drizzle-adapter/libsql
原文对照：https://npmcn.com/package/%40drizzle-adapter/libsql/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：107 kB，58 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@libsql/client ^0\.15\.9 \|\| ^0\.17\.0
- 首次发布：2024-12-03T05:41:35.438Z
- 最新版本发布：2026-09-26T22:03:51.192Z
- 近 30 天下载量：22581（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 3 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @drizzle-adapter/libsql
```

也可以使用：`pnpm add @drizzle-adapter/libsql`、`yarn add @drizzle-adapter/libsql`、`bun add @drizzle-adapter/libsql`

## README

# @ rizzle- adapter/ libsql (小雨)

LibSQL适应器用于Drizzle适应器生态系统的实施,支持本地SQLite数据库和Turso.

## 概览

这个 `@drizzle-adapter/libsql` 软件包为 Drizzle 适应器接口提供 LibSQL 执行。 虽然你不直接与此软件包互动( 您使用 `@drizzle-adapter/core` 相反,它为Drizzle适应器生态系统中的LibSQL和Turso提供了支持.

## 为什么是LibSQL/Turso?

LibSQL和Turso提供了独特的优势:

-   **嵌入或无服务器**: 使用本地或Turso作为无服务器数据库
-   **SQLite 兼容性**: 建于 SQLite 上, 具有额外特性
-   **WebSocket 协议**: 低纬度的高效二进制协议
-   **自动复制**: 与 Turso 的内置复制
-   **边际计算**: 图尔索边缘网络的全球分布
-   **地方发展**: 以文件为基础的 SQLite 方便本地开发
-   **成本效益**: 与图尔索进行免费分级和基于使用定价
-   **多区域**: 与图尔索自动进行多区域部署

### 完美为:

1.  **边缘应用程序**: 数据来自最近的地点
2.  **地方发展**:嵌入式数据库以促进发展
3.  **混合部署**: 视需要将本地和服务器混合
4.  **成本敏感项目**: 视需要开始免费和规模化
5.  **全球应用**: 用 Turso 自动全局发行

## 安装

```bash
# Install both the core package and the LibSQL adapter
pnpm install @drizzle-adapter/core @drizzle-adapter/libsql
```

## 重要:适配器注册

适配器要正确使用 DrizzleAdapterFactory 操作,必须导入它进行自我注册的副作用:

```typescript
// Import for side effects - adapter will self-register
import '@drizzle-adapter/libsql';

// Now you can use the factory
import { DrizzleAdapterFactory } from '@drizzle-adapter/core';
```

## 使用量

### 配置

```typescript
import { DrizzleAdapterFactory, TypeDrizzleDatabaseConfig } from '@drizzle-adapter/core';

// Local SQLite database
const localConfig: TypeDrizzleDatabaseConfig = {
  DATABASE_DRIVER: 'libsql',
  DATABASE_URL: 'file:local.db'
};

// Turso database
const tursoConfig: TypeDrizzleDatabaseConfig = {
  DATABASE_DRIVER: 'libsql',
  DATABASE_URL: 'libsql://your-database-url.turso.io',
  DATABASE_AUTH_TOKEN: 'your-auth-token',
  DATABASE_SYNC_URL: 'file:local-replica.db' // Optional sync URL for replica
};

const factory = new DrizzleAdapterFactory();
const adapter = factory.create(config);
```

### Schema 定义

```typescript
const dataTypes = adapter.getDataTypes();

const users = dataTypes.dbTable('users', {
  id: dataTypes.dbInteger('id').primaryKey().autoincrement(),
  name: dataTypes.dbText('name').notNull(),
  email: dataTypes.dbText('email').notNull().unique(),
  metadata: dataTypes.dbText('metadata'), // JSON stored as text
  createdAt: dataTypes.dbInteger('created_at')
    .default(sql`(strftime('%s', 'now'))`)
});

const posts = dataTypes.dbTable('posts', {
  id: dataTypes.dbInteger('id').primaryKey().autoincrement(),
  userId: dataTypes.dbInteger('user_id')
    .references(() => users.id),
  title: dataTypes.dbText('title').notNull(),
  content: dataTypes.dbText('content').notNull(),
  published: dataTypes.dbInteger('published').default(0),
  createdAt: dataTypes.dbInteger('created_at')
    .default(sql`(strftime('%s', 'now'))`)
});
```

### 基本 CRUD 操作

```typescript
import { eq, and, or, desc, sql } from 'drizzle-orm';

const client = await adapter.getConnection().getClient();

// INSERT
// Single insert with returning
const [newUser] = await client
  .insert(users)
  .values({
    name: 'John Doe',
    email: 'john@example.com',
    metadata: JSON.stringify({ role: 'user' })
  })
  .returning();

// Bulk insert
await client
  .insert(posts)
  .values([
    {
      userId: newUser.id,
      title: 'First Post',
      content: 'Hello, world!'
    },
    {
      userId: newUser.id,
      title: 'Second Post',
      content: 'Another post'
    }
  ]);

// SELECT
// Select all
const allUsers = await client
  .select()
  .from(users);

// Select with conditions
const user = await client
  .select()
  .from(users)
  .where(eq(users.email, 'john@example.com'));

// Select with join
const userPosts = await client
  .select({
    userName: users.name,
    postTitle: posts.title,
    content: posts.content,
    metadata: users.metadata,
    createdAt: sql`datetime(${posts.createdAt}, 'unixepoch')`
  })
  .from(posts)
  .leftJoin(users, eq(posts.userId, users.id))
  .where(eq(posts.published, 1))
  .orderBy(desc(posts.createdAt));

// UPDATE
await client
  .update(users)
  .set({
    name: 'John Smith',
    metadata: JSON.stringify({ role: 'admin' })
  })
  .where(eq(users.id, newUser.id));

// DELETE
await client
  .delete(posts)
  .where(
    and(
      eq(posts.userId, newUser.id),
      eq(posts.published, 0)
    )
  );
```

### 全文搜索

```typescript
// Create FTS table
await client.execute(sql`
  CREATE VIRTUAL TABLE posts_fts USING fts5(
    title, content,
    content='posts',
    content_rowid='id'
  )
`);

// Search posts
const searchResults = await client
  .select({
    title: posts.title,
    content: posts.content,
    author: users.name,
    rank: sql`rank`
  })
  .from(posts)
  .leftJoin(users, eq(posts.userId, users.id))
  .where(sql`posts.id IN (
    SELECT rowid 
    FROM posts_fts 
    WHERE posts_fts MATCH ${searchTerm}
    ORDER BY rank
  )`);
```

## 最佳做法

### 地方发展

```typescript
// Use file-based SQLite for development
const devAdapter = factory.create({
  DATABASE_DRIVER: 'libsql',
  DATABASE_URL: 'file:dev.db'
});
```

### 与Turso一起生产

```typescript
// Use Turso for production
const prodAdapter = factory.create({
  DATABASE_DRIVER: 'libsql',
  DATABASE_URL: process.env.DATABASE_URL,
  DATABASE_AUTH_TOKEN: process.env.DATABASE_AUTH_TOKEN
});
```

### 复制支持

```typescript
// Use local replica for better performance
const replicaAdapter = factory.create({
  DATABASE_DRIVER: 'libsql',
  DATABASE_URL: process.env.DATABASE_URL,
  DATABASE_AUTH_TOKEN: process.env.DATABASE_AUTH_TOKEN,
  DATABASE_SYNC_URL: 'file:local-replica.db'
});
```

## 最佳做法

1.  **发展流动**: 使用基于文件的 SQLite 进行开发
2.  **生产**: 使用Turso进行生产部署
3.  **复制品**:利用当地复制品提高性能
4.  **JSON 处理**:将JSON作为TEXT存储,并视需要进行剖析/字符串
5.  **查询优化**: 使用索引和FTS改进性能

## 捐款

我们欢迎捐款! 请随意提交拉力请求 对于重大变动,请先开出一个问题来讨论你想要改变什么.

## 相关软件包

-   [@ 细雨适应器/ 核心](https://npmcn.com/package/%40drizzle-adapter/core) - 核心接口和类型
-   [@ 细雨适应器/ sqlite- core](https://npmcn.com/package/%40drizzle-adapter/sqlite-core) - 共享 SQLite 功能

## 常见问题

### 如何安装 @drizzle-adapter/libsql？

在项目目录运行 npm install @drizzle-adapter/libsql，或使用 pnpm add / yarn add / bun add。

### @drizzle-adapter/libsql 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @drizzle-adapter/libsql 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @drizzle-adapter/libsql 可以商用吗？

@drizzle-adapter/libsql 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @drizzle-adapter/libsql 的下载量有多少？

根据 npm 官方下载统计，@drizzle-adapter/libsql 在 2026/10/13 – 2026/11/11 这 30 天内被下载 22,581 次，日均约 753 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @drizzle-adapter/libsql 还在维护吗？

最新版本 1\.1\.5 发布于 2026/09/27（1 个月前）；至今共发布 15 个版本，其中过去 12 个月发布了 3 个；首次发布于 2024/12/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。