rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

Install#

Drizzle's drizzle-orm/bun-sql entry runs on Bun's built-in SQL class, so PostgreSQL needs no pg or postgres.js dependency — drizzle-kit is only a dev tool for generating and applying migrations. The wiring below follows the shared shape from the overview.

Shell
bun add drizzle-orm zod @rhythmjs/rhythm @rhythmjs/router @rhythmjs/middleware
bun add -d drizzle-kit

The database#

createDatabase returns the drizzle instance over a Bun.SQL client. The raw client stays reachable as db.$client, which is what the app closes on shutdown.

TypeScript
// src/database.ts
import { SQL } from "bun";
import { drizzle } from "drizzle-orm/bun-sql";
import * as schema from "./notes/notes.table";

const databaseUrl = process.env.DATABASE_URL ?? "postgres://postgres:postgres@localhost:5432/notes_drizzle";

export type Database = ReturnType<typeof createDatabase>;

export function createDatabase() {
  return drizzle({ client: new SQL(databaseUrl), schema });
}

Table and service#

Everything notes-related lives under src/notes/: the table, the zod schemas, the service, and the controller. Ids are plain text columns defaulted from crypto.randomUUID() in JavaScript, so a malformed id in the URL is an empty result instead of a database type error.

TypeScript
// src/notes/notes.table.ts
import { pgTable, text, timestamp } from "drizzle-orm/pg-core";

export const notes = pgTable("notes", {
  id: text("id")
    .primaryKey()
    .$defaultFn(() => crypto.randomUUID()),
  title: text("title").notNull(),
  content: text("content").notNull().default(""),
  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
});

export type Note = typeof notes.$inferSelect;

The service is a factory over the typed database. It owns every query; nothing else in the app touches drizzle. returning() turns updates and deletes into found-or-not answers without a second round trip.

TypeScript
// src/notes/notes.service.ts
export function createNotesService(db: Database) {
  return {
    list: () => db.select().from(notes).orderBy(desc(notes.createdAt)),
    async get(id: string) {
      const [note] = await db.select().from(notes).where(eq(notes.id, id));
      return note;
    },
    async create(input: CreateNoteInput) {
      const [note] = await db.insert(notes).values(input).returning();
      return note;
    },
    async update(id: string, patch: UpdateNoteInput) {
      const [note] = await db
        .update(notes)
        .set({ ...patch, updatedAt: new Date() })
        .where(eq(notes.id, id))
        .returning();
      return note;
    },
    async remove(id: string) {
      const deleted = await db.delete(notes).where(eq(notes.id, id)).returning({ id: notes.id });
      return deleted.length > 0;
    },
  };
}

export type NotesService = ReturnType<typeof createNotesService>;

Wiring the module#

The app module decorates db onto the startup context and closes the pool in the cleanup passed to register. It then derives notesService from it and mounts the controller. The controller is a RhythmRouter with full paths: filter() on the router renders thrown HttpErrors, validate("body", …) guards the writes and intercept(…) enforces the response contract.

TypeScript
// src/app.module.ts
export const appModule = new Rhythm({ name: "app" })
  .register(
    decorate(() => ({ db: createDatabase() })),
    ({ db }) => db.$client.close(),
  )
  .use(derive(({ db }) => ({ notesService: createNotesService(db) })))
  .use(mount(notesController));
TypeScript
// src/notes/notes.controller.ts
export const notesController = new RhythmRouter<NotesContext>()
  .use(filter())
  .use(intercept(notesResponseSchema))
  .get("/api/notes", async (ctx) => {
    json(ctx, await ctx.notesService.list());
  })
  .get("/api/notes/:id", async (ctx) => {
    const note = await ctx.notesService.get(ctx.params.id);
    if (!note) throw new HttpError(404, "Note not found");
    json(ctx, note);
  });

src/main.ts serves with Bun.serve({ port, fetch: toFetchHandler(appModule) }). On shutdown it stops the server and then calls appModule.stop(), which runs the cleanup and closes the pool.

Migrations#

drizzle-kit generate diffs notes.table.ts against the last snapshot and emits a SQL migration into drizzle/ — no database needed. drizzle-kit migrate applies whatever is pending.

TypeScript
// drizzle.config.ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/notes/notes.table.ts",
  out: "./drizzle",
  dbCredentials: { url: process.env.DATABASE_URL ?? "postgres://postgres:postgres@localhost:5432/notes_drizzle" },
});
Shell
bun run db:generate   # emit drizzle/0001_*.sql after editing the table
bun run db:migrate    # apply pending migrations

Where to next#

The same shape with a generated client: Prisma. A unit-of-work ORM that forks per request: MikroORM. No ORM at all: MongoDB. The full app is examples/drizzle-postgres.