EnvironmentsCopy page

An environment is a named target. Nothing about it is inferred from NODE_ENV or from the name. Protection is protected: true on that entry. A pipeline always passes --target. With more than one target, the commands that must pick one database are OKM1853 when it is omitted. Those commands are on Database. The checklist is Production checklist.

An empty target installs the head snapshot and reference rows. The snapshot rules are Required rows. A target that already has history replays pending files. The command is migrate apply.

Preview

One ephemeral database per pull request. Infrastructure creates it: a branch, CREATE DATABASE, or a container. OKModel does not drop it.

1. Create the empty database.
2. Register it as a target, for example preview.
3. okm migrate apply --target preview. An empty database installs the head snapshot and reference rows.
4. Optionally seed, then deploy the application with the preview URL. okm seed loads the file.
5. Deleting the database when the pull request closes is the infrastructure's job.

import { defineConfig } from "okmodel/migrate";

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

export default defineConfig({
  schema: "./schema.ts",
  targets: {
    preview: url,
  },
});

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

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

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

okm migrate apply --target preview

Rehearsal

To try pending migrations against realistic data, clone or branch the production database, register the clone as a target, and run:

okm migrate apply --target rehearsal

A clone already has history, so this replays the pending migration files. The report is the command's stdout: which migrations ran, and the error if a step stops. The recipe is apply on a clone.

A preview built from the head snapshot and a rehearsal built by replaying history are required to match. okm migrate check --provision is that comparison. A difference is OKM1521. How the two scratch schemas are compared is Lint.

The package copy is docs/environments.md on main.