Migration ของฐานข้อมูล

คู่มือนี้ครอบคลุมฐานข้อมูลของ CMS เอง: ประวัติ schema อยู่ที่ไหน วิธีเปลี่ยน schema และวิธี apply การเปลี่ยนแปลงกับฐานข้อมูล local, ฐานข้อมูลที่ deploy แล้ว และฐานข้อมูลรายไซต์ทั้งหมด รันทุกคำสั่ง จาก root ของ repository

อะไรอยู่ที่ไหน

Path	คืออะไร
backend/prisma/migrations/	SQL migration ของ Prisma หนึ่งไดเรกทอรีต่อหนึ่ง migration 20260908000000_init คือ baseline สำหรับการติดตั้งใหม่: schema ทั้งหมดและแถว seed เป็นแหล่งอ้างอิงหลัก ของประวัติ schema รวมถึง constraint ที่กำหนดเองและแถว seed ที่จำเป็น
backend/migrations-wrangler/	mirror สำหรับ D1 ของ migration เหล่านั้น (0001_init.sql สำหรับ baseline แล้วหนึ่งไฟล์ต่อ migration ถัดไปแต่ละรายการ) เป็นไฟล์ที่สร้างขึ้น — ห้ามแก้ด้วยมือ Wrangler apply ไฟล์เหล่านี้กับ D1
backend/prisma/prod.prisma, local.prisma, site.prisma, eav.prisma, tables.prisma	ชิ้นส่วน (fragment) ของ schema ให้แก้ไฟล์เหล่านี้
backend/prisma/schema.prisma	ประกอบจาก prod.prisma + site.prisma + eav.prisma + tables.prisma โดย scripts/build-prisma-schema.mjs ไฟล์นี้ถูก check in แต่เป็นผลลัพธ์: การแก้ไขโดยตรงจะถูกเขียนทับในการ build ครั้งถัดไป
backend/prisma/schema.local.prisma	การประกอบแบบเดียวกันบนฐาน local.prisma ใช้ตอนเขียน migration อยู่ใน gitignore
backend/tenant-migrations/	schema ที่ฐานข้อมูลรายไซต์ใหม่ใช้เริ่มต้น (0001_tenant_schema.sql) บวกกับ delta ใน deltas/ ที่พาฐานข้อมูลรายไซต์ที่มีอยู่ไปข้างหน้า ตอนนี้ยังไม่มี delta เกี่ยวข้องเฉพาะเมื่อคุณใช้ npm run provision:site

หลังรีลีสแรก Migration เพิ่มต่อท้ายได้อย่างเดียว ห้ามแก้หรือลบ migration ที่เผยแพร่แล้ว ให้แก้ด้วย migration ใหม่

ก่อนรีลีสแรก

Dee Wan ยังไม่ได้รีลีส จึงยังไม่มีการติดตั้งที่ต้องย้ายตาม ก่อนรีลีสแรก การเปลี่ยน schema จะแก้ baseline แทนการเพิ่ม migration ใหม่: fragment, 20260908000000_init, mirror 0001_init.sql และ baseline ของเว็บไซต์ 0001_tenant_schema.sql เปลี่ยนไปพร้อมกัน และ npm run migrate:check, npm run prisma:drift กับ npm run tenant:schema:check ต้องผ่าน

รีลีสแรกเริ่มจากฐานข้อมูลใหม่ทั้งหมด ไม่มี SQL สำหรับอัปเกรดฐานข้อมูลที่ build ก่อนหน้าสร้างไว้ และไม่มี delta ของเว็บไซต์ การแก้ baseline ทำให้ tenant schema เปลี่ยนโดยไม่มี delta ใหม่ ดังนั้น npm run tenant:schema จะปฏิเสธ ให้สร้างใหม่ด้วย npm run tenant:schema -- --allow-no-delta หลังรีลีสแรก การเปลี่ยน schema ทุกครั้งคือ migration ใหม่ ตามขั้นตอนด้านล่าง

