สำหรับทีมที่ทดสอบ Prisma 8 มาตั้งแต่ตอนที่ยังใช้ชื่อ Prisma Next ในไฟล์ schema น่าจะยังมี // use prisma-next อยู่ที่บรรทัดแรก ส่วนใน .env บน CI ก็อาจมี PRISMA_NEXT_DEBUG=1 ที่เคยตั้งไว้ตอนตรวจหาข้อผิดพลาดค้างอยู่ ก่อนหน้านี้ทุกอย่างอาจจะรันผ่านเป็นสีเขียวมาตลอด จนกระทั่งวันที่ 12 กันยายน ทีมงาน Prisma ได้ปล่อย Prisma ORM v8.0.0-rc.10 ออกมา

แม้ rc.10 จะยังเป็น Release Candidate หรือรุ่นทดสอบก่อนปล่อยจริง ไม่ใช่เวอร์ชัน 8.0.0 ตัวสมบูรณ์ แต่จุดสำคัญใน Release Notes รอบนี้คือ ทีมงานระบุชัดเจนว่า การเปลี่ยนชื่อจาก Prisma Next เป็น Prisma 8 ในทุก identifier ที่โปรเจกต์มองเห็นนั้นเสร็จสิ้นแล้ว สรุปง่ายๆ คือ header เดิมในไฟล์ schema ยังคงใช้ต่อได้ แต่ Environment Variable ชื่อเดิมจะไม่ทำงานอีกต่อไป ยกเว้นตัวแปรปิด telemetry เพียงตัวเดียว

เวลาอัปเกรดเวอร์ชัน สิ่งที่ทำให้ระบบพังมักไม่ใช่ฟีเจอร์ใหญ่ แต่เป็นการเปลี่ยนชื่อที่กระทบการตั้งค่าเดิม ใน rc.10 นี้ สิ่งที่ต้องรู้แบ่งออกเป็น 4 เรื่องหลักๆ คือ อะไรที่ค่อยเปลี่ยนทีหลังได้, อะไรที่ต้องแก้ทันทีวันนี้, คำสั่งไหนที่ต้องรันหนึ่งครั้งหลังอัปเกรด และฟีเจอร์ใหม่ใน TypeScript ที่มาแทนการเขียน Type ด้วยมือ

Header และไฟล์ primer: ค่อยเปลี่ยนทีหลังได้

กลุ่มแรกคือส่วนที่เปลี่ยนชื่อแล้ว แต่ระบบยังรองรับชื่อเดิมอยู่ มี 2 อย่าง:

1. Header ในไฟล์ schema: ปัจจุบันบรรทัดระบุเวอร์ชันเปลี่ยนเป็น // use prisma-8 แล้ว ส่วน // use prisma-next เดิมแม้จะ deprecated แล้วแต่ยังใช้งานได้ตามปกติ เพราะคำสั่ง contract emit ไม่ได้นำบรรทัด header ไปประมวลผลอยู่แล้ว อีกทั้ง Language Server ใน Editor ก็ยังรู้จักชื่อเดิมอยู่ และจะช่วยเปลี่ยนเป็นชื่อใหม่ให้อัตโนมัติเวลาจัดรูปแบบไฟล์ ส่วนโปรเจกต์ที่สร้าง schema ใหม่ด้วยคำสั่ง orm init หรือ contract infer จะได้ header ใหม่มาตั้งแต่แรกเลย

2. ไฟล์ primer (prisma-8.md): ไฟล์สรุปภาพรวมโปรเจกต์ที่คำสั่ง orm init สร้างไว้ที่โฟลเดอร์หลักของโปรเจกต์ เปลี่ยนชื่อจาก prisma-next.md เป็น prisma-8.md ไฟล์เดิมไม่ได้ทำให้ระบบพัง แต่แนะนำให้เปลี่ยนชื่อไฟล์ตาม และแก้ไขลิงก์ใน README.md หรือไฟล์คำสั่งของ AI Agent ที่อ้างอิงถึงไฟล์นี้ เพื่อไม่ให้ลิงก์เสีย

Environment Variable ตระกูล PRISMA_NEXT_*: ต้องเปลี่ยนทันทีวันนี้

