Astro DB

Astro DB 是一款专为 Astro 设计的全托管 SQL 数据库。你可以在本地开发或者连接到我们 Astro Studio 平台上托管的数据库。

安装

使用 @astrojs/db 集成（v0.8.1 或更高版本）来将 Astro DB 添加到新的或现有的 Astro 项目中（需要 astro@4.5 或更高版本）。Astro 包含一个内置的 astro add 命令能帮你自动化设置此过程。

npx astro add db

pnpm astro add db

yarn astro add db

如果你愿意，也可以手动安装 @astrojs/db。

定义你的数据库

Astro DB 是一个用于配置、开发和查询你的数据的完整解决方案。每当你运行 astro dev 时，都会创建一个本地数据库，并使用 libSQL 来管理你的数据，而无需 Docker 或网络连接。

使用 astro add 命令安装 @astrojs/db 将在你的项目中创建一个 db/config.ts 文件，你将在其中定义你的数据库表：

import { defineDb } from 'astro:db';

export default defineDb({
  tables: { },
})

表

Astro DB 中的数据是通过 SQL 表存储的。表将你的数据结构化为行和列，其中列强制每行值的类型。

当你定义一个表时，Astro 将为你的项目生成一个 TypeScript 接口来查询该表。这意味着当你访问数据时，将获得完整的 TypeScript 支持，包括属性自动完成和类型检查。

要配置数据库表，应从 astro:db 导入并使用 defineTable() 和 column 工具。

这个例子配置了一个 Comment 表，它有 author 和 body 的必需文本列。然后，通过 defineDb() 导出使其在你的项目中可用。

import { defineDb, defineTable, column } from 'astro:db';

const Comment = defineTable({
  columns: {
    author: column.text(),
    body: column.text(),
  }
})

export default defineDb({
  tables: { Comment },
})

查看表配置参考以获取完整的表选项参考。

列

Astro DB 支持以下列类型：

import { defineTable, column } from 'astro:db';

const Comment = defineTable({
  columns: {
    // A string of text.
    author: column.text(),
    // A whole integer value.
    likes: column.number(),
    // A true or false value.
    flagged: column.boolean(),
    // Date/time values queried as JavaScript Date objects.
    published: column.date(),
    // An untyped JSON object.
    metadata: column.json(),
  }
});

查看表的列参考以获取更多细节。

表引用

表之间的关系是数据库设计中的常见架构。例如，一个 Blog 表可能与 Comment、Author 和 Category 等其他几个表密切相关。

你可以使用引用列定义来这些表之间的关系并将它们保存到你的数据库中。要建立关系，你需要：

在被引用的表上有一个标识符列。这通常是带有 primaryKey 属性的 id 列。
在基础表上有一个用于存储被引用 id 的列。这将使用 references 属性来建立关系。

这个例子显示了一个 Comment 表的 authorId 列引用了 Author 表的 id 列。

const Author = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    name: column.text(),
  }
});

const Comment = defineTable({
  columns: {
    authorId: column.number({ references: () => Author.columns.id }),
    body: column.text(),
  }
});

为你的数据库填充数据

在开发过程中，Astro 将使用你的 DB 配置并根据你的架构生成本地类型。这些内容将在每次启动开发服务器时重新生成，并允许你使用类型安全和自动补全来查询和处理你的数据样例。

要为你的 Astro 项目填充开发数据进行测试和调试，你需要创建一个 db/seed.ts 文件。从 astro:db 导入 db 对象和任何配置的表，然后使用 db.insert() 函数提供一个表行数据对象的数组。

以下例子为 Comment 表定义了两行开发数据：

import { db, Comment, Author } from 'astro:db';

export default async function() {
  await db.insert(Author).values([
    { id: 1, name: "Kasim" },
    { id: 2, name: "Mina" },
  ]);

  await db.insert(Comment).values([
    { authorId: 1, body: 'Hope you like Astro DB!' },
    { authorId: 2, body: 'Enjoy!'},
  ])
}

你的开发服务器将在此文件更改时自动重启你的数据库，然后重新生成你的类型并从 seed.ts 填充你的开发数据。

查询你的数据库

你可以从项目中的任何 Astro 页面或端点使用提供的 db ORM 和查询构建器来查询你的数据库。