ฐานข้อมูลในเครื่องที่สร้างจาก baseline เก่าจะไม่ได้รับการเปลี่ยนแปลงนี้ ให้สร้างใหม่: หยุดสภาพแวดล้อมในเครื่อง ลบ backend/.wrangler/state แล้วรัน npm run local:migrate และ npm run local:seed อีกครั้ง การทำเช่นนี้จะลบเว็บไซต์ รายการ และไฟล์ที่อัปโหลดในเครื่องทั้งหมด

เปลี่ยน schema

ก่อนรีลีสแรก ให้อัปเดต baseline ตามที่อธิบายไว้ด้านบน ขั้นตอนด้านล่างใช้หลังรีลีส

1. แก้ fragment ที่มี model นั้น (site.prisma, eav.prisma หรือ tables.prisma)

2. build schema.prisma และ Prisma client ใหม่:

   npm run prisma:generate

3. apply ทุกอย่างที่มีอยู่แล้วกับฐานข้อมูล local ของคุณ แล้วเขียน migration ใหม่:

   npm run local:migrate
   npm run local:migrate -- initial --create-migration

   การเขียน migration ปิดอยู่จนกว่าคุณจะส่ง --create-migration ดังนั้นการ apply ปกติจะไม่เขียน migration จาก schema ที่ drift ไปแล้ว เมื่อส่ง flag นี้ และเฉพาะเมื่อไม่มีอะไรเหลือให้ apply บน local คำสั่งจะรัน prisma migrate dev --create-only ซึ่งเขียนไดเรกทอรีใหม่ใต้ backend/prisma/migrations/ แล้ว apply migration นั้นกับฐานข้อมูล local คำสั่งใช้ config local ที่ถูก track ไว้ (backend/wrangler.dev.jsonc) จึงใช้ได้บน clone ที่ไม่เคย ติดตั้ง

   ให้คงคำว่า initial ไว้ในคำสั่งนั้น ปัจจุบัน --create-migration ที่ส่งมาเดี่ยว ๆ จะถูกปฏิเสธ พร้อมข้อความวิธีใช้

4. อ่าน SQL ที่สร้างขึ้นก่อน commit migration ที่เขียนจาก schema ซึ่ง drift ไปจากฐานข้อมูล อาจมีคำสั่ง DROP TABLE ที่ไม่มีใครตั้งใจ

5. สร้าง mirror สำหรับ D1 ใหม่และตรวจผล:

   npm run migrate:sync          # writes backend/migrations-wrangler/ from the Prisma migrations
   npm run migrate:check         # fails if the mirror and the migrations disagree
   npm run prisma:drift          # fails if schema.prisma no longer describes what the migrations build

6. หากคุณใช้ฐานข้อมูลรายไซต์ ให้สร้าง schema ของมันใหม่ด้วย:

   npm run tenant:schema         # rewrites the per-site bootstrap schema
   npm run tenant:schema:check   # fails until every new table has a placement

   migration ที่เพิ่มตารางจะไม่ผ่าน tenant:schema:check จนกว่าตารางนั้นจะถูกจัดวาง (placement) ใน backend/src/lib/tenancy/placement.ts

   migration ที่เปลี่ยนสิ่งที่ฐานข้อมูลรายไซต์ที่มีอยู่เก็บไว้ต้องมี delta ด้วย เขียน SQL ที่พาฐานข้อมูลแบบนั้นไปข้างหน้า เป็น backend/tenant-migrations/deltas/NNNN_<name>.sql ด้วยหมายเลขถัดไป ก่อนรัน npm run tenant:schema สำหรับคอลัมน์หรือ index ที่เพิ่ม นี่คือ SQL ของ migration เอง npm run tenant:schema ปฏิเสธ tenant schema ที่เปลี่ยนไปโดยไม่มี delta ใหม่ และบอกชื่อไฟล์ที่ต้องเขียน ใช้ --allow-no-delta เฉพาะเมื่อการเปลี่ยนนั้นไม่ต้องมี delta

7. commit Prisma migration, ไฟล์ mirror ของมัน, delta ใด ๆ และการเปลี่ยน tenant schema ใด ๆ ไปพร้อมกัน

Apply migration

ที่ไหน	คำสั่ง	หมายเหตุ
local rig (ไม่มีบัญชี Cloudflare)	npm run local:migrate	ใช้ backend/wrangler.dev.jsonc ซึ่งทุก clone มี ไม่ต้องใช้ credential
mirror local ของการตั้งค่าที่ติดตั้งแล้ว	npm run migrate:d1:local	อ่าน backend/wrangler.jsonc ซึ่ง setup เขียนและ git ละเว้น จึงล้มเหลวบน clone ที่ยังไม่ได้ติดตั้ง ใช้คู่กับ npm run dev:install --workspace backend
ฐานข้อมูลควบคุมที่ deploy แล้ว	npm run migrate:d1	ต้องมี CLOUDFLARE_API_TOKEN พิมพ์ config และฐานข้อมูลที่กำลังจะ migrate ก่อนรัน เพิ่ม -- --config <file> สำหรับการติดตั้งที่ไม่ใช่ backend/wrangler.jsonc
ฐานข้อมูลรายไซต์ที่มีอยู่	npm run tenant:upgrade	เฉพาะเมื่อคุณเคยรัน npm run provision:site -- --plan แสดงว่าแต่ละไซต์ขาดอะไรโดยไม่เขียน

การติดตั้งใหม่ไม่ต้องใช้คำสั่งเหล่านี้เลย: npm run setup apply schema เอง

npm run deploy ปฏิเสธการ deploy admin Worker ขณะที่ฐานข้อมูลควบคุมมี migration ค้างอยู่ หรือเมื่อมันบอกไม่ได้ ให้ apply ก่อน --skip-migration-check ข้ามการตรวจนี้ ใช้เฉพาะเมื่อคุณรู้ว่าโค้ดใหม่ไม่ขึ้นกับ migration ที่ค้างอยู่

เมื่อ migration ล้มเหลว

• migration ถูก apply ตามลำดับ และแต่ละตัวถูกบันทึกว่า apply แล้วหลังจากสำเร็จเท่านั้น ความล้มเหลวจะหยุดการรันและบอกว่า migration นั้นไม่ได้ถูกบันทึก migration ที่ตามมาจะไม่ถูก apply แก้สาเหตุแล้วรันคำสั่งเดิมอีกครั้ง: มันจะลอง migration ที่ล้มเหลวใหม่
• หาก migration หยุดกลางทาง การลองใหม่จะรันทีละ statement และข้ามเฉพาะ statement ที่ตาราง, index, trigger หรือคอลัมน์ของมันมีอยู่แล้ว จึงทำให้จบได้ migration ที่มีบล็อก BEGIN … END ที่ไม่ใช่ trigger แยกแบบนั้นไม่ได้ การรันจะปฏิเสธและระบุชื่อมัน และคุณต้องแก้ schema ด้วยมือ ก่อนรันอีกครั้ง
• อย่าแก้ migration ที่ล้มเหลวด้วยการแก้ migration ที่ถูก apply ที่ใดที่หนึ่งไปแล้ว ให้เพิ่ม migration ใหม่ที่แก้ไขมัน รัน migrate:sync แล้ว apply อีกครั้ง
• ก่อน apply migration ที่มีความเสี่ยงกับฐานข้อมูลที่ deploy แล้ว ให้ export ไว้ก่อน: npx wrangler d1 export <database-name> --remote --output backup.sql จาก backend/ Cloudflare D1 ยังเก็บประวัติแบบ point-in-time ของตัวเอง (Time Travel) ซึ่งกู้ฐานข้อมูลกลับไปยัง ช่วงเวลาก่อน migration ได้
• หาก npm run deploy ปฏิเสธเพราะมี migration ค้างอยู่ ให้ apply ด้วย npm run migrate:d1 แทนการข้ามการตรวจ

---

ยังไม่เปิดตัว (pre-MVP) และยังไม่มีเวอร์ชันเสถียร
คอมมิตซอร์สโค้ด: e207e63239a627fbd2ae9c414ef7c6eb19fcfe5a (มีการแก้ไขที่ยังไม่คอมมิต)
วันที่สร้างเอกสาร (UTC): 2026-10-21T09:28:24.214Z
คอมมิตสำหรับอัปเกรด: ระบุไม่ได้: มีการแก้ไขที่ยังไม่คอมมิต. บันทึกการเปลี่ยนแปลง