Blog

Drizzle ORM, Neon Postgres, and typed publication state

หมายเหตุด้านวิศวกรรมของ Naly: Drizzle ORM, Neon Postgres และสถานะการเผยแพร่แบบมีชนิดข้อมูล

ชั้นการเผยแพร่เนื้อหาของ Naly สามารถทำให้มีความกำหนดได้โดยการเก็บขั้นตอนงานทั้งหมดใน Neon Postgres ผ่านสคีมาของ Drizzle ORM การออกแบบนี้ย้ายการควบคุมการเผยแพร่จากสมมติฐานแบบในหน่วยความจำไปสู่เรกคอร์ดที่มีชนิดข้อมูลและคงอยู่แม้เกิดการลองใหม่ ข้อผิดพลาด หรือการนำกลับมาใช้งานใหม่ มันเข้ากันได้ดีกับการรันแบบ serverless ใน Next.js โดย 5

June 26, 20268 sources

บทคัดย่อ

สแต็กนี้ทำให้ Naly ได้รับชั้นควบคุมการเผยแพร่แบบมีชนิดข้อมูล: Drizzle ORM จัดเก็บข้อมูลบทความ การคาดการณ์ แหล่งข้อมูล โพสต์ทางโซเชียล คะแนนรางวัล และระเบียน cron เป็นเอนทิตีเชิงสัมพันธ์ใน Neon Postgres แทนที่จะเป็นสถานะ runtime ที่กระจัดกระจาย เนื่องจากแต่ละขั้นตอนงานถูกเก็บเป็นแถวและ enum สถานะที่ชัดเจน Naly จึงสามารถรัน pipeline ของ cron ซ้ำได้อย่างปลอดภัย ฟื้นฟูความล้มเหลวแบบบางส่วน และทำให้ข้อมูล UI ที่ผู้สร้างเนื้อหาเห็นสอดคล้องกับสถานะที่ API แสดง การณ ในวันที่ 26 มิถุนายน 2026 นี่คือสัญญาปฏิบัติการที่ทนทานของโครงการสำหรับการเผยแพร่การคาดการณ์

ตำแหน่งใน Naly

ในสแต็กปัจจุบัน พฤติกรรมการเผยแพร่ถูกแชร์อยู่ในหลายเส้นทางของแอป Next.js และ cron jobs ซึ่งทั้งหมดชี้ไปยัง contract ของฐานข้อมูลเดียวกัน ชุดแพ็กเกจที่ใช้งานอยู่—next@16.0.7, react@19.2.1, drizzle-orm@^0.44.7, @neondatabase/serverless@^1.0.2, tsx@^4.21.0, typescript@^5.9.3—ตรงกับเลเยอร์ ORM แบบ serverful-ish ที่ทำงานอยู่ภายใน server-side routes/actions และ scheduled workers

Naly จัดเก็บโดเมนเหล่านี้เป็นตารางระดับแรก:

  • ระเบียนบทความและการคาดการณ์
  • URL แหล่งที่มาและสแน็ปช็อตแหล่งที่มา
  • โพสต์โซเชียล + ข้อมูล metadata การจัดจำหน่าย
  • คะแนนรางวัล เมตาดาต้าการปรับเทียบ และฟิลด์ audit
  • เมตาดาต้าการรัน cron และจุดตรวจการเผยแพร่

คุณค่าคือไม่ได้อยู่แค่ความคงทน แต่คือ semantics ที่ใช้ร่วมกัน เรนเดอร์ทุกตัว worker และ API action อ่านโมเดลสถานะการเผยแพร่ชุดเดียวกัน และสามารถประสานกันได้โดยไม่พึ่งธงข้ามกระบวนการที่ซ่อนอยู่

กลไกเชิงเทคนิค

Drizzle ให้แนวทางแบบ schema-first สำหรับ semantics แบบใช้ร่วมกันลักษณะนี้ คู่มือ Drizzle แสดงลำดับงานมาตรฐาน: กำหนด schema ใน TypeScript กำหนดค่า DATABASE_URL , initialize drizzle, และใช้ query types ที่สร้างขึ้นสำหรับการ insert/read/update (เอกสารภาพรวม, บทช่วยสอน Neon).

รูปแบบการเริ่มต้นไดรเวอร์สไตล์ Naly แบบกะทัดรัดจะมีลักษณะดังนี้:

import { drizzle } from 'drizzle-orm/neon-http';
import { pgTable, text, timestamp, pgEnum, integer } from 'drizzle-orm/pg-core';

export const publicationState = pgEnum('publication_state', [
  'queued', 'draft_ready', 'published', 'failed',
]);

export const publications = pgTable('publications', {
  id: text('id').primaryKey(),
  slug: text('slug').notNull().unique(),
  state: publicationState('state').notNull(),
  stateVersion: integer('state_version').notNull().default(1),
  stateChangedAt: timestamp('state_changed_at').notNull().defaultNow(),
});