กลุ่มนี้คือส่วนที่ต้องรีบจัดการ เพราะ Environment Variable ของ CLI ที่เคยขึ้นต้นด้วย PRISMA_NEXT_ ตัดคำว่า NEXT_ ออกไปเกือบทุกตัว เช่น PRISMA_NEXT_DEBUG เปลี่ยนเป็น PRISMA_DEBUG และ PRISMA_NEXT_TELEMETRY_ENDPOINT เปลี่ยนเป็น PRISMA_TELEMETRY_ENDPOINT โดยตัว CLI จะไม่อ่านค่าจากชื่อเดิมอีกต่อไป ค่าคอนฟิกที่เคยตั้งไว้จึงไม่มีผล ถ้า CI/CD pipeline พึ่งพาตัวแปรเหล่านี้อยู่ ระบบก็อาจทำงานผิดพลาดได้

จุดที่ต้องระวังคือ มีข้อยกเว้นเพียงตัวเดียว คือตัวแปรปิด Telemetry อย่าง PRISMA_NEXT_DISABLE_TELEMETRY ที่ยังรองรับชื่อเดิมอยู่ นอกเหนือจากตัวนี้แล้วต้องไล่เปลี่ยนทั้งหมด โดยจุดที่มักมีตัวแปรเหล่านี้ซ่อนอยู่มี 3 ที่คือ Shell profile บนเครื่อง, ไฟล์ .env ในโปรเจกต์ และหน้าตั้งค่าบนระบบ CI ซึ่ง CI คือจุดที่หลุดได้ง่ายที่สุด เพราะไม่ได้รันอยู่บนเครื่องเราตลอดเวลา

นอกจากนี้ โฟลเดอร์เก็บการตั้งค่าของ CLI ย้ายจาก ~/.config/prisma-next/ ไปเป็น ~/.config/prisma-8/ ด้วย (บน Windows คือโฟลเดอร์ใต้ %APPDATA%) ส่งผลให้หลังอัปเกรด ตัว CLI จะแสดงข้อความแจ้งเตือนเรื่อง Telemetry อีกรอบเหมือนเพิ่งติดตั้งใหม่ ซึ่งทีมงาน Prisma ระบุไว้ชัดเจนว่าเป็นการทำงานที่ตั้งใจไว้ ไม่ใช่บั๊กแต่อย่างใด เราสามารถลบโฟลเดอร์เดิมทิ้งได้เลย แล้ว CLI จะสร้างโฟลเดอร์ prisma-8 ขึ้นมาใหม่และถามเรื่องนี้เพียงครั้งเดียว

รัน prisma contract emit หนึ่งครั้ง เพื่อบันทึกสถานะ nullable ของ Relation

การเปลี่ยนแปลงถัดมาอยู่ในไฟล์ contract.json ที่ CLI สร้างขึ้นจาก schema เพื่อให้ Prisma Client นำไปเชื่อมต่อฐานข้อมูล และให้เครื่องมือ Migration นำไปปรับโครงสร้างข้อมูลต่อได้ ใน rc.10 Relation แบบหนึ่งต่อหนึ่ง (1:1) และหลายต่อหนึ่ง (N:1) ทุกตัว จะมีค่า nullable เพิ่มเข้ามาใน contract อย่างชัดเจน โดยดูจากเครื่องหมาย ? ของฟิลด์ Relation นั้นใน schema ถ้ามี ? หมายถึงยอมให้มีค่าว่างได้ ถ้าไม่มีแปลว่าต้องมีค่าเสมอ

ตัวอย่างการเปลี่ยนแปลงใน contract.json:

{ "cardinality": "N:1", "on": { "...": "..." } }
{ "cardinality": "N:1", "nullable": false, "on": { "...": "..." } }

สิ่งที่สำคัญยิ่งกว่าตัว flag คือระบบตรวจสอบความถูกต้องที่เพิ่มเข้ามา: ถ้าฟิลด์ Relation กำหนดไว้ว่าห้ามว่าง (ไม่มี ?) แต่คอลัมน์ Foreign Key ในฐานข้อมูลจริงกลับยอมให้เป็นค่าว่างได้ (หรือในทางกลับกัน) คำสั่ง prisma contract emit จะแจ้งเตือนข้อผิดพลาดทันทีและไม่ออกไฟล์ contract ให้ จากเดิมที่ความไม่ตรงกันนี้อาจหลุดรอดไปได้ วิธีแก้คือปรับเครื่องหมาย ? ใน schema ให้ตรงกับโครงสร้างจริงของคอลัมน์ แล้วสั่ง emit ใหม่อีกครั้ง