Drizzle ORM

import { db } from 'astro:db';

Astro DB 包含一个内置的 Drizzle ORM 客户端。使用该客户端无需设置或手动配置。当你运行 Astro 时，Astro DB 的 db 客户端会自动配置以与你的数据库（本地或远程）进行通信。它使用你明确的数据库架构定义进行类型安全的 SQL 查询，当你引用不存在的列或表时，会出现 TypeScript 错误。

查询

以下例子选择了 Comment 表的所有行。这将返回来自 db/seed.ts 全量的填充的开发数据数组，然后可以在你的页面模板中使用它们：

---
import { db, Comment } from 'astro:db';

const comments = await db.select().from(Comment);
---

<h2>Comments</h2>

{
  comments.map(({ author, body }) => (
    <article>
      <p>Author: {author}</p>
      <p>{body}</p>
    </article>
  ))
}

查看 Drizzle select() API 参考以获取完整概述。

插入

要接受用户输入，如处理表单请求并将数据插入到你的远程托管数据库，需要为你的 Astro 项目配置按需渲染并为你的部署环境添加一个 SSR 适配器。

这个例子基于解析后表单的 POST 请求向 Comment 表插入一行：

---
import { db, Comment } from 'astro:db';

if (Astro.request.method === 'POST') {
  // 解析表单数据
  const formData = await Astro.request.formData();
  const author = formData.get('author');
  const content = formData.get('content');
  if (typeof author === 'string' && typeof content === 'string') {
    // 将表单数据插入到 Comment 表中
    await db.insert(Comment).values({ author, content });
  }
}

// 在每次请求上渲染新的评论列表
const comments = await db.select().from(Comment);
---

<form method="POST" style="display: grid">
  <label for="author">Author</label>
  <input id="author" name="author" />

  <label for="content">Content</label>
  <textarea id="content" name="content"></textarea>

  <button type="submit">Submit</button>
</form>

<!--渲染 `comments`-->

你也可以从 API 端点查询你的数据库。这个例子通过 id 参数从 Comment 表中删除一行：

import type { APIRoute } from "astro";
import { db, Comment, eq } from 'astro:db';

export const DELETE: APIRoute = async (ctx) => {
  await db.delete(Comment).where(eq(Comment.id, ctx.params.id ));
  return new Response(null, { status: 204 });
}

查看 Drizzle insert() API 参考以获取完整概述。

过滤

要通过特定属性查询表结果，请使用 Drizzle 的部分查询选项。例如，向你的 select() 查询添加一个 .where() 调用，并传递你想做的比较操作。

以下例子查询了 Comment 表中包含 “Astro DB” 短语的所有行。使用 like() 操作符检查 body 中是否存在短语：

---
import { db, Comment, like } from 'astro:db';

const comments = await db.select().from(Comment).where(
    like(Comment.body, '%Astro DB%')
);
---

Drizzle 辅助工具

所有用于构建查询的 Drizzle 辅助工具都从 astro:db 模块中暴露出来。这包括：

过滤操作符如 eq() 和 gt()
聚合辅助工具如 count()
用于编写原始 SQL 查询语句的 sql 辅助工具

import { eq, gt, count, sql } from 'astro:db';

关系

你可以使用 SQL 连接从多个表查询关联的数据。要创建一个连接查询，请使用连接操作符扩展你的 db.select() 语句。每个函数都接受一个要连接的表和一个条件来匹配两个表之间的行。

这个例子使用了 innerJoin() 函数将 Comment 的作者与他们相关的 Author 信息连接起来，基于 authorId 列。这将返回一个对象数组，每个 Author 和 Comment 行作为顶级属性：

---
import { db, eq, Comment, Author } from 'astro:db';

const comments = await db.select()
  .from(Comment)
  .innerJoin(Author, eq(Comment.authorId, Author.id));
---

<h2>Comments</h2>

{
  comments.map(({ Author, Comment }) => (
    <article>
      <p>Author: {Author.name}</p>
      <p>{Comment.body}</p>
    </article>
  ))
}

查看 Drizzle 连接参考以获取所有可用的连接操作符和配置选项。

批处理事务

