From cb18683fb84953d760af1ffb41d43a81853e9ee5 Mon Sep 17 00:00:00 2001 From: wyf9 Date: Wed, 5 Aug 2026 17:39:14 +0800 Subject: [PATCH] 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 | 4 +--- README.md | 4 +--- README.zh.md | 4 +--- docs/guide/deployment.md | 44 +++++++++++++++++++++++++++++++++++-- docs/zh/guide/deployment.md | 44 +++++++++++++++++++++++++++++++++++-- package.json | 2 ++ 6 files changed, 89 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c432228..8673d68 100644 --- a/AGENTS.md +++ b/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 ``` diff --git a/README.md b/README.md index 8b302bf..a0e93cf 100644 --- a/README.md +++ b/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 diff --git a/README.zh.md b/README.zh.md index 9df67f3..128625a 100644 --- a/README.zh.md +++ b/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 diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index 311065b..c22d22d 100644 --- a/docs/guide/deployment.md +++ b/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..workers.dev`. -### 4. Configure GitHub Webhook +### 5. Configure GitHub Webhook 1. Go to your GitHub App settings 2. Set **Webhook URL** to `https://webhooker..workers.dev/webhook` diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index d9a097c..1906315 100644 --- a/docs/zh/guide/deployment.md +++ b/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..workers.dev` 访问。 -### 4. 配置 GitHub Webhook +### 5. 配置 GitHub Webhook 1. 进入 GitHub App 设置页面 2. 设置 **Webhook URL** 为 `https://webhooker..workers.dev/webhook` diff --git a/package.json b/package.json index 37f43fe..5333c09 100644 --- a/package.json +++ b/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",