สำหรับไฟล์ contract เดิมที่สร้างจาก rc.9 หรือเวอร์ชันก่อนหน้า ตัว Client ยังโหลดขึ้นมาทำงานได้ตามปกติโดยไม่พัง เพราะถ้าไม่มี flag นี้ ตัว Client จะดูจากคอลัมน์ Foreign Key ให้เอง ส่วนไฟล์ snapshot ของ contract เก่าที่ระบบ Migration เก็บไว้ จะไม่มีการเขียนทับและยังทำงานได้ตามเดิม

อย่างไรก็ตาม ขั้นตอนนี้ข้ามไม่ได้ เพราะถ้ายังไม่สั่ง emit ใหม่ ไฟล์ contract.d.ts ก็จะยังไม่มี Type ชุดใหม่ให้เรียกใช้งาน ดังนั้นหลังอัปเกรดแพ็กเกจแล้ว ให้รันคำสั่งนี้หนึ่งครั้ง:

prisma contract emit

หรือจะรันผ่าน script contract:emit ของโปรเจกต์ก็ได้ แล้ว commit ไฟล์ที่สร้างขึ้นมาใหม่ และถ้าโปรเจกต์ใช้ Supabase extension อยู่ด้วย ไฟล์ที่ emit ออกมาใหม่จะอัปเดตเวอร์ชันของ extension ใน metadata จาก 8.0.0-rc.9 เป็น 8.0.0-rc.10 ทั้งใน contract.json และ contract.d.ts ซึ่งเป็นการเปลี่ยนแปลงตามปกติ โดยทีมงานย้ำชัดเจนว่า ห้ามแก้ไขไฟล์ที่ระบบสร้างขึ้นอัตโนมัติเหล่านี้ด้วยมือ

Models และ Scalars: เข้ามาแทนที่ Prisma.User และ UserGetPayload

นี่คือฟีเจอร์ที่คนเขียน TypeScript น่าจะถูกใจที่สุดในรอบนี้ เพราะหลัง emit ใหม่ ไฟล์ contract.d.ts จะส่งออก namespace ชื่อ Models และค่าคงที่ชื่อ models ออกมาให้ โดยมีสมาชิกแยกตามแต่ละโมเดล เช่น Models.public_User หรือ typeof models.public.User (ชื่อจะขึ้นต้นด้วย Schema ของฐานข้อมูล ยกเว้น SQLite ที่ไม่มี Schema จะใช้ชื่อโมเดลตรงๆ)

จากนั้นเราสามารถต่อยอดเป็น Type ได้ 3 รูปแบบหลัก ซึ่งใช้แทน Prisma.User และ UserGetPayload<...> ใน Prisma 7:

• Scalars<M>: ใช้ระบุ Type ของข้อมูลแต่ละแถวที่ได้จากการ query โมเดลนั้นแบบปกติ
• Shape<M, Spec>: ใช้กำหนดโครงสร้าง Type ตามต้องการ เช่น เลือกเฉพาะบางฟิลด์ ตัดบางฟิลด์ออก หรือดึง Relation ที่เกี่ยวข้องเข้ามาด้วย
• ResultType: ใช้หา Type ของผลลัพธ์จาก ORM query โดยตรง ซึ่งใน rc.10 ใช้กับ ORM query ได้แล้ว (ก่อนหน้านี้คืนค่าเป็น never)

ตัวอย่างโค้ดจาก Release Notes:

import type { Models } from './prisma/contract';
import type { Scalars, Shape } from '@prisma/orm-postgres/family-contract/types';
import type { ResultType } from '@prisma/orm-postgres/components/runtime';

type UserRow = Scalars<Models.public_User>;
type UserResponse = Shape<Models.public_User, { '-': 'passwordHash'; posts: { '+': 'id' | 'title' } }>;
const usersWithPosts = db.orm.public.User.include('posts');
type UserWithPosts = ResultType<typeof usersWithPosts>;

ข้อควรสังเกตคือ Path ในการ import:

• Models นำเข้ามาจาก ./prisma/contract ในโปรเจกต์ของคุณเอง
• Scalars และ Shape นำเข้ามาจาก package contract ของฐานข้อมูลที่ใช้ เช่น @prisma/orm-postgres/family-contract/types (ถ้าใช้ MongoDB จะเป็น @prisma/orm-mongo/...)
• ResultType นำเข้ามาจาก @prisma/orm-postgres/components/runtime