const db = drizzle(process.env.DATABASE_URL!);

สิ่งนี้สะท้อนเอกสารของ Drizzle ที่รองรับ drizzle-orm/neon-http และ drizzle-orm/neon-serverless เป็นตัวเลือกการส่งข้อมูลสำหรับ Neon โดยมี HTTP สำหรับงานแบบ one-shot และพฤติกรรม session ลักษณะ WebSocket สำหรับงาน transaction แบบโต้ตอบเมื่อจำเป็น Drizzle pg-core definitions ยังช่วยให้ทำ typed inference ได้ ($inferInsert, $inferSelect) ทำให้ payload การเผยแพร่ถูกตรวจสอบด้วย TypeScript ระดับ compile time ขณะคงความยืดหยุ่นของ JSON สำหรับเมตาดาต้าที่ไม่สำคัญได้

สำหรับ Naly แพทเทิร์นสถาปัตยกรรมที่สำคัญคือ:

  1. กำหนด state transitions (queued -> drafted -> approved -> published -> archived) เป็นแถวอย่างชัดแจ้ง
  2. เก็บตรรกะการเปลี่ยนผ่านไว้ในโมดูลฝั่งเซิร์ฟเวอร์เดียว
  3. บันทึกการเปลี่ยนแปลงแต่ละครั้งด้วย idempotency key (job id + state hash)
  4. รันการเปลี่ยนผ่านที่สำคัญภายใน transaction ของฐานข้อมูลเมื่อความเป็นอะตอมิกเป็นเรื่องสำคัญ
  5. สร้าง artefact แบบคงที่เท่านั้น (เช่น blob URLs, social copy, schema snapshots) หลังจากสถานะถูกเลื่อนขั้นแล้ว

ผลลัพธ์คล้ายกับ finite-state machine ขนาดเล็กที่ถูกคงอยู่ใน Postgres โดยมีสัญญาสคีมาที่เข้มงวด มากกว่าพฤติกรรมที่เป็นนัยใน cron workers

สิ่งที่วรรณกรรมกล่าวไว้

เอกสารชั้นหลักวางประเด็นนี้เป็นตัวเลือกออกแบบที่ใช้งานได้จริงสำหรับระบบ serverless:

  • Drizzle วางตัวเองให้ใกล้เคียง SQL โดยการออกแบบและพร้อมสำหรับ serverless ลดภาระ abstraction ของ ORM สำหรับทีมที่ต้องการ SQL semantics โดยตรงในขณะยังคง type safety (ภาพรวมของ Drizzle).
  • คู่มือ Drizzle/Neon ระบุชัดเจนว่ารองรับชุดไดรเวอร์ Native Neon HTTP/WebSocket และการออกแบบ schema-first แบบมีชนิด โดยรวมถึง @neondatabase/serverless ตัวอย่าง integration และการอนุมานชนิดข้อมูล (Drizzle with Neon, Get Started with Drizzle + Neon).
  • เมตริกซ์การเชื่อมต่อของ Drizzle แสดงการแยก runtime-driver อย่างชัดเจน เพื่อให้ทีมสามารถจับคู่โหมดการทำงานให้เหมาะกับลักษณะงานและข้อจำกัด runtime (เอกสารการเชื่อมต่อฐานข้อมูล).
  • เอกสารไดรเวอร์ของ Neon และแนวทาง edge เน้นว่าการเข้าถึง serverless/Postgres มักทำผ่านการ proxy ด้วย HTTP หรือ websocket ซึ่งเป็นเหตุผลหลักว่าทำไมการตัดสินใจรันที่ edge จึงต้องชัดเจนต่อแต่ละ workload (Neon serverless driver, How to use Postgres at the Edge).

ด้านสคีมา งานวิจัยเรื่องวิวัฒนาการสคีมาแสดงเหตุผลว่าทำไม migration และโมเดลสถานะที่ชัดเจนจึงสำคัญ Tesseract ชี้ว่าการวิวัฒนาการสคีมาสามารถถือเป็นปฏิบัติการ transaction ระดับแรก และระบบที่แข็งแกร่งควรลด downtime โดยการออกแบบ (online schema evolution). EvoSchema แสดงว่าการเปลี่ยนสคีมา โดยเฉพาะการกระทบระดับตาราง อาจทำให้พฤติกรรม downstream ไม่เสถียร ซึ่งเป็นการเตือนที่รุนแรงต่อการเพิ่มแบบ ad-hoc แบบสุ่มในตาราง publication/state (EvoSchema).

การชั่งน้ำหนักการออกแบบ