所有远程数据库查询都作为网络请求进行。当进行大量查询，或者如果任何查询失败需要自动回滚时，你可能需要将查询批量处理为单个事务。

这个例子使用 db.batch() 方法在单个请求中填充多行：

import { db, Author, Comment } from 'astro:db';

export default async function () {
  const queries = [];
  // 使用单个网络请求将 100 个样本数据填充到你的远程数据库中。
  for (let i = 0; i < 100; i++) {
    queries.push(db.insert(Comment).values({ body: `Test comment ${i}` }));
  }
  await db.batch(queries);
}

查看 Drizzle db.batch() 文档以获取更多详细信息。

Astro Studio

Studio 功能

Astro DB 可以连接到 Astro Studio 平台，快速为你的项目添加一个托管数据库。你可以从 Astro Studio 仪表盘上查看、管理和部署新的托管数据库。

Astro Studio 网页门户允许你通过网页界面或使用 CLI 命令连接并管理你的远程托管的 Astro DB 数据库。

在你的 Studio 仪表板，你可以访问账号管理、帮助文章和支持消息控制台等。

访问 Astro Studio 进行注册或登录。

创建新的 Studio 项目

Studio 功能

在 Astro Studio 中有两种方式创建项目:

使用 Astro Studio 网页界面从新的或现有的 GitHub 仓库创建。

点击页头中的 “create project” 按钮并按照说明开始操作。Astro Studio 将连接到你的 GitHub 仓库，并为你的项目创建一个新的托管数据库。

使用 Astro Studio CLI 从任何本地 Astro 项目创建。你可以运行以下命令开始:

# 使用你的 GitHub 账号登录到 Astro Studio
npx astro login

# 根据提示链接到一个新的项目
npx astro link

# (可选) 将你的本地数据库配置推送到远程数据库
npx astro db push

# 使用你的 GitHub 账号登录到 Astro Studio
pnpm astro login

# 根据提示链接到一个新的项目
pnpm astro link

# (可选) 将你的本地数据库配置推送到远程数据库
pnpm astro db push

# 使用你的 GitHub 账号登录到 Astro Studio
yarn astro login

# 根据提示链接到一个新的项目
yarn astro link

# (可选) 将你的本地数据库配置推送到远程数据库
yarn astro db push

一旦你已经成功登录并链接，你就可以运行所有的 Astro DB 命令来管理你的远程数据库。

查看 Astro DB CLI 参考获取所有可用命令。

使用 Studio 连接进行部署

Studio 功能

你可以使用与你的 Studio 数据库的实时连接来部署你的 Astro DB 项目。这可以在任何使用静态构建或 SSR 适配器的部署平台上实现。

首先，配置你的构建命令以使用 --remote 标志与 Studio 连接。这个示例将该标志应用到你项目 package.json 中的 "build" 脚本。如果你的部署平台接受构建命令，确保这被设置成 npm run build。

{
  "scripts": {
    "build": "astro build --remote"
  }
}

创建一个 Studio 应用令牌

你需要创建一个应用令牌来从生产部署访问你的 Studio 数据库。你可以通过导航到 Settings 标签页并选择 Tokens 从你的 Studio 项目仪表板创建一个应用令牌。

复制生成的令牌并在你的部署平台中使用名称 ASTRO_STUDIO_APP_TOKEN 作为环境变量 / 环境秘钥。

设置 GitHub CI Action

Studio 功能

你可以使用 Studio CI 流水线自动推送模式更改到你的 Studio 数据库。每当你合并到 main 时，这将会校验更改是否可以安全地进行，并且都会保持你的配置更新。

按照 GitHub 的文档在你的仓库中配置一个新的秘钥，名称为 ASTRO_STUDIO_APP_TOKEN，并将你的 Studio 应用令牌作为秘钥的值。

一旦你的秘钥配置好，就在你的项目的 .github/workflows 目录中创建一个新的 GitHub Actions 工作流文件，将检出仓库和安装 Node.js 作为步骤，并使用 withastro/action-studio 动作来同步模式更改。

该动作会在所有事件触发器上运行 astro db verify，以确保架构更改可以安全地应用。如果你特别添加了 push 触发器，那么该动作会将这些更改推送到你的 Studio 数据库。