การทำงานของโค้ดตัวอย่าง:

• UserRow ได้ Type ของข้อมูลผู้ใช้ตามฟิลด์มาตรฐานทั้งหมด
• UserResponse กำหนดโครงสร้างข้อมูลเอง โดยใช้ '-' เพื่อตัดฟิลด์ passwordHash ออก และใช้ '+' ดึง relation posts ติดมาด้วยเฉพาะฟิลด์ id กับ title
• สองบรรทัดสุดท้าย เราสร้าง query ด้วย .include('posts') แล้วใช้ ResultType หา Type ของผลลัพธ์จากตัวแปร query โดยอัตโนมัติ

ประโยชน์สำคัญคือ ช่วยให้เราไม่ต้องเขียน Type ของโมเดลเองด้วยมืออีกต่อไป เพราะการก๊อปปี้ฟิลด์มาเขียน Type เองมักเป็นปัญหาที่ตรวจจับยาก เวลาเพิ่มคอลัมน์ใหม่ใน schema โค้ดจะไม่ขึ้นตัวแดงเตือน แต่ Type จะตกหล่นฟิลด์นั้นไปโดยไม่รู้ตัว คู่มือการอัปเกรดของ Prisma จึงแนะนำให้ทยอยนำ Models และ Scalars ไปใช้แทน Type เดิมที่เคยเขียนด้วยมือได้เลยเมื่อสะดวก

การปรับปรุงย่อยที่ช่วยให้การทำงานราบรื่นขึ้น

รอบนี้มีการแก้บั๊ก 2 จุดที่เห็นผลชัดเจนในการทำงานจริง:

1. migration plan ทำงานแม่นยำขึ้น: หลังจากรันคำสั่ง db sign แล้ว ตัว migration plan จะเสนอเฉพาะส่วนที่มีการเปลี่ยนแปลงจริงเท่านั้น ไม่เสนอให้สร้างตารางใหม่ทั้งหมดเหมือนแต่ก่อน เพราะปัจจุบัน db sign จะตั้งค่า ref ชื่อ db ให้ชี้ไปยัง contract ที่เพิ่ง sign เสมอ แม้จะระบุฐานข้อมูลด้วย flag --db ก็ตาม ทำให้การนำฐานข้อมูลเดิมที่มีข้อมูลอยู่แล้วมาใช้งานต่อทำได้ง่ายขึ้นมาก โดยไม่ต้องทำ 3 ขั้นตอนแบบเดิมอีกต่อไป (ไม่ต้องสร้าง baseline plan, ไม่ต้อง sign ซ้ำรอบสอง และไม่ต้องรันคำสั่ง migration ref set เอง) ส่วนรายละเอียดเรื่อง migration plan เราเคยสรุปไว้แล้วในบทความ Prisma 8 rc.8

2. คืน Connection ให้ Pool เร็วขึ้นบน Postgres: สำหรับโปรเจกต์ที่ตั้งค่า Connection Pool ไว้จำกัด การ query แบบ buffered บน PostgreSQL จะคืน Connection กลับสู่ Pool ทันทีตั้งแต่ก่อนเริ่ม decode แถวข้อมูล จากเดิมที่ถ้าเราวนลูปอ่านข้อมูลผ่าน iterator แล้วหยุดค้างไว้ Connection นั้นจะค้างตามไปด้วยจนทำให้ query อื่นต้องรอ แต่ใน rc.10 ทีมงานแก้ไขปัญหานี้ให้แล้ว ส่วนการ query แบบ Cursor Stream จะยังคงถือ Connection ไว้จนจบตามปกติ และไม่กระทบต่อ Connection หรือ Transaction ที่จัดการเอง

นอกจากนี้ Language Server ใน Editor ยังปรับปรุงใหม่ให้แนะนำชื่อ Attribute ของฟิลด์, โมเดล และ block พร้อมชื่อ argument ที่ต้องใส่ให้อัตโนมัติ โดยอ้างอิงจาก target และ extension ที่ติดตั้งอยู่จริง และถ้ามี argument ที่จำเป็น ตัว Editor ก็จะใส่เป็น snippet ให้แก้ไขต่อได้ (ถ้า Editor นั้นรองรับ)

ยังเป็นรุ่น RC และมีคู่มืออัปเกรดสำหรับ AI Agent โดยเฉพาะ