การเลือกของ Naly โดยรวมคือการถ่วงดุลระหว่างความเข้มงวดกับความฝืด หากใช้อย่างจริงจัง schemas ที่พิมพ์ได้แน่นอนและ enum สถานะที่ชัดเจนช่วยเพิ่มความสังเกตได้และความน่าเชื่อถือ แต่ก็เพิ่มต้นทุนการออกแบบล่วงหน้าและต้องการวินัยในการ migrate การชี้กราฟมีแนวโน้มดีขึ้นเมื่อ logic การเผยแพร่ถูกแชร์ข้าม cron worker, AI pipeline และตัวเรนเดอร์หน้าสาธารณะ

  • ทางเลือกการเลือกไดรเวอร์: neon-http ง่ายกว่าและมักเร็วขึ้นสำหรับงานแบบ one-shot neon-serverless ดีขึ้นเมื่อจำเป็นต้องมีเซสชันแบบโต้ตอบ
  • การออกแบบแบบ schema-first: ความปลอดภัยระดับ compile-time ลดข้อผิดพลาด runtime แต่การเปลี่ยนสคีมาต้องมีแผน migration และอาจปรากฏเป็น deploy ที่ถูกบล็อกหากการทดสอบไม่ครอบคลุมการเปลี่ยนผ่านสถานะ
  • ความสามารถในการย้าย runtime: โมเดลไดรเวอร์ที่เป็นมิตรกับ edge ของ Neon ขยายตัวเลือกการ deploy แต่โหมดการส่งข้อมูลส่งผลต่อพฤติกรรม session โปรไฟล์ latency และเส้นทางการยืนยันตัวตน/TLS
  • ความถูกต้องของชนิดข้อมูลเทียบกับความสะดวกในการปฏิบัติงาน: enum ที่ชัดเจนช่วยป้องกันสถานะที่ไม่ถูกต้อง แต่สามารถทำให้การแก้ไขด่วนดึกคืนช้าลง หากสคริปต์ migration ยังไม่ได้รับอนุมัติก่อน

โหมดความล้มเหลว

  • ใช้ไดรเวอร์ไม่เหมาะกับลักษณะงาน: การใช้การสืบค้น HTTP แบบ one-shot สำหรับการเปลี่ยนผ่านสถานะหลายขั้นอาจสูญเสียการรับประกันความอะตอมิกและสร้างสถานะเผยแพร่บางส่วน
  • การเปลี่ยน schema ไหลหลุดระหว่าง worker และการ deploy: หาก publication_state ค่าเปลี่ยนไปโดยไม่มี migration ที่ประสานงาน โค้ด cron รุ่นเก่าอาจเขียนสถานะที่ไม่ถูกต้อง
  • การลองซ้ำที่ไม่ idempotent: cron เริ่มใหม่อาจทำให้การเขียนสู่โซเชียลซ้ำซ้อน ยกเว้น checkpoints เป็น idempotent และไม่ซ้ำกันตาม run-id
  • ความล่าช้าในการ migrate: งานที่ตั้งเวลาไว้รันกับสแน็ปช็อตสคีมาเก่าสามารถล้มเหลวได้ โดยเฉพาะระหว่างการ deploy แบบ rolling
  • ต้นทุนเริ่มต้น edge + auth: ในโหมด edge ที่จำกัด การตั้งค่าการเชื่อมต่อซ้ำบ่อยอาจเพิ่ม latency และทำให้เกิด timeout เทียม หากไม่ปรับ timeout budget และการกระจายงานให้เหมาะสม

สำหรับประเด็นนี้ การวิเคราะห์ความล้มเหลวควรปฏิบัติต่อสถานะการเผยแพร่ในฐานะ artefact ของความถูกต้อง ไม่ใช่รายละเอียดการ implement ทุกการเปลี่ยนผ่านสถานะต้อง replay-safe

หมายเหตุการนำไปใช้

  • เก็บไฟล์สคีมาไว้เป็นศูนย์กลางและเวอร์ชันเดียว สร้าง artifacts สำหรับ migration ซ้ำใหม่จากจุดรวมข้อมูลเดียว
  • แยกตารางโดเมนที่เปลี่ยนได้ออกจากตาราง artifact ที่ไม่เปลี่ยนแปลง
  • แบบจำลองการเปลี่ยนผ่านการเผยแพร่เป็นขอบเขต transaction และบังคับ invariant (เช่น ไม่ให้มีการ queued -> published กระโดดโดยตรง)
  • เก็บเมตาดาต้าของ scheduler (last_run, next_run_at, error_count) ในตารางของตัวเองเพื่อใช้ในการแจ้งเตือนและตรวจสอบ
  • แนะนำให้ใช้โมดูลฝั่งเซิร์ฟเวอร์เท่านั้นสำหรับการเริ่มต้น DB (DATABASE_URL จาก .env.local ในสภาพแวดล้อม cron/runtime)
  • ใช้ structured query แทน raw SQL ในงานส่วนใหญ่ และสงวน raw SQL สำหรับ seed ของ migration หรือการรายงาน
  • ปฏิบัติต่อ stateVersion และ event log เป็นสะพานความเข้ากันได้เมื่อสคีมาเปลี่ยนแปลง

เอกสารอ้างอิง

Sources