OKModel

CI runs PostgreSQL 15 to 18. Other SQL databases are the direction. Apache-2.0.

Install

okmodel has no runtime dependencies. Each driver is an optional peer. Pick the one the runtime already has.

bun add okmodel postgres

The other drivers:

bun add okmodel pg
bun add -D @types/pg
bun add okmodel @electric-sql/pglite
bun add okmodel

postgres.js is the default on Node and Bun. node-postgres is for a project that already has pg. PGlite runs Postgres in the process. The last line is Bun.sql, built into Bun 1.4+, and it runs only there.

Date and time columns need a Temporal global. Bun and Node 26 have it. On Node 22 and 24 assign a polyfill before those columns run (OKM1210 when it is missing). Example with temporal-polyfill (not part of the quickstart script):

import { Temporal } from "temporal-polyfill";

globalThis.Temporal = Temporal;

Quick start

Define the table, compile the schema, point the config at it, push, then connect. The same steps are on Installation and Your first schema and queries.

schema.ts:

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

export const notes = table("notes", {
  id: t.id(),
  title: t.text(),
});

export default schema({ tables: [notes] });

t.id() stores gen_random_uuid(), which works on Postgres 15 to 18. For a large write-heavy table, defaults: { id: "uuidv7" } keeps the ids time-ordered and the index local. That choice needs Postgres 18 and minPostgres: 18. Omit minPostgres unless you need a newer major. requires: { postgres: ">=18" } is the same floor and is deprecated.

okmodel.config.ts:

import { defineConfig } from "okmodel/migrate";

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

okm push connects and creates the tables. It does not write a SQL file. A protected target refuses it (OKM1850).

bunx okm push

db.ts:

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

import schema from "./schema.ts";

export const db = connect(process.env.DATABASE_URL!, { schema });

Basic usage

Each call on db. Your first schema and queries has one example per call.

notes.ts:

import { db } from "./db.ts";

// insert omits id. The row that comes back has it.
export async function createNote(title: string) {
  return db.notes.insert({ title });
}

// find returns a list and needs a limit. [0] is undefined when nothing matched.
export async function readNote(id: string) {
  const found = await db.notes.find({ where: { id }, limit: 1 });
  return found[0];
}

// one returns the row, or null. More than one match throws not_unique.
export async function readOne(id: string) {
  return db.notes.one({ where: { id } });
}

// where picks the row. A write with no where is OKM1102.
export async function renameNote(id: string, title: string) {
  await db.notes.update({ where: { id }, set: { title } });
}

export async function removeNote(id: string) {
  await db.notes.delete({ where: { id } });
}

okm push is for a database you can recreate. A shared database uses reviewed migrations: okm generate init, then okm migrate apply. okm init writes starter files for one package, or for the workspace packages you select, and does not connect; okm generate init writes the first migration and is a different command.

Tooling

okm pull writes schema files from a database. okm import drizzle writes them from a Drizzle schema. Several catalogs share one database through external() and okm catalog export. describe and buildCatalog are on okmodel/migrate. Extension packs cover unaccent, hstore, ltree, btree_gist, btree_gin, fuzzystrmatch, and pgcrypto. The GitHub Action posts the migration plan on a pull request. A type change that rewrites a table is five migrations, not one ALTER COLUMN … TYPE.

Want…	Go to
Pull a database	pull
Import Drizzle	From Drizzle
Several catalogs	Catalogs
describe	Schema API
Extension packs	Extensions
The GitHub Action	GitHub Action
A rewriting type change	Type change

Next

Want…	Go to
One example per client call	Your first schema and queries
Tables, keys, and relations	Define
Every feature in one file	Guide
Run it in production	Production checklist
Install it safely	Using OKModel safely
What is not built yet	Known limits

Documentation

Resource	Link
Docs site	okm.omqkhafi.dev
Get started	/docs/start
Handbook	/docs
Changelog	/changelog
Agents index	/llms.txt
Size	docs/size.md
Security	SECURITY.md
Safe install	Using OKModel safely
Contributing	CONTRIBUTING.md

License

Published on npm. Apache-2.0.