这个示例 GitHub Action _studio.yml 在 main 分支更新时推送更改：

name: Astro Studio

env:
  ASTRO_STUDIO_APP_TOKEN: ${{secrets.ASTRO_STUDIO_APP_TOKEN }}

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, reopened, synchronize]

jobs:
  DB:
    permissions:
      contents: read
      actions: read
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - uses: jaid/action-npm-install@v1.2.1
      - uses: withastro/action-studio@main

推送表架构

Studio 功能

随着你项目的增长，你的表架构也会随着时间的推移而改变。你可以在本地安全地测试配置更改，并在部署时推送到你的 Studio 数据库。

在从仪表板创建 Studio 项目时，你将有创建 GitHub CI 流水线的选项。这将在与你的仓库的主分支合并时自动迁移架构更改。

你也可以通过 CLI 使用 astro db push --remote 命令将本地架构更改推送到 Astro Studio：

npm run astro db push --remote

pnpm astro db push --remote

yarn astro db push --remote

此命令将验证你的本地更改是否可以在不丢失数据的情况下进行，并在必要时，建议如何安全地修改你的架构以解决冲突。

推送破坏性架构更改

如果你必须以一种与 Astro Studio 托管的现有数据不兼容的方式更改你的表架构，你将需要重置你的生产数据库。

要推送包含破坏性更改的表架构更新，请添加 --force-reset 标志以重置所有生产数据：

npm run astro db push --remote --force-reset

pnpm astro db push --remote --force-reset

yarn astro db push --remote --force-reset

重命名表

Studio 功能

在将你的架构推送到 Astro Studio 之后，可以重命名一个表。

如果你没有任何重要的生产数据，那么你可以使用 --force-reset 标志重置你的数据库。这个标志将会删除数据库中的所有表，并创建新的表，以便它完全匹配你当前的架构。

为了在保留你的生产数据的同时重命名一个表，你必须执行一系列非破坏性更改，以安全地将你的本地架构推送到 Astro Studio。

以下示例将一个表从 Comment 重命名为 Feedback：

在你的数据库配置文件中，为你想要重命名的表添加 deprecated: true 属性：

const Comment = defineTable({
  deprecated: true,
  columns: {
    author: column.text(),
    body: column.text(),
  }
});

添加一个新的表架构（完全匹配现有表的属性）并使用新名称：

const Comment = defineTable({
  deprecated: true,
  columns: {
    author: column.text(),
    body: column.text(),
  }
});

const Feedback = defineTable({
  columns: {
    author: column.text(),
    body: column.text(),
  }
});

使用 astro db push --remote 推送到 Astro Studio。这将添加新表并将旧表标记为已弃用。
更新你的本地项目代码以使用新表而不是旧表。你可能还需要将数据迁移到新表。

当你确信旧表不再被你的项目使用时，可以从你的 config.ts 中移除该架构：

const Comment = defineTable({
  deprecated: true,
  columns: {
    author: column.text(),
    body: column.text(),
  }
});

const Feedback = defineTable({
  columns: {
    author: column.text(),
    body: column.text(),
  }
});

再次使用 astro db push --remote 命令推送到 Astro Studio。旧表将被删除，只留下新的、重命名的表。

推送数据

Studio 功能

你可能需要将数据推送到你的 Studio 数据库进行填充或数据迁移。你可以使用 astro:db 模块创建一个 .ts 文件来编写类型安全的查询。然后，使用命令 astro db execute <file-path> --remote 执行该文件对你的 Studio 数据库：

以下评论可以使用命令 astro db execute db/seed.ts --remote 进行填充：

import { Comment } from 'astro:db';

export default async function () {
  await db.insert(Comment).values([
    { authorId: 1, body: 'Hope you like Astro DB!' },
    { authorId: 2, body: 'Enjoy!' },
  ])
}

查看 CLI 参考获取完整的命令列表。

连接 Astro Studio

Studio 功能

默认情况下，当你运行 dev 或 build 命令时，Astro 将使用本地数据库文件。每次运行命令时，表都会从头开始重新创建，并插入开发的样例数据。

要连接到你的托管 Studio 数据库，你可以添加 --remote 参数。使用此参数进行生产部署，以便对你的 Studio 数据库拥有可读写权限。这将允许你接受并持久化用户数据。

