chore: add db:migrate scripts and document the D1 migration step

- Add npm scripts db:migrate (local) and db:migrate:prod (remote) for
  wrangler d1 migrations apply webhooker
- Document the D1 database creation + migration step in the deployment
  guides (README en/zh, docs en/zh) and AGENTS.md
- Note the d1 execute fallback for databases already migrated manually

AGENTS.md

@@ -145,9 +145,7 @@ npx wrangler kv namespace create KV
 # Update wrangler.jsonc with KV ID
 npx wrangler d1 create webhooker
 # Update wrangler.jsonc d1_databases with the database ID
-npx wrangler d1 execute webhooker --remote --file ./migrations/0001_init.sql
-npx wrangler d1 execute webhooker --remote --file ./migrations/0002_log_detail.sql
-npx wrangler d1 execute webhooker --remote --file ./migrations/0003_telegram_links.sql
+npm run db:migrate:prod   # wrangler d1 migrations apply webhooker --remote (migrations/0001..0003)
 npx wrangler deploy
 ```
 

README.md

@@ -279,9 +279,7 @@ npx wrangler kv namespace create KV
 # Create D1 database and run migrations
 npx wrangler d1 create webhooker
 # Update wrangler.jsonc d1_databases with the database ID
-npx wrangler d1 execute webhooker --remote --file ./migrations/0001_init.sql
-npx wrangler d1 execute webhooker --remote --file ./migrations/0002_log_detail.sql
-npx wrangler d1 execute webhooker --remote --file ./migrations/0003_telegram_links.sql
+npm run db:migrate:prod   # apply migrations to the remote D1 database
 
 # Deploy
 npx wrangler deploy

README.zh.md

@@ -278,9 +278,7 @@ npx wrangler kv namespace create KV
 # 创建 D1 数据库并执行迁移
 npx wrangler d1 create webhooker
 # 更新 wrangler.jsonc d1_databases 中的数据库 ID
-npx wrangler d1 execute webhooker --remote --file ./migrations/0001_init.sql
-npx wrangler d1 execute webhooker --remote --file ./migrations/0002_log_detail.sql
-npx wrangler d1 execute webhooker --remote --file ./migrations/0003_telegram_links.sql
+npm run db:migrate:prod   # 将迁移应用到远端 D1 数据库
 
 # 部署
 npx wrangler deploy

docs/guide/deployment.md

@@ -45,7 +45,47 @@ set them (no PKCS#8 conversion required).
 
 Discord interactions arrive via the HTTPS Interactions Endpoint, so set `DISCORD_PUBLIC_KEY` and point the **Interactions Endpoint URL** at `https://your-domain/discord/interactions`. See [Interactions Endpoint](#interactions-endpoint) below.
 
-### 3. Deploy
+### 3. Create D1 Database and Run Migrations
+
+```bash
+npx wrangler d1 create webhooker
+```
+
+Copy the returned database ID into `wrangler.jsonc`:
+
+```jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "webhooker",
+      "database_id": "your-database-id",
+    },
+  ],
+}
+```
+
+Then apply the migrations:
+
+```bash
+npm run db:migrate:prod   # apply migrations to the remote D1 database
+npm run db:migrate        # apply migrations to the local (Miniflare) database
+```
+
+The `db:migrate` scripts run `wrangler d1 migrations apply webhooker` (see `package.json`), which applies each SQL file in `migrations/` and records applied versions in the `d1_migrations` table.
+
+::: tip Databases previously migrated with `d1 execute`
+If the database already has these tables/columns (e.g. previously migrated with `wrangler d1 execute --file`), the `d1_migrations` tracking table may be missing and `db:migrate:prod` will try to re-run every migration. The `ALTER TABLE ... ADD COLUMN` statements in `0002_log_detail.sql` then fail because the columns already exist. In that case run the files directly instead:
+
+```bash
+npx wrangler d1 execute webhooker --remote --file ./migrations/0001_init.sql
+npx wrangler d1 execute webhooker --remote --file ./migrations/0002_log_detail.sql
+npx wrangler d1 execute webhooker --remote --file ./migrations/0003_telegram_links.sql
+```
+
+:::
+
+### 4. Deploy
 
 ```bash
 npx wrangler deploy
@@ -53,7 +93,7 @@ npx wrangler deploy
 
 Your worker is now live at `https://webhooker.<your-subdomain>.workers.dev`.
 
-### 4. Configure GitHub Webhook
+### 5. Configure GitHub Webhook
 
 1. Go to your GitHub App settings
 2. Set **Webhook URL** to `https://webhooker.<your-subdomain>.workers.dev/webhook`

docs/zh/guide/deployment.md

@@ -44,7 +44,47 @@ npx wrangler secret put ADMIN_USER_IDS       # 逗号分隔的 GitHub ID/登录
 
 Discord 交互通过 HTTPS Interactions Endpoint 送达，需要设置 `DISCORD_PUBLIC_KEY` 并把 **Interactions Endpoint URL** 指向 `https://your-domain/discord/interactions`。参见下方 [Interactions Endpoint](#interactions-endpoint)。
 
-### 3. 部署
+### 3. 创建 D1 数据库并执行迁移
+
+```bash
+npx wrangler d1 create webhooker
+```
+
+将返回的数据库 ID 填入 `wrangler.jsonc`：
+
+```jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "webhooker",
+      "database_id": "your-database-id",
+    },
+  ],
+}
+```
+
+然后执行迁移：
+
+```bash
+npm run db:migrate:prod   # 将迁移应用到远端 D1 数据库
+npm run db:migrate        # 将迁移应用到本地（Miniflare）数据库
+```
+
+`db:migrate` 脚本执行 `wrangler d1 migrations apply webhooker`（见 `package.json`），逐一应用 `migrations/` 下的 SQL 文件，并在 `d1_migrations` 表中记录已应用的版本。
+
+::: tip 曾用 `d1 execute` 迁移过的数据库
+如果数据库已有这些表/列（例如之前用 `wrangler d1 execute --file` 迁移过），可能缺少 `d1_migrations` 追踪表，`db:migrate:prod` 会尝试重新执行所有迁移；`0002_log_detail.sql` 中的 `ALTER TABLE ... ADD COLUMN` 语句会因列已存在而失败。此时请直接执行文件：
+
+```bash
+npx wrangler d1 execute webhooker --remote --file ./migrations/0001_init.sql
+npx wrangler d1 execute webhooker --remote --file ./migrations/0002_log_detail.sql
+npx wrangler d1 execute webhooker --remote --file ./migrations/0003_telegram_links.sql
+```
+
+:::
+
+### 4. 部署
 
 ```bash
 npx wrangler deploy
@@ -52,7 +92,7 @@ npx wrangler deploy
 
 Worker 现在可通过 `https://webhooker.<your-subdomain>.workers.dev` 访问。
 
-### 4. 配置 GitHub Webhook
+### 5. 配置 GitHub Webhook
 
 1. 进入 GitHub App 设置页面
 2. 设置 **Webhook URL** 为 `https://webhooker.<your-subdomain>.workers.dev/webhook`

package.json

@@ -5,6 +5,8 @@
   "scripts": {
     "dev": "wrangler dev",
     "deploy": "wrangler deploy",
+    "db:migrate": "wrangler d1 migrations apply webhooker --local",
+    "db:migrate:prod": "wrangler d1 migrations apply webhooker --remote",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "lint:md": "markdownlint '**/*.md' --ignore node_modules --ignore dist",