ExpressCopy page

You get a small Express server with a read route, a write route, and a clean shutdown that closes the pool. The example is the smallest long-lived server in this handbook.

Runtime and driver

CI boots the example with Bun only. The Hono example shows a bundled Node.js entry, if you want the build step.

Install

db module and lifecycle

There is one client per process, opened at module level in src/db.ts, and every request shares its pool. It throws at import when DATABASE_URL is missing, because connect does not read the environment. closeDb() ends the pool.

/**
 * Process-scoped client for the Express example.
 *
 * One connect for the process. Close on shutdown.
 */

import { connect } from "okmodel/pg/postgresjs";

import { app } from "./schema.js";

const url = process.env.DATABASE_URL;
if (url === undefined || url.length === 0) {
  throw new Error("DATABASE_URL is required");
}

/** Shared client for this process. */
export const db = connect(url, { schema: app });

/** Closes the process client. */
export async function closeDb(): Promise<void> {
  await db.close();
}

src/schema.ts re-exports the table every framework example shares:

export { app, notes } from "../../shared/schema.js";

/**
 * Shared notes table for framework examples.
 *
 * Each example imports this schema. Tests create an isolated database and
 * apply the matching SQL before booting the app.
 */

import { schema, table, t } from "okmodel/pg";

/** Notes table used by every framework example. */
export const notes = table("example_notes", {
  id: t.identity(),
  title: t.text(),
});

/** Schema for the examples. */
export const app = schema({ tables: [notes] });

/** SQL that creates {@link notes} on an empty database. */
export const NOTES_DDL = `
create table example_notes (
  id bigint generated by default as identity primary key,
  title text not null
);
`;

In your own app, define the table in src/schema.ts directly. The table is named example_notes, so the client property is db.example_notes.

Connection config

One route that reads and writes

GET /notes returns the oldest 50 notes. POST /notes takes { "title": "..." } and returns the new row with status 201. Database errors go to Express through next(error). GET /health does not touch the database; it is the readiness check the test waits on, and the one to point a load balancer at. On SIGINT or SIGTERM the server stops accepting connections and calls closeDb().

A body that is not valid JSON never reaches the route: express.json() rejects it first. POST /notes has no authentication; express.json() caps the body at its default 100 KB. Add authentication before you copy it.

/**
 * Smallest Express app: GET reads notes, POST writes one.
 */

import express from "express";

import { closeDb, db } from "./db.js";

const port = Number(process.env.PORT ?? "3101");
const app = express();
app.use(express.json());

app.get("/notes", async (_req, res, next) => {
  try {
    const rows = await db.example_notes.find({
      orderBy: { id: "asc" },
      limit: 50,
    });
    res.json(rows);
  } catch (error) {
    next(error);
  }
});

app.post("/notes", async (req, res, next) => {
  try {
    const title = typeof req.body?.title === "string" ? req.body.title : undefined;
    if (title === undefined || title.length === 0) {
      res.status(400).json({ error: "title is required" });
      return;
    }
    const row = await db.example_notes.insert({ title });
    res.status(201).json(row);
  } catch (error) {
    next(error);
  }
});

app.get("/health", (_req, res) => {
  res.json({ ok: true });
});

const server = app.listen(port, () => {
  console.log(`express example on ${port}`);
});

async function shutdown(): Promise<void> {
  server.close();
  await closeDb();
}

process.on("SIGINT", () => void shutdown());
process.on("SIGTERM", () => void shutdown());

Dev and test

Start Postgres, point DATABASE_URL at it, create the table, then run the server. In this repository, bun run db:up starts a local Postgres whose primary URL is below.

bun run db:up
export DATABASE_URL=postgres://okm:okm@127.0.0.1:55432/okm

The example has no okmodel.config.ts. In your app, add one next to package.json:

import { defineConfig } from "okmodel/migrate";

export default defineConfig({
  schema: "./src/schema.ts",
  database: process.env.DATABASE_URL!,
});

Create the table on a fresh database with okm push, which writes no SQL file and suits a database you can drop:

target default
applied push-1

For a database you will deploy, write the first migration and apply it, then commit migrations/. After a later schema change, run bunx okm push again on a dev database, or bunx okm generate <name> then bunx okm migrate apply.

Start the server in the same shell. Without DATABASE_URL there, it stops at start with error: DATABASE_URL is required.

cd examples/express
bun run dev

Call it from another terminal:

curl -i http://localhost:3101/health
curl -i -X POST http://localhost:3101/notes -H 'content-type: application/json' -d '{"title":"hello"}'
curl -i http://localhost:3101/notes

These responses come from a run on a fresh database. id is a string, because the default codec for t.identity() is a string.

The example's own test does not run okm: it creates an isolated database and applies NOTES_DDL through examples/shared/support.ts, which is faster. To run it from a clone:

bun run build
bun run db:up
bun install --cwd examples/express
cd examples/express && REQUIRE_DOCKER=1 bun test ./express.test.ts

Deploy and migrate-on-deploy

Run src/server.ts under Bun, or a compiled copy under Node.js, behind your process manager, with DATABASE_URL set. Send SIGTERM to stop it so closeDb() runs.

Apply migrations before the new version takes traffic. Run this in your release job, with DATABASE_URL pointing at a direct connection to the primary, not a pooler:

A migration that only adds things lets the old version keep running while the release rolls out (Migrations in CI, Environments).

Limits and gotchas

• Do not create a client per request. Import the one in src/db.ts.
• Only SIGINT and SIGTERM close the pool. A process killed with SIGKILL leaves its connections for Postgres to reap.
• The route returns at most 50 rows. To read past them, page through the rest (Read rows).

What is tested

The frameworks job runs on pull requests that touch examples/, the runtime, the dialects, or the Frameworks pages, and after each merge.