数据库选项

EmDash 支持多种数据库后端。根据你的部署目标进行选择。

概述

Cloudflare D1

D1 是 Cloudflare 的无服务器 SQLite 数据库。在部署到 Cloudflare Workers 时使用它。

import { d1 } from "@emdash-cms/cloudflare";

export default defineConfig({
	integrations: [
		emdash({
			database: d1({ binding: "DB" }),
		}),
	],
});

配置

设置

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "emdash-db",
      "database_id": "your-database-id"
    }
  ]
}

[[d1_databases]]
binding = "DB"
database_name = "emdash-db"
database_id = "your-database-id"

创建 D1 数据库

wrangler d1 create emdash-db

读取副本

D1 支持读取复制，为全球分布的站点降低读取延迟。启用后，读取查询会路由到附近的副本，而不是总是访问主数据库。

EmDash 使用 D1 Sessions API 透明地管理这一点。使用 session 选项启用它：

import { d1 } from "@emdash-cms/cloudflare";

export default defineConfig({
	integrations: [
		emdash({
			database: d1({
				binding: "DB",
				session: "auto",
			}),
		}),
	],
});

会话模式

工作原理

• 匿名访问者获得 first-unconstrained — 读取发送到最近的副本以获得最低延迟。由于匿名用户从不写入，他们不需要一致性保证。
• 已认证用户（编辑者、作者）获得基于书签的会话。写入后，书签 Cookie 确保下一个请求至少看到该状态。
• 写入请求（POST、PUT、DELETE）始终从主数据库开始。
• 构建时查询（Astro 内容集合）完全绕过会话并直接使用主数据库。

libSQL

libSQL 是 SQLite 的一个分支，支持远程连接。当你需要远程数据库而不使用 Cloudflare D1 时使用它。

import { libsql } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: libsql({
				url: process.env.LIBSQL_DATABASE_URL,
				authToken: process.env.LIBSQL_AUTH_TOKEN,
			}),
		}),
	],
});

配置

本地开发

在开发期间使用本地 libSQL 文件：

database: libsql({ url: "file:./data.db" });

PostgreSQL

Node.js 部署需要完整关系数据库时支持 PostgreSQL。

import { postgres } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: postgres({
				connectionString: process.env.DATABASE_URL,
			}),
		}),
	],
});

配置

你可以使用连接字符串或单独的参数进行连接：

// 连接字符串
database: postgres({
	connectionString: "postgres://user:password@localhost:5432/emdash",
});

// 单独的参数
database: postgres({
	host: "localhost",
	port: 5432,
	database: "emdash",
	user: "emdash",
	password: process.env.DB_PASSWORD,
	ssl: true,
});

连接池

适配器在底层使用 pg.Pool。根据你的部署调整池大小：

database: postgres({
	connectionString: process.env.DATABASE_URL,
	pool: { min: 2, max: 20 },
});

SQLite

使用 better-sqlite3 的 SQLite 是 Node.js 部署的最简单选项。

import { sqlite } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data.db" }),
		}),
	],
});

配置

文件路径

url 必须以 file: 开头：

// 相对路径
database: sqlite({ url: "file:./data/emdash.db" });

// 绝对路径
database: sqlite({ url: "file:/var/data/emdash.db" });

// 来自环境变量
database: sqlite({ url: `file:${process.env.DATABASE_PATH}` });

迁移

EmDash 自动处理 SQLite、libSQL 和 PostgreSQL 的迁移。对于 D1，通过 Wrangler 运行迁移。

检查迁移状态

npx emdash init --database ./data.db

此命令：

1. 如果需要，创建数据库文件
2. 运行任何挂起的迁移
3. 报告当前迁移状态

迁移文件

迁移与 EmDash 捆绑在一起。要手动运行它们：

# SQLite/libSQL - 迁移自动运行

# D1 - 通过 wrangler 运行
wrangler d1 migrations apply DB

基于环境的配置

为每个环境使用不同的数据库：

import { sqlite, libsql, postgres } from "emdash/db";
import { d1 } from "@emdash-cms/cloudflare";

const database = import.meta.env.PROD ? d1({ binding: "DB" }) : sqlite({ url: "file:./data.db" });

export default defineConfig({
	integrations: [emdash({ database })],
});

或根据环境变量切换：

const database = process.env.DATABASE_URL
	? postgres({ connectionString: process.env.DATABASE_URL })
	: sqlite({ url: "file:./data.db" });