Blog

Drizzle ORM, Neon Postgres, and typed publication state

Catatan Teknik Naly: Drizzle ORM, Neon Postgres, dan Status Publikasi Bertipe

Lapisan publikasi konten Naly dapat dibuat deterministik dengan menyimpan setiap langkah alur kerja di Neon Postgres melalui skema Drizzle ORM. Desain ini memindahkan kontrol publikasi dari asumsi berbasis memori menjadi catatan bertipe yang tetap bertahan terhadap retry, crash, dan redeploy. Ini sangat cocok dengan eksekusi serverless di Next.js by 5

June 26, 20268 sources

Abstrak

Tumpukan ini memberi Naly sebuah kontrol publikasi bertipe: Drizzle ORM menangkap artikel, prediksi, sumber, posting media sosial, reward, dan catatan cron sebagai entitas relasional di Neon Postgres, bukan status runtime yang tersebar. Karena setiap langkah alur kerja disimpan sebagai baris eksplisit dan enum status, Naly bisa menjalankan ulang pipeline cron dengan aman, pulih dari kegagalan parsial, dan menjaga data UI yang terlihat editor tetap selaras dengan status yang terlihat oleh API. Hingga 26 Juni 2026, ini menjadi kontrak operasional yang bertahan untuk publikasi prediksi.

Posisinya dalam Naly

Pada tumpukan saat ini, perilaku publikasi dibagikan di beberapa jalur aplikasi Next.js dan pekerjaan cron, semuanya mengarah pada kontrak database yang sama. Paket yang sudah digunakan—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—sesuai dengan lapisan ORM bernuansa serverful yang berjalan di dalam route/aksi sisi server dan pekerja terjadwal.

Naly menyimpan domain ini sebagai tabel kelas pertama:

  • catatan artikel dan prediksi
  • URL sumber dan snapshot provenance
  • posting sosial + metadata distribusi
  • skor reward, metadata kalibrasi, dan bidang audit
  • metadata cron-run dan checkpoint publikasi

Nilainya bukan sekadar persistensi; tetapi semantik bersama. Setiap renderer, worker, dan aksi API membaca model status publikasi yang sama dan dapat berkoordinasi tanpa flag lintas-proses tersembunyi.

Mekanisme teknis

Drizzle menyediakan jalur berbasis skema untuk semantik bersama seperti ini. Panduan Drizzle menunjukkan alur canonical: definisikan skema di TypeScript, konfigurasikan DATABASE_URL, drizzledan gunakan tipe query yang dihasilkan untuk insert/read/update (dokumen ikhtisar, tutorial Neon).

Pola inisialisasi driver bergaya Naly yang minimal terlihat seperti ini:

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!);

Ini mencerminkan dokumentasi Drizzle yang mendukung drizzle-orm/neon-http dan drizzle-orm/neon-serverless sebagai pilihan transport untuk Neon, dengan HTTP untuk beban kerja one-shot dan perilaku sesi mirip WebSocket untuk pekerjaan transaksi interaktif saat dibutuhkan. Drizzle memiliki pg-core definisi yang juga memungkinkan inferensi bertipe ($inferInsert, $inferSelect) sehingga payload publikasi divalidasi oleh TypeScript saat compile time sambil tetap mempertahankan JSON fleksibel untuk metadata non-kritis.

Untuk Naly, pola arsitektur pentingnya adalah ini:

  1. definisikan transisi status (queued -> drafted -> approved -> published -> archived) sebagai baris eksplisit,
  2. simpanan logika transisi dalam satu modul khusus server saja,
  3. catat setiap mutasi dengan kunci idempotensi (job id + state hash),
  4. jalankan transisi kritis di dalam transaksi database ketika atomicity penting,
  5. hasilkan artefak yang tidak berubah (mis. blob URL, social copy, snapshot skema) hanya setelah status sudah maju.

Efeknya mirip mesin finite-state yang kecil dan dipersistenkan di Postgres dengan kontrak skema ketat dibanding perilaku implisit di dalam worker cron.

Apa yang dikatakan literatur

Dokumentasi utama memframing ini sebagai pilihan desain praktis untuk sistem serverless:

  • Drizzle memposisikan dirinya sebagai SQL-like secara desain dan siap serverless, mengurangi overhead abstraksi ORM untuk tim yang ingin semantik SQL langsung sambil mempertahankan keselamatan tipe (Drizzle overview).
  • Tutorial Drizzle/Neon secara eksplisit mendukung kombinasi driver Neon HTTP/WebSocket dan pemodelan skema-first bertipe, termasuk @neondatabase/serverless contoh integrasi dan inferensi tipe (Drizzle with Neon, Get Started with Drizzle + Neon).
  • Matriks koneksi Drizzle menunjukkan pemisahan driver runtime yang eksplisit, sehingga tim bisa menyelaraskan mode eksekusi dengan beban kerja dan batasan runtime (Database connection docs).
  • Dokumentasi driver dan panduan edge Neon menekankan bahwa akses serverless/Postgres umumnya dicapai lewat HTTP atau proxy berbasis websocket, sehingga keputusan eksekusi di edge harus eksplisit per beban kerja (Neon serverless driver, How to use Postgres at the edge).

Pada sisi skema, penelitian tentang evolusi skema menjelaskan mengapa migrasi dan model status yang eksplisit itu penting. Tesseract berargumen bahwa evolusi skema dapat diperlakukan sebagai operasi transaksi kelas utama dan sistem yang tangguh harus meminimalkan downtime melalui desain (online schema evolution). EvoSchema menunjukkan bahwa perubahan skema—terutama gangguan level tabel—dapat mengganggu perilaku downstream, sehingga ini menjadi peringatan keras terhadap penambahan ad-hoc sembarangan ke tabel publikasi/status (EvoSchema).

Trade-off desain

Pilihan Naly pada dasarnya adalah trade-off antara ketat dan gesekan. Skema bertipe ketat dan enum status eksplisit meningkatkan observabilitas serta keandalan, tetapi juga menaikkan biaya pemodelan awal dan menuntut disiplin migrasi. Kurva trade-off menjadi menguntungkan ketika logika publikasi menjadi titik bersama di antara worker cron, pipeline AI, dan renderer halaman publik.

  • Pilihan driver: neon-http lebih sederhana dan sering lebih cepat untuk operasi one-shot; neon-serverless lebih baik ketika sesi interaktif dibutuhkan.
  • Desain schema-first: keamanan saat compile-time menurunkan error runtime, tetapi perubahan skema menuntut perencanaan migrasi dan dapat muncul sebagai deploy yang terblokir jika pengujian tidak mencakup transisi status.
  • Portabilitas runtime: model driver yang ramah edge dari Neon memperluas opsi deployment, tetapi mode transport memengaruhi perilaku sesi, profil latensi, dan jalur autentikasi/TLS.
  • Ketepatan tipe vs kenyamanan operasional: enum eksplisit mencegah status tidak valid tetapi dapat memperlambat hotfix malam hari jika skrip migrasi belum disetujui sebelumnya.

Mode kegagalan

  • Driver yang salah untuk beban kerja: memakai query HTTP one-shot untuk transisi status multi-langkah dapat kehilangan jaminan atomik dan menghasilkan status publikasi yang parsial.
  • Pergeseran skema antar worker dan deploy: jika publication_state nilainya berubah tanpa migrasi yang terkoordinasi, kode cron lama dapat menulis status tidak valid.
  • Retry yang tidak idempotent: restart cron bisa menggandakan write sosial kecuali checkpoint bersifat idempotent dan unik per run-id.
  • Keterlambatan migrasi: job terjadwal yang berjalan terhadap snapshot skema usang dapat gagal, terutama saat rolling deploy.
  • Edge cold-start + overhead auth: di tier edge yang terbatas, setup koneksi berulang dapat menaikkan latensi dan menghasilkan false timeout kecuali anggaran timeout dan fanout job disetel.

Untuk topik ini, analisis kegagalan harus memperlakukan state publikasi sebagai artefak kebenaran, bukan detail implementasi. Setiap transisi status harus aman untuk replay.

Catatan implementasi

  • Simpan file skema terpusat dan terversi; hasilkan artefak migrasi dari satu sumber kebenaran tunggal.
  • Pisahkan tabel domain mutable dari tabel artefak immutable.
  • Modelkan transisi publikasi sebagai batas transaksi dan terapkan invarians (mis. tidak boleh ada queued -> published lompatan langsung).
  • Simpan metadata scheduler (last_run, next_run_at, error_count) dalam tabel sendiri untuk alerting dan audit.
  • Lebih baik gunakan modul server-only untuk inisialisasi DB (DATABASE_URL dari .env.local lingkungan cron/runtime).
  • Gunakan kueri terstruktur dibanding raw SQL untuk sebagian besar operasi, dan simpan raw SQL untuk seed migrasi atau pelaporan.
  • Perlakukan stateVersion dan log peristiwa sebagai jembatan kompatibilitas ketika skema berevolusi.

Referensi

Sources