Migration

Migration protocol — the two kinds of migration, kept apart on purpose.

A schema migration (ChangeSet + its atomic operations) reshapes the physical database to match metadata: add a field, change a type, create an object, run SQL. It is derivable from the metadata and applied by os migrate plan / os migrate apply.

A data migration rewrites the rows themselves, and whether it is done is a property of ONE DEPLOYMENT's database rather than of the installed code version — so it cannot be expressed as a ChangeSet, and its completion cannot be inferred from a release. DataMigrationFlag is the per-deployment record that one ran here and its self-check passed; consumers that would act irreversibly on migrated data gate on the flag instead of the version.

Source: packages/spec/src/system/migration.zod.ts

TypeScript Usage

import { AddFieldOperation, ChangeSetSchema, CreateObjectOperation, DataMigrationFlagSchema, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependencySchema, MigrationJournalEventSchema, MigrationOperationSchema, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system';
import type { ChangeSet, DataMigrationFlag, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, MigrationJournalEvent, MigrationOperation, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system';

// Validate data
const result = AddFieldOperation.parse(data);

AddFieldOperation

Add a new field to an existing object

Property	Type	Required	Description
type	`'add_field'`	✅
objectName	`string`	✅	Target object name
fieldName	`string`	✅	Name of the field to add
field	`{ name?: string; label?: string; type: Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| … +42 more>; description?: string; … }`	✅	Full field definition to add

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this change set
name	`string`	✅	Human readable name for the migration
description	`string`	optional	Detailed description of what this migration does
author	`string`	optional	Author who created this migration
createdAt	`string`	optional	ISO 8601 timestamp when the migration was created
dependencies	`{ migrationId: string; package?: string }[]`	optional	Migrations that must run before this one
operations	`({ type: 'add_field'; objectName: string; fieldName: string; field: object } \| { type: 'modify_field'; objectName: string; fieldName: string; changes: Record<string, any> } \| { type: 'remove_field'; objectName: string; fieldName: string } \| { type: 'create_object'; object: object } \| … +3 more)[]`	✅	Ordered list of atomic migration operations
rollback	`({ type: 'add_field'; objectName: string; fieldName: string; field: object } \| { type: 'modify_field'; objectName: string; fieldName: string; changes: Record<string, any> } \| { type: 'remove_field'; objectName: string; fieldName: string } \| { type: 'create_object'; object: object } \| … +3 more)[]`	optional	Operations to reverse this migration

Property	Type	Required	Description
type	`'create_object'`	✅
object	`{ name: string; label?: string; pluralLabel?: string; description?: string; … }`	✅	Full object definition to create

Property	Type	Required	Description
id	`string`	✅	Migration id (e.g. adr-0104-file-references) — one row per data migration
last_run_at	`string`	✅	When this migration last completed a gated (apply-mode) run on this deployment
verified_at	`string \| null`	optional	When the self-check last PASSED. Null/absent until it does — and cleared again by a later failing run, so a regression closes the gate
applied_at	`string \| null`	optional	When the backfill last ran in apply mode (writes enabled)
blocking	`integer`	✅	Blocking discrepancies reported by the last self-check. The gate requires 0
advisory	`integer`	optional	Advisory findings from the last run (external URLs, stale owners, …) — cost storage or need a modelling decision, never block the gate
details	`string`	optional	JSON-encoded counts from the last run, for diagnostics
deviation_observed_at	`string \| null`	optional	When this deployment last ADMITTED a value the verified contract rejects, via an OS_ALLOW_LAX_* escape hatch. Does not clear verified_at — it withdraws the irreversible half of what the certificate authorises (#4797)
deviation_detail	`string \| null`	optional	JSON-encoded first counterexample behind deviation_observed_at (object, field, type, parse issue), for diagnostics

On this page