# 使用远程连接进行构建
astro build --remote

# 使用远程连接进行开发
astro dev --remote

要使用远程连接，你需要一个应用令牌来进行 Studio 认证。请访问 Studio 控制面板获取令牌创建和设置指南。

当你准备好部署时，参见我们的使用 Studio 连接进行部署指南。

从 Astro Studio 迁移到 Turso

在 Studio 仪表板中，导航到你要迁移的项目。在设置选项卡中，使用 “Export Database（导出数据库）” 按钮下载数据库的转储。
按照官方说明安装 Turso CLI 并注册或登录你的 Turso 帐户。
使用 turso db create 命令在 Turso 上创建一个新数据库。
Terminal window
```
turso db create [database-name]
```
使用 Turso CLI 获取数据库 URL，并将其配置为环境变量 ASTRO_DB_REMOTE_URL。
Terminal window
```
turso db show [database-name]
```
```
ASTRO_DB_REMOTE_URL=[your-database-url]
```
创建一个令牌来访问你的数据库，并将其配置为环境变量 ASTRO_DB_APP_TOKEN。
Terminal window
```
turso db tokens create [database-name]
```
```
ASTRO_DB_APP_TOKEN=[your-app-token]
```
将你的 DB 架构和元数据推送到新的 Turso 数据库。
Terminal window
```
astro db push --remote
```
将步骤 1 中的数据库转储导入到新的 Turso DB 中。
Terminal window
```
turso db shell [database-name] < ./path/to/dump.sql
```
确认你的项目连接到新数据库后，你就可以安全地从 Astro Studio 中删除该项目了。

libSQL

添加于： @astrojs/db@0.14.0 新

Astro DB 可以从任何公开 libSQL 服务器远程协议的平台，连接到任何 libSQL 服务器，或者也可以自托管。

要将 Astro DB 连接到 libSQL 数据库，需要设置以下环境变量：

ASTRO_DB_REMOTE_URL: libSQL 服务器的连接 URL
ASTRO_DB_APP_TOKEN: libSQL 服务器的身份验证令牌

使用 libSQL 时和连接到 Astro Studio 托管数据库时，部署和推送更改到数据库的命令是相同的。不过，当使用 --remote 选项运行命令，如 astro build 和 astro db push 时，都需要在本地设置环境变量。

libSQL 连接的详细信息（例如加密密钥、备份、同步间隔）可以配置为远程连接 URL 中的查询参数。

例如，要让本地文件作为加密 libSQL 服务器的嵌入式副本，你可以设置以下环境变量：

ASTRO_DB_REMOTE_URL=file://local-copy.db?encryptionKey=your-encryption-key&syncInterval=60&syncUrl=libsql%3A%2F%2Fyour.server.io
ASTRO_DB_APP_TOKEN=token-to-your-remote-url

URL 方案和 host

libSQL 同时支持 HTTP 和 WebSockets 作为远程服务器的传输协议。它还支持使用本地文件或内存数据库。这些都可以在连接 URL 中使用以下 URL 方案来进行配置：

memory: 将使用内存数据库。在这种情况下，host 必须为空。
file: 将使用本地文件。host 是文件的路径（file:path/to/file.db）。
libsql: 将通过库首选的协议使用远程服务器（可能因版本而异）。host 是服务器的地址（libsql://your.server.io）。
http: 将通过 HTTP 使用远程服务器。https: 可用于启用安全连接。host 和 libsql 相同。
ws: 将通过 WebSockets 使用远程服务器。wss: 可用于启用安全连接。 host 和 libsql 相同。

`encryptionKey`

libSQL 对加密数据库具有原生支持。传递此搜索参数将使用给定密钥的加密：

ASTRO_DB_REMOTE_URL=file:path/to/file.db?encryptionKey=your-encryption-key

`syncUrl`

嵌入式副本是 libSQL 客户端的一项功能，可在本地文件或内存中实现数据库的完整同步副本，以实现超快读取。写入将发送到在 syncUrl 上定义的远程数据库并与本地副本同步。

使用此属性来传递单独的连接 URL，并将 DB 转换为另一个数据库的嵌入式副本。此属性只应与 file: 和 memory: 方案来一起使用。该参数必须经过 URL 编码。

例如，要在 libsql://your.server.io 上拥有数据库的内存嵌入式副本，你可以按如下方式设置连接 URL：

ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io

`syncInterval`

嵌入式副本同步之间的时间间隔（以秒为单位）。默认情况下，它仅在启动时和写入后同步。

此属性仅在同时设置了 syncUrl 时才生效。例如，要将内存中嵌入式副本设置为每分钟同步，请设置以下环境变量：

ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io&syncInterval=60

构建 Astro DB 集成

Astro 集成可以通过额外的 Astro DB 表和填充数据来扩展用户项目。

在 astro:db:setup 钩子中使用 extendDb() 方法注册额外的 Astro DB 配置和填充文件。 defineDbIntegration() 辅助函数为 astro:db:setup 钩子提供 TypeScript 支持和自动补全。

import { defineDbIntegration } from '@astrojs/db/utils';

export default function MyIntegration() {
  return defineDbIntegration({
    name: 'my-astro-db-powered-integration',
    hooks: {
      'astro:db:setup': ({ extendDb }) => {
        extendDb({
          configEntrypoint: '@astronaut/my-package/config',
          seedEntrypoint: '@astronaut/my-package/seed',
        });
      },
      // 其他集成钩子...
    },
  });
}

集成的配置和填充文件遵循与其用户定义的等效项相同的格式。

在集成中进行类型安全操作

在进行集成工作时，你可能无法从 astro:db 导出的 Astro 生成的表类型中获益。为了完全的类型安全，使用 asDrizzleTable() 辅助工具创建一个可以用于数据库操作的表引用对象。

例如，给定一个集成设置以下 Pets 数据库表：

import { defineDb, defineTable, column } from 'astro:db';

export const Pets = defineTable({
  columns: {
    name: column.text(),
    species: column.text(),
  },
});

export default defineDb({ tables: { Pets } });

填充文件可以导入 Pets 并使用 asDrizzleTable() 向你的表插入具有类型检查的行：

import { asDrizzleTable } from '@astrojs/db/utils';
import { db } from 'astro:db';
import { Pets } from './config';

export default async function() {
  const typeSafePets = asDrizzleTable('Pets', Pets);

  await db.insert(typeSafePets).values([
    { name: 'Palomita', species: 'cat' },
    { name: 'Pan', species: 'dog' },
  ]);
}

asDrizzleTable('Pets', Pets) 返回的值等同于 import { Pets } from 'astro:db'，但即使 Astro 的类型生成无法运行时也可用。你可以在任何需要查询或插入数据库的集成代码中使用它。

自托管生产部署

如果你将网站部署到自管理的主机上，例如虚拟私人服务器，你可以选择使用数据库文件，而不是连接到 Astro Studio 托管的数据库。

如果你能够接受这些风险，并且能够自己管理部署，你可以使用数据库文件，而不是连接到 Studio。

在构建过程中，设置 ASTRO_DATABASE_FILE 环境变量，将其指向宿主环境中你的 .db 文件的路径：

ASTRO_DATABASE_FILE=/srv/files/database.db astro build

构建过程会将此路径静态编译为你的生产数据库。当你部署并启动你的服务器时，它将连接到生产主机上此路径的文件。

此外，推送任何表架构更改（也称为“架构迁移”）必须使用此环境变量手动管理。

贡献

社区

Astro DB

安装

定义你的数据库

表

列

表引用

为你的数据库填充数据

查询你的数据库

Drizzle ORM

查询

插入

过滤

Drizzle 辅助工具

关系

批处理事务

Astro Studio

创建新的 Studio 项目

使用 Studio 连接进行部署

创建一个 Studio 应用令牌

设置 GitHub CI Action

推送表架构

推送破坏性架构更改

重命名表

推送数据

连接 Astro Studio

从 Astro Studio 迁移到 Turso

libSQL

URL 方案和 host

`encryptionKey`

`syncUrl`

`syncInterval`

构建 Astro DB 集成

在集成中进行类型安全操作

自托管生产部署

你有什么想法？

创建 GitHub Issue

发送反馈

发送反馈