Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

i18n(zh-cn): Update astro-db.mdx #7789

Merged
merged 4 commits into from
Apr 7, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 109 additions & 14 deletions src/content/docs/zh-cn/guides/astro-db.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import { FileTree } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';
import StudioHeading from '~/components/StudioHeading.astro';
import { Steps } from '@astrojs/starlight/components';

Astro DB 是一款专为 Astro 设计的全托管 SQL 数据库。你可以在本地开发或者连接到我们 [Astro Studio](/zh-cn/recipes/studio/) 平台上托管的数据库。

Expand Down Expand Up @@ -53,9 +54,9 @@ export default defineDb({

### 表

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

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

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

Expand Down Expand Up @@ -105,9 +106,9 @@ const Comment = defineTable({

### 表引用

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

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

- 在被引用的表上有一个**标识符列**。这通常是带有 `primaryKey` 属性的 `id` 列。
- 在基础表上有一个用于**存储被引用 `id`** 的列。这将使用 `references` 属性建立关系。
Expand All @@ -132,7 +133,7 @@ const Comment = defineTable({

## 为你的数据库填充数据

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

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

Expand Down Expand Up @@ -161,7 +162,7 @@ export default async function() {
import { db } from 'astro:db';
```

Astro DB 包含一个内置的 [Drizzle ORM](https://orm.drizzle.team/) 客户端。使用该客户端无需设置或手动配置。当你运行 Astro 时,Astro DB 的 `db` 客户端会自动配置以与你的数据库(本地或远程)进行通信。它使用你明确的数据库模式定义进行类型安全的 SQL 查询,当你引用不存在的列或表时,会出现 TypeScript 错误。
Astro DB 包含一个内置的 [Drizzle ORM](https://orm.drizzle.team/) 客户端。使用该客户端无需设置或手动配置。当你运行 Astro 时,Astro DB 的 `db` 客户端会自动配置以与你的数据库(本地或远程)进行通信。它使用你明确的数据库架构定义进行类型安全的 SQL 查询,当你引用不存在的列或表时,会出现 TypeScript 错误。

### 查询

Expand Down Expand Up @@ -342,35 +343,129 @@ Astro DB 可以[连接到 Astro Studio 平台](/zh-cn/recipes/studio/),快速
要创建一个新项目,你可以使用[现成的模板](https://studio.astro.build)或访问[Astro Studio 指南](/zh-cn/recipes/studio/#创建新的-studio-项目)。

<StudioHeading>
### 推送表模式
### 推送表架构
</StudioHeading>


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

在[从仪表板创建 Studio 项目](#astro-studio)时,你将有创建 GitHub CI 流水线的选项。这将在与你的仓库的主分支合并时自动迁移模式更改
在[从仪表板创建 Studio 项目](#astro-studio)时,你将有创建 GitHub CI 流水线的选项。这将在与你的仓库的主分支合并时自动迁移架构更改

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

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npm run astro db push
npm run astro db push --remote
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro db push
pnpm astro db push --remote
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro db push
yarn astro db push --remote
```
</Fragment>
</PackageManagerTabs>

这个命令将验证更改是否可以在无数据丢失的情况下进行,并指导如何推荐模式更改以解决冲突。如果必须进行破坏性的模式更改,添加 `--force-reset` 标志以重置所有生产数据。
此命令将验证你的本地更改是否可以在不丢失数据的情况下进行,并在必要时,建议如何安全地修改你的架构以解决冲突。

#### 推送破坏性架构更改

:::caution
__这将销毁你的数据库__。仅在你不需要你的生产数据时执行此命令。
:::

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

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

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npm run astro db push --remote --force-reset
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro db push --remote --force-reset
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro db push --remote --force-reset
```
</Fragment>
</PackageManagerTabs>

<StudioHeading>
### 重命名表
</StudioHeading>

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

如果你**没有任何重要的生产数据**,那么你可以使用 `--force-reset` 标志[重置你的数据库](#推送破坏性架构更改)。这个标志将会删除数据库中的所有表,并创建新的表,以便它完全匹配你当前的架构。

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

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

<Steps>

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

```ts title="db/config.ts" ins={2}
const Comment = defineTable({
deprecated: true,
columns: {
author: column.text(),
body: column.text(),
}
});
```

2. 添加一个新的表架构(完全匹配现有表的属性)并使用新名称:

```ts title="db/config.ts" ins={9-14}
const Comment = defineTable({
deprecated: true,
columns: {
author: column.text(),
body: column.text(),
}
});

const Feedback = defineTable({
columns: {
author: column.text(),
body: column.text(),
}
});
```
3. 使用 `astro db push --remote` [推送到 Astro Studio](#推送表架构)。这将添加新表并将旧表标记为已弃用。
4. 更新你的本地项目代码以使用新表而不是旧表。你可能还需要将数据迁移到新表。
5. 当你确信旧表不再被你的项目使用时,可以从你的 `config.ts` 中移除该架构:
```ts title="db/config.ts" del={1-7}
const Comment = defineTable({
deprecated: true,
columns: {
author: column.text(),
body: column.text(),
}
});

const Feedback = defineTable({
columns: {
author: column.text(),
body: column.text(),
}
});
```
6. 再次使用 `astro db push --remote` 命令推送到 Astro Studio。旧表将被删除,只留下新的、重命名的表。
</Steps>

<StudioHeading>
### 推送数据
Expand Down
Loading