The schemaCopy page

schema() compiles the tables into one catalog. This page holds the declaration, the tables list, and the oldest PostgreSQL major the catalog allows. Each other option is linked from the declaration to the page that now holds it.

The declaration

Options are sections of this page, or pages that still exist: tables, columns, and defaults. Tables come first, because every other option refers to them.

Tables

tables is every table() this schema compiles. The client name is the name you passed to table().

The list order is the order of the emitted interfaces. The catalog is sorted by identity, so swapping two tables does not change the catalog hash. Calling schema() twice on the same tables returns equal catalog bytes.

one

One table is a schema. The module default-exports it. Config points schema at this file.

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

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

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

several

.references("notes") looks up notes in this list. comments is first here. notes is second. Either order resolves.

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

const comments = table("comments", {
  id: t.identity(),
  noteId: t.bigint().references("notes"), 
  body: t.text(),
});

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

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

Minimum Postgres

minPostgres is a major. Connect checks the server against it. Omitted means 15, the oldest major okmodel runs. A feature below its major is refused when schema() runs. A bare t.id() stores gen_random_uuid() and does not need 18.

omitted

Omitted names 15. A bare t.id() stores gen_random_uuid().

Connect accepts PostgreSQL 15 and newer. okm migrate apply still looks for an explicit default uuidv7() before the first statement. A server below 18 that has no uuidv7() function is refused, and nothing is changed. A server that already defines uuidv7() is accepted. A migration with no such expression does not ask the server.

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

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

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

floor

minPostgres: 18 asks for 18 or newer. A server below that major is refused. The majors are 15, 16, 17, and 18.

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

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

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

features

Each row is a feature that refuses a lower floor. The number is the major that feature needs.

below 18

minPostgres of 15, 16, or 17 refuses a column whose default is uuidv7() when schema() runs. A bare t.id() is gen_random_uuid() and is accepted. "uuidv4" stores the same function. A client generator is the other way through. Both are on id default. An omitted floor does not refuse an explicit uuidv7() here. Apply checks the server.

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

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

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

together

A schema written for 17. Both bare t.id() columns already store gen_random_uuid(). This example sets that same function on the schema. A large write-heavy table can set uuidv7 instead, and that choice needs Postgres 18 and minPostgres: 18.

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

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

const sessions = table("sessions", {
  id: t.id(),
  name: t.text(),
});

export default schema({
  tables: [notes, sessions],
  minPostgres: 17, 
  defaults: { id: "uuidv4" },
});

string

requires: { postgres: ">=17" } is the same floor as minPostgres: 17. The string form is deprecated. Passing both is an error that names both keys. ">= 17", "17", ">=17.2", and a major outside 15 through 18 are errors. The error names minPostgres and those majors.