diff --git a/apps/wiki/db/003_note_descriptions.sql b/apps/wiki/db/003_note_descriptions.sql
index dcc4036..fd3d4ba 100644
--- a/apps/wiki/db/003_note_descriptions.sql
+++ b/apps/wiki/db/003_note_descriptions.sql
@@ -1,6 +1,9 @@
+BEGIN;
 ALTER TABLE posts ADD COLUMN IF NOT EXISTS description text NOT NULL DEFAULT '';
 UPDATE posts p SET description=left(COALESCE((
  SELECT a.body FROM post_assets pa JOIN assets a ON a.id=pa.asset_id
  WHERE pa.post_id=p.id AND a.kind='text' AND a.body IS NOT NULL
  ORDER BY pa.position LIMIT 1
 ),p.title),200) WHERE p.description='';
+INSERT INTO schema_migrations(version) VALUES('003_note_descriptions') ON CONFLICT DO NOTHING;
+COMMIT;
diff --git a/docs/note-preview-stage.md b/docs/note-preview-stage.md
index c1249ca..1109dd0 100644
--- a/docs/note-preview-stage.md
+++ b/docs/note-preview-stage.md
@@ -11,7 +11,7 @@
 - `apps/wiki/src/lib/explore.ts`：统一 description 和 imageCount；保留所有去重后的图片；图文按真实截图数量统计，纯文本返回 description。
 - `apps/wiki/src/lib/library.ts`：读取笔记实际截图数量，避免把共用封面误计为图文页数。
 - `apps/wiki/src/lib/model.ts`：补充 description 和截图计数字段类型。
-- `apps/wiki/db/003_note_descriptions.sql`：独立存储 description，为现有记录从说明文字回填摘要，原正文保留。
+- `apps/wiki/db/003_note_descriptions.sql`：独立存储 description，为现有记录从说明文字回填摘要，原正文保留，迁移在事务内执行并记录版本。
 - `apps/wiki/src/lib/write.ts`：创建笔记 API 支持保存独立 description，标签机制保持可用。
 - `apps/wiki/src/pages/api/upload.ts`：上传的说明同步保存为笔记 description，完整文字保留。
 - `apps/wiki/src/lib/publish-learning-series.ts`：发布图文时使用各自副标题作为 description。