อย่าลืมว่าเวอร์ชันนี้ยังเป็นเพียง Release Candidate ไม่ใช่เวอร์ชัน 8.0.0 ตัวจริงที่ใช้ปิดงานกับทีมได้

จุดที่น่าสนใจคือ ทีมงาน Prisma เขียนคู่มือการอัปเกรดแต่ละขั้นเวอร์ชันไว้เป็นไฟล์ให้ AI Coding Agent อ่านโดยตรง ในรูปแบบไฟล์ instructions.md สำหรับการอัปเกรดจาก 8.0.0-rc.9 ไปยัง 8.0.0-rc.10 ใน repository ของ Prisma เอง ซึ่งแบ่งเป็นโฟลเดอร์ทีละขั้นเวอร์ชัน ภายในมีคำอธิบายภาษาธรรมชาติ ควบคู่กับเงื่อนไขการตรวจหาไฟล์ และขั้นตอนคำสั่งที่ต้องทำตาม ทำให้ Agent ทำตามขั้นตอนได้ทันทีโดยไม่ต้องตีความเอง

นั่นแปลว่าเราสามารถเปิดเครื่องมืออย่าง Claude Code หรือ Codex แล้วสั่งให้ทำตามไฟล์นี้ได้เลย Agent จะช่วยค้นหา // use prisma-next และ PRISMA_NEXT_, เปลี่ยนชื่อไฟล์ primer รวมถึงรัน emit ให้เสร็จสรรพ แต่มี 2 เรื่องที่ต้องจำไว้เสมอ:

• ต้องตรวจสอบ Git diff เองทุกบรรทัดก่อน commit: โดยเฉพาะการเปลี่ยนชื่อ Environment Variable บน CI ที่ไม่สามารถทดสอบบนเครื่องตัวเองได้
• ห้ามแก้ไขไฟล์ contract ด้วยมือ: ให้แก้ไขที่ไฟล์ schema แล้วสั่ง emit ใหม่เสมอ

นอกจากนี้ ในรอบเดียวกันทีมงาน Prisma ยังตรวจสอบเอกสารอ้างอิงของ Agent Skill ทั้งชุดอีกครั้ง และแก้ข้อความที่ไม่ตรงกับ CLI ปัจจุบัน 21 จุด

เช็กลิสต์ 10 นาที เตรียมพร้อมก่อนเข้าสู่เวอร์ชัน Stable

ก่อนที่เวอร์ชันตัวจริงจะมาถึง มี 4 สิ่งที่ควรทำตามลำดับ ซึ่งเราประเมินว่าใช้เวลาไม่ถึง 10 นาที:

• ค้นหาคำว่า PRISMA_NEXT_ ทั่วทั้งโปรเจกต์ (รวมถึงไฟล์ .env และการตั้งค่าใน CI) แล้วเปลี่ยนเป็น PRISMA_ ทั้งหมด ยกเว้น PRISMA_NEXT_DISABLE_TELEMETRY ที่ยังคงใช้ชื่อเดิมต่อไปได้
• เปลี่ยน header บรรทัดแรกของไฟล์ .prisma ทุกไฟล์ให้เป็น // use prisma-8
• เปลี่ยนชื่อไฟล์ prisma-next.md เป็น prisma-8.md แล้วแก้ไขลิงก์ในเอกสารต่างๆ ที่ชี้มายังไฟล์นี้
• รันคำสั่ง prisma contract emit หนึ่งครั้ง แล้ว commit ไฟล์ contract.json และ contract.d.ts ที่สร้างขึ้นมาใหม่

เมื่อทำครบทั้ง 4 ข้อนี้แล้ว ค่อยทยอยนำ Models และ Scalars ไปใช้แทน Type ที่เคยเขียนด้วยมือในแต่ละไฟล์เมื่อสะดวก โดยไม่ต้องรีบร้อน

ถ้าเตรียมตัวให้พร้อมตั้งแต่วันนี้ พอถึงวันที่เวอร์ชัน 8.0.0 ตัวจริงปล่อยออกมา CI ก็จะยังคงผ่านฉลุยเป็นสีเขียวเหมือนเดิม ช่วยให้การทำงานดำเนินต่อไปได้อย่างราบรื่นโดยไม่มีอะไรติดขัด

ที่มา:

• Release v8.0.0-rc.10 · prisma/orm จาก Prisma
• Prisma 8 upgrade instructions 8.0.0-rc.9 → 8.0.0-rc.10 จาก Prisma