@astrojs/ db

Astro DB 是专为 Astro 生态系统设计的完全托管 SQL 数据库：在 Astro 中本地开发并部署到任何 libSQL 兼容数据库。

¥Astro DB is a fully-managed SQL database designed for the Astro ecosystem: develop locally in Astro and deploy to any libSQL-compatible database.

使用 Astro DB，你将拥有一个功能强大、本地、类型安全的工具来查询和建模内容作为关系数据库。

¥With Astro DB you have a powerful, local, type-safe tool to query and model content as a relational database.

See the Astro DB guide for full usage and examples.

安装

¥Installation

Astro 包含一个 astro add 命令来自动设置官方集成。如果你愿意，你可以改用安装集成手动。

¥Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

在新的终端窗口中运行以下命令之一。

¥Run one of the following commands in a new terminal window.

npx astro add db

pnpm astro add db

yarn astro add db

手动安装

¥Manual Installation

如果你希望自己从头开始设置，请跳过 astro add 并按照这些说明自行安装 Astro DB。

¥If you prefer to set things up from scratch yourself, skip astro add and follow these instructions to install Astro DB yourself.

1. 通过包管理器从 npm 安装集成

¥ Install the integration from npm via a package manager

npm install @astrojs/db

pnpm add @astrojs/db

yarn add @astrojs/db

2. 将集成添加到 `astro.config.mjs`

¥ Add the integration to astro.config.mjs

import { defineConfig } from 'astro/config';
import db from '@astrojs/db';

export default defineConfig({
  integrations: [
   db()
  ]
});

3. 配置你的数据库

¥ Configure your database

在项目的根目录中创建一个 db/config.ts 文件。这是一个特殊文件，Astro 将自动加载并使用它配置你的数据库表。

¥Create a db/config.ts file at the root of your project. This is a special file that Astro will automatically load and use to configure your database tables.

import { defineDb } from 'astro:db';

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

表格配置参考

¥Table configuration reference

`columns`

使用 columns 对象配置表列：

¥Table columns are configured using the columns object:

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

const Comment = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    author: column.text(),
    content: column.text({ optional: true }),
    published: column.date({ default: NOW }),
  },
});

使用 column 实用程序配置列。column 支持以下类型：

¥Columns are configured using the column utility. column supports the following types:

column.text(...) - 存储纯文本或富文本内容
column.number(...) - 存储整数和浮点值
column.boolean(...) - 存储真/假值
column.date(...) - 存储 Date 对象，解析为 ISO 字符串以进行数据存储
column.json(...) - 存储任意 JSON blob，解析为字符串化的 JSON 以进行数据存储

所有列中都有一些共享的配置值：

¥There are a few shared configuration values across all columns:

primaryKey - 将 number 或 text 列设置为唯一标识符。
optional - Astro DB 默认对所有列使用 NOT NULL。将 optional 设置为 true 以允许空值。
default - 设置新插入条目的默认值。这接受静态值或 sql 字符串作为生成的值（如时间戳）。
unique - 将列标记为唯一。这可以防止表中的条目出现重复值。
references - 按列引用相关表。这将建立外键约束，这意味着每个列值在引用表中都必须具有匹配的值。

`indexes`

表索引用于提高给定列或列组合的查找速度。indexes 属性接受指定要索引的列的配置对象数组：

¥Table indexes are used to improve lookup speeds on a given column or combination of columns. The indexes property accepts an array of configuration objects specifying the columns to index:

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

const Comment = defineTable({
  columns: {
    authorId: column.number(),
    published: column.date(),
    body: column.text(),
  },
  indexes: [
    { on: ["authorId", "published"], unique: true },
  ]
});

这将在 authorId 和 published 列上生成一个名为 Comment_authorId_published_idx 的唯一索引。

¥This will generate a unique index on the authorId and published columns with the name Comment_authorId_published_idx.

每个索引都有以下配置选项：

¥The following configuration options are available for each index:

on：string | string[] - 要索引的单个列或列名数组。
unique：boolean - 设置为 true 以在索引列中强制使用唯一值。
name：string（可选） - 唯一索引的自定义名称。这将根据被索引的表和列名称覆盖 Astro 生成的名称（例如 Comment_authorId_published_idx）。自定义名称是全局的，因此请确保索引名称在表之间不冲突。

`foreignKeys`

外键用于建立两个表之间的关系。foreignKeys 属性接受可能在表之间关联一个或多个列的配置对象数组：

¥Foreign keys are used to establish a relationship between two tables. The foreignKeys property accepts an array of configuration objects that may relate one or more columns between tables:

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

const Author = defineTable({
  columns: {
    firstName: column.text(),
    lastName: column.text(),
  },
});

const Comment = defineTable({
  columns: {
    authorFirstName: column.text(),
    authorLastName: column.text(),
    body: column.text(),
  },
  foreignKeys: [
    {
      columns: ["authorFirstName", "authorLastName"],
      references: () => [Author.columns.firstName, Author.columns.lastName],
    },
  ],
});

每个外键配置对象都接受以下属性：

¥Each foreign key configuration object accepts the following properties:

columns：string[] - 与引用表相关的列名数组。
references：() => Column[] - 返回引用表中的列数组的函数。

