Drizzle ORM di Hono: Membangun REST API Artikel dengan Bun dan PostgreSQL
Hono dikenal sebagai web framework yang ringan dan cepat, sedangkan Drizzle adalah ORM TypeScript yang gaya penulisannya mirip SQL. Keduanya sama-sama kecil, berbasis TypeScript, dan jalan mulus di Bun, jadi kombinasinya populer untuk membangun API. Di artikel ini kita membuat REST API artikel lengkap dengan PostgreSQL: dari schema, migrasi, validasi, sampai CRUD dengan pagination, pencarian, dan sorting.
Catatan penting soal versi
Drizzle sedang berada di masa transisi ke v1. Menurut dokumentasi resminya, v1 dipasang lewat tag @rc, sedangkan rilis stabil (latest) masih di seri 0.x. Ada dua hal yang perlu kamu tahu:
Pakai minimal 0.45.2 kalau memilih jalur stabil. Versi itu memperbaiki masalah escaping pada
sql.identifier()dansql.as()yang berpotensi SQL injection. Jangan pernah memasukkan input pengguna ke fungsi itu.Kode di artikel ini hanya memakai query builder inti (
select,insert,update,delete), tanpa relational queries dan tanpa API casing. Bagian yang berubah besar di v1 tidak tersentuh, sehingga kode yang sama seharusnya berjalan di kedua jalur. Rangkuman perubahan v1 ada di bagian akhir.
Yang akan kita bangun
API artikel dengan lima endpoint:
GET /articles: daftar dengan pagination, pencarian, dan sortingGET /articles/:slug: detail satu artikelPOST /articles: membuat artikelPUT /articles/:id: memperbarui artikelDELETE /articles/:id: menghapus artikel
1. Membuat proyek
bun create hono@latest blog-api # pilih template "bun"
cd blog-api
bun add drizzle-orm zod @hono/zod-validator
bun add -D drizzle-kit dotenvKita memakai PostgreSQL lewat driver Bun SQL yang sudah bawaan Bun, jadi tidak perlu paket driver tambahan seperti pg. Kalau belum punya database, cara cepatnya lewat Docker:
docker run --name blog-db -e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=blog -p 5432:5432 -d postgres:17Lalu buat file .env:
DATABASE_URL=postgres://postgres:postgres@localhost:5432/blog2. Struktur folder
blog-api/
├── drizzle.config.ts
├── drizzle/ # file migrasi (dibuat otomatis)
└── src/
├── index.ts # aplikasi Hono
├── db/
│ ├── index.ts # koneksi database
│ └── schema.ts # definisi tabel
└── routes/
└── articles.ts # endpoint artikel3. Mendefinisikan schema
Di Drizzle, schema ditulis sebagai kode TypeScript dan menjadi sumber kebenaran untuk tipe sekaligus migrasi.
// src/db/schema.ts
import { integer, pgTable, text, timestamp, varchar } from 'drizzle-orm/pg-core';
export const articles = pgTable('articles', {
id: integer().primaryKey().generatedAlwaysAsIdentity(),
slug: varchar({ length: 255 }).notNull().unique(),
title: varchar({ length: 255 }).notNull(),
description: text().notNull(),
content: text().notNull(),
author: varchar({ length: 100 }),
image_url: text(),
date: timestamp({ withTimezone: true }).notNull().defaultNow(),
created_at: timestamp({ withTimezone: true }).notNull().defaultNow(),
updated_at: timestamp({ withTimezone: true })
.notNull()
.defaultNow()
.$onUpdate(() => new Date()),
});
export type Article = typeof articles.$inferSelect;
export type NewArticle = typeof articles.$inferInsert;Beberapa hal yang layak dicatat:
Nama properti sengaja memakai snake_case (
image_url,created_at) agar JSON yang keluar sama dengan yang diharapkan CMS, tanpa fungsi pemetaan tambahan. Kalau kamu lebih suka camelCase, tulis satu fungsiserialize()untuk mengubah bentuknya.$onUpdatemengisiupdated_atotomatis setiap kali data diperbarui lewat Drizzle.$inferSelectdan$inferInsertmenghasilkan tipe TypeScript langsung dari schema, jadi tidak perlu menulis interface terpisah.
4. Koneksi database
// src/db/index.ts
import { drizzle } from 'drizzle-orm/bun-sql';
export const db = drizzle(process.env.DATABASE_URL!);Hanya itu. Bun otomatis membaca file .env, jadi tidak perlu memuat dotenv di kode aplikasi.
5. Konfigurasi dan migrasi
// drizzle.config.ts
import 'dotenv/config';
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
dialect: 'postgresql',
schema: './src/db/schema.ts',
out: './drizzle',
dbCredentials: { url: process.env.DATABASE_URL! },
});Tambahkan script di package.json:
{
"scripts": {
"dev": "bun run --hot src/index.ts",
"db:generate": "drizzle-kit generate",
"db:migrate": "drizzle-kit migrate",
"db:push": "drizzle-kit push",
"db:studio": "drizzle-kit studio"
}
}Alurnya:
bun run db:generate # membuat file SQL migrasi di folder ./drizzle
bun run db:migrate # menjalankan migrasi ke databasePada tahap awal pengembangan, db:push menerapkan perubahan schema langsung ke database tanpa membuat file migrasi. Praktis untuk eksperimen, tetapi untuk proyek yang sudah punya data, tetap gunakan generate dan migrate agar riwayat perubahan tercatat di Git. db:studio membuka antarmuka web untuk melihat isi tabel.
6. Aplikasi Hono
// src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { HTTPException } from 'hono/http-exception';
import { logger } from 'hono/logger';
import { articlesRoute } from './routes/articles';
const app = new Hono();
app.use(logger());
app.use(cors({ origin: 'http://localhost:3000' })); // alamat CMS / blog
app.route('/articles', articlesRoute);
app.notFound((c) => c.json({ message: 'Endpoint tidak ditemukan' }, 404));
app.onError((error, c) => {
if (error instanceof HTTPException) {
return c.json({ message: error.message }, error.status);
}
console.error(error);
return c.json({ message: 'Terjadi kesalahan pada server' }, 500);
});
// Port 3000 biasanya dipakai Next.js, jadi API pakai 3001.
export default { port: 3001, fetch: app.fetch };Dua hal di sini sering menjebak. Pertama, tanpa cors, browser akan memblokir permintaan dari aplikasi Next.js ke API ini. Kedua, onError membuat semua error, termasuk HTTPException yang kita lempar dari route, keluar dalam bentuk { message } yang konsisten.
7. Endpoint artikel
Pertama, schema validasi dengan Zod. Kita bungkus zValidator dalam fungsi kecil supaya error validasi ikut memakai format { message, errors }:
// src/routes/articles.ts
import { zValidator } from '@hono/zod-validator';
import { and, asc, count, desc, eq, ilike, ne, or } from 'drizzle-orm';
import { Hono } from 'hono';
import type { ValidationTargets } from 'hono';
import { HTTPException } from 'hono/http-exception';
import { z } from 'zod';
import type { ZodType } from 'zod';
import { db } from '../db';
import { articles } from '../db/schema';
export const articlesRoute = new Hono();
function validate<Target extends keyof ValidationTargets, Schema extends ZodType>(
target: Target,
schema: Schema,
) {
return zValidator(target, schema, (result, c) => {
if (!result.success) {
return c.json(
{
message: 'Data tidak valid',
errors: result.error.issues.map((issue) => ({
field: issue.path.join('.'),
message: issue.message,
})),
},
400,
);
}
});
}
const articleBody = z.object({
title: z.string().trim().min(1).max(255),
slug: z
.string()
.trim()
.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Slug hanya boleh huruf kecil, angka, dan tanda hubung'),
description: z.string().trim().min(1),
content: z.string().trim().min(1),
author: z.string().trim().min(1).max(100),
date: z.coerce.date(),
image_url: z.string().url().nullable(),
});
const idParam = z.object({ id: z.coerce.number().int().positive() });
const listQuery = z.object({
page: z.coerce.number().int().min(1).default(1),
limit: z.coerce.number().int().min(1).max(100).default(10),
search: z.string().trim().optional(),
sort: z.enum(['date', 'title', 'author', 'created_at']).default('date'),
order: z.enum(['asc', 'desc']).default('desc'),
});
// Hanya kolom yang ada di daftar ini yang boleh dipakai untuk sorting.
const sortColumns = {
date: articles.date,
title: articles.title,
author: articles.author,
created_at: articles.created_at,
} as const;
// Karakter % dan _ pada LIKE punya arti khusus, jadi perlu di-escape.
const escapeLike = (value: string) => value.replace(/[\\%_]/g, '\\$&');Daftar artikel: pagination, pencarian, sorting
articlesRoute.get('/', validate('query', listQuery), async (c) => {
const { page, limit, search, sort, order } = c.req.valid('query');
const where = search
? or(
ilike(articles.title, `%${escapeLike(search)}%`),
ilike(articles.description, `%${escapeLike(search)}%`),
)
: undefined;
const column = sortColumns[sort];
const [rows, totals] = await Promise.all([
db
.select()
.from(articles)
.where(where)
.orderBy(order === 'asc' ? asc(column) : desc(column))
.limit(limit)
.offset((page - 1) * limit),
db.select({ total: count() }).from(articles).where(where),
]);
const total = totals[0]?.total ?? 0;
return c.json({
message: 'success',
data: rows,
meta: {
page,
limit,
total,
totalPages: Math.ceil(total / limit),
search: search ?? null,
sort: { key: sort, order },
},
});
});Beberapa detail yang sengaja dibuat:
Query data dan query
count()berjalan paralel denganPromise.all, dengan kondisiwhereyang sama agar total selalu sesuai hasil pencarian.Kolom sorting diambil dari daftar putih (
sortColumns), bukan dari input mentah, supaya pengguna tidak bisa mengurutkan berdasarkan kolom sembarangan.Bentuk respons memakai
{ message, data, meta }seperti API yang dipakai CMS dan blog kita sebelumnya.Untuk daftar yang besar, pertimbangkan memilih kolom tertentu saja (
db.select({ id: articles.id, title: articles.title, ... })) agar kolomcontentyang berat tidak ikut terkirim.
Detail, buat, perbarui, hapus
articlesRoute.get('/:slug', async (c) => {
const [article] = await db
.select()
.from(articles)
.where(eq(articles.slug, c.req.param('slug')))
.limit(1);
if (!article) throw new HTTPException(404, { message: 'Artikel tidak ditemukan' });
return c.json({ message: 'success', data: article });
});
articlesRoute.post('/', validate('json', articleBody), async (c) => {
const body = c.req.valid('json');
const [created] = await db
.insert(articles)
.values(body)
.onConflictDoNothing({ target: articles.slug })
.returning();
// Tidak ada baris yang dikembalikan berarti slug sudah dipakai.
if (!created) throw new HTTPException(409, { message: 'Slug sudah dipakai artikel lain' });
return c.json({ message: 'Artikel dibuat', data: created }, 201);
});
articlesRoute.put('/:id', validate('param', idParam), validate('json', articleBody), async (c) => {
const { id } = c.req.valid('param');
const body = c.req.valid('json');
const [taken] = await db
.select({ id: articles.id })
.from(articles)
.where(and(eq(articles.slug, body.slug), ne(articles.id, id)))
.limit(1);
if (taken) throw new HTTPException(409, { message: 'Slug sudah dipakai artikel lain' });
const [updated] = await db.update(articles).set(body).where(eq(articles.id, id)).returning();
if (!updated) throw new HTTPException(404, { message: 'Artikel tidak ditemukan' });
return c.json({ message: 'Artikel diperbarui', data: updated });
});
articlesRoute.delete('/:id', validate('param', idParam), async (c) => {
const { id } = c.req.valid('param');
const [deleted] = await db
.delete(articles)
.where(eq(articles.id, id))
.returning({ id: articles.id });
if (!deleted) throw new HTTPException(404, { message: 'Artikel tidak ditemukan' });
return c.json({ message: 'Artikel dihapus' });
});Perhatikan dua pola Drizzle yang berguna di sini:
.returning()mengembalikan baris yang baru disisipkan, diubah, atau dihapus dalam satu query. Kalau hasilnya kosong, kita tahu data tidak ditemukan tanpa query tambahan.onConflictDoNothingmenangani slug ganda di level database, tanpa bergantung pada format pesan error milik driver tertentu. Constraintunique()di schema tetap menjadi jaring pengaman kalau dua permintaanPUTbertabrakan di waktu yang hampir bersamaan.
8. Mencobanya
bun run dev
# Buat artikel
curl -X POST http://localhost:3001/articles \
-H 'Content-Type: application/json' \
-d '{
"title": "Halo Drizzle",
"slug": "halo-drizzle",
"description": "Artikel pertama",
"content": "<p>Isi artikel</p>",
"author": "admin",
"date": "2026-11-17T08:00:00.000Z",
"image_url": null
}'
# Daftar dengan pencarian dan sorting
curl 'http://localhost:3001/articles?page=1&limit=5&search=drizzle&sort=title&order=asc'Tips tambahan
Transaksi: untuk beberapa operasi yang harus berhasil bersama, bungkus dengan
db.transaction(async (tx) => { ... })dan pakaitxalih-alihdbdi dalamnya.Tipe end-to-end: ekspor
export type AppType = typeof appdari Hono, lalu pakai Hono RPC (hc) di Next.js agar tipe respons API mengalir ke frontend tanpa menulis ulang.Autentikasi: endpoint tulis (
POST,PUT,DELETE) sebaiknya dilindungi middleware JWT. Cek dokumentasi Hono untuk opsi terbarunya sebelum menerapkannya.Debug query: aktifkan
drizzle(url, { logger: true })untuk melihat SQL yang dihasilkan.
Bagaimana dengan Drizzle v1?
Kalau kamu ingin mencoba v1, dokumentasi resmi memakai tag @rc:
bun add drizzle-orm@rc
bun add -D drizzle-kit@rc
bunx drizzle-kit up # mengubah struktur folder migrasi lama ke format baruPerubahan terbesarnya, menurut halaman "v0 → v1 updates":
Relational Queries v1 dihapus. Relasi sekarang ditulis dengan
defineRelations()di satu tempat.API casing baru: opsi
casingdidrizzle()digantisnakeCase.table(...)dancamelCase.table(...).Paket validator pindah ke dalam
drizzle-orm, misalnyadrizzle-zodmenjadidrizzle-orm/zod.drizzle-kit ditulis ulang: folder migrasi tidak lagi memakai
journal.json, dan adadrizzle-kit checkuntuk mendeteksi migrasi yang bentrok antar-branch.Error query tidak lagi menyertakan parameter secara default, kecuali kamu mengaktifkan
paramsInErrors: true.
Untuk proyek produksi, jalur rilis stabil 0.x tetap pilihan yang lebih aman sampai v1 dirilis sebagai versi final. Kalau kamu mulai dari proyek baru, tidak ada salahnya memakai kode dasar di artikel ini lalu mencoba v1 di branch terpisah.
Kesimpulan
Drizzle dan Hono cocok dipasangkan karena sama-sama tipis dan menjaga tipe dari ujung ke ujung: schema Drizzle menghasilkan tipe, Zod memvalidasi input, dan Hono menyajikannya sebagai API. Dengan Bun sebagai runtime dan driver Bun SQL bawaan, setup-nya pun minim dependensi. Dari sini kamu bisa menambah autentikasi JWT, relasi antar tabel.