Astro DB CLI 参考

¥Astro DB CLI reference

Astro DB 包含一组 CLI 命令，用于与你的本地和 libSQL 兼容数据库交互。

¥Astro DB includes a set of CLI commands to interact with your local and libSQL-compatible database.

使用 GitHub CI 操作时会自动调用这些命令，也可以使用 astro db CLI 手动调用。

¥These commands are called automatically when using a GitHub CI action, and can be called manually using the astro db CLI.

`astro db push`

标志:

¥Flags:

--force-reset 如果需要重大架构更改，请重置所有生产数据。

安全地将数据库配置更改推送到你的项目数据库。这将检查是否存在数据丢失风险，并指导你完成任何推荐的迁移步骤。如果必须进行重大架构更改，请使用 --force-reset 标志重置所有生产数据。

¥Safely push database configuration changes to your project database. This will check for any risk of data loss and guide you on any recommended migration steps. If a breaking schema change must be made, use the --force-reset flag to reset all production data.

`astro db verify`

检查本地和远程数据库配置之间是否存在任何差异。这由 astro db push 自动运行。verify 将比较你的本地 db/config.ts 文件与远程数据库，并在检测到更改时发出警告。

¥Check for any differences between your local and remote database configurations. This is automatically run by astro db push. verify will compare your local db/config.ts file with the remote database and warn if changes are detected.

`astro db execute <file-path>`

标志:

¥Flags:

--remote 针对你的 libSQL 兼容数据库运行。省略针对你的开发服务器运行。

执行 .ts 或 .js 文件以读取或写入数据库。这接受文件路径作为参数，并支持使用 astro:db 模块编写类型安全查询。使用 --remote 标志针对你的 libSQL 兼容数据库运行，或省略该标志针对你的开发服务器运行。请参阅如何使用种子开发数据获取示例文件。

¥Execute a .ts or .js file to read or write to your database. This accepts a file path as an argument, and supports usage of the astro:db module to write type-safe queries. Use the --remote flag to run against your libSQL-compatible database, or omit the flag to run against your development server. See how to seed development data for an example file.

`astro db shell --query <sql-string>`

标志:

¥Flags:

--query 要执行的原始 SQL 查询。
--remote 针对你的 libSQL 兼容数据库运行。省略针对你的开发服务器运行。

对数据库执行原始 SQL 查询。使用 --remote 标志针对你的 libSQL 兼容数据库运行，或省略该标志针对你的开发服务器运行。

¥Execute a raw SQL query against your database. Use the --remote flag to run against your libSQL-compatible database, or omit the flag to run against your development server.

Astro DB 实用程序参考

¥Astro DB utility reference

`isDbError()`

isDbError() 函数检查错误是否为 libSQL 数据库异常。这可能包括使用引用时的外键约束错误，或插入数据时缺少字段。你可以将 isDbError() 与 try / catch 块结合使用，以处理应用中的数据库错误：

¥The isDbError() function checks if an error is a libSQL database exception. This may include a foreign key constraint error when using references, or missing fields when inserting data. You can combine isDbError() with a try / catch block to handle database errors in your application:

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

export const POST: APIRoute = (ctx) => {
  try {
    await db.insert(Comment).values({
      id: ctx.params.id,
      content: 'Hello, world!'
    });
  } catch (e) {
    if (isDbError(e)) {
      return new Response(`Cannot insert comment with id ${id}\n\n${e.message}`, { status: 400 });
    }
    return new Response('An unexpected error occurred', { status: 500 });
  }

  return new Response(null, { status: 201 });
};

@astrojs/ db

安装

手动安装

1. 通过包管理器从 npm 安装集成

2. 将集成添加到 `astro.config.mjs`

3. 配置你的数据库

表格配置参考

`columns`

`indexes`

`foreignKeys`

Astro DB CLI 参考

`astro db push`

`astro db verify`

`astro db execute <file-path>`

`astro db shell --query <sql-string>`

Astro DB 实用程序参考

`isDbError()`

更多集成

前端框架

@astrojs/alpinejs

@astrojs/preact

@astrojs/react

@astrojs/solid⁠-⁠js

@astrojs/svelte

@astrojs/vue

SSR 适配器

@astrojs/cloudflare

@astrojs/netlify

@astrojs/node

@astrojs/vercel

其他集成

@astrojs/db

@astrojs/markdoc

@astrojs/mdx

@astrojs/partytown

@astrojs/sitemap

@astrojs/tailwind

@astrojs/ db

安装

手动安装

1. 通过包管理器从 npm 安装集成

2. 将集成添加到 astro.config.mjs

3. 配置你的数据库

表格配置参考

columns

indexes

foreignKeys

Astro DB CLI 参考

astro db push

astro db verify

astro db execute <file-path>

astro db shell --query <sql-string>

Astro DB 实用程序参考

isDbError()

更多集成

前端框架

SSR 适配器

其他集成

2. 将集成添加到 `astro.config.mjs`

`columns`

`indexes`

`foreignKeys`

`astro db push`

`astro db verify`

`astro db execute <file-path>`

`astro db shell --query <sql-string>`

`isDbError()`