Programmatic API
You can run schema sync from your own code using the syncSchema convenience function or the SchemaSync class directly. This is useful for application startup, custom deployment scripts, and CI/CD integration.
Quick Start
The simplest way to sync your schema:
import { DbSpace } from "@atscript/db";
import { syncSchema } from "@atscript/db/sync";
import { User, Post, Comment } from "./schema/index.as.js";
const db = new DbSpace(adapterFactory);
const result = await syncSchema(db, [User, Post, Comment]);
console.log(result.status); // 'up-to-date' | 'synced' | 'failed' | 'synced-by-peer' | 'refused'syncSchema is a one-liner that creates a SchemaSync instance and calls run(). It handles locking, hashing, diffing, and DDL execution in a single call.
SchemaSync Class
For more control, use the SchemaSync class directly. It provides separate plan() and run() methods:
import { SchemaSync } from "@atscript/db/sync";
const sync = new SchemaSync(db);
// Plan first — see what would change without applying
const plan = await sync.plan(types);
console.log(plan.status); // 'up-to-date' | 'changes-needed'
for (const entry of plan.entries) {
console.log(entry.name, entry.status, entry.destructive);
}
// Then run — apply changes with distributed locking
const result = await sync.run(types, { force: true, safe: false });
console.log(result.status); // 'up-to-date' | 'synced' | 'failed' | 'synced-by-peer' | 'refused'The constructor accepts an optional logger:
const sync = new SchemaSync(db, console);TSyncOptions
Options for both syncSchema() and sync.run():
| Option | Type | Default | Description |
|---|---|---|---|
force | boolean | false | Ignore hash check, always introspect the database |
safe | boolean | false | Skip destructive operations (column drops, table drops) |
podId | string | Random UUID | Identifier for distributed locking |
lockTtlMs | number | 30000 | Lock time-to-live in milliseconds (auto-extended while sync runs) |
waitTimeoutMs | number | 60000 | Max wait time for another pod's lock |
pollIntervalMs | number | 500 | Poll interval when waiting for lock release |
logger | TGenericLogger | NoopLogger | Logger for sync progress and failures (see below) |
dataSteps | TDataStep[] | — | One-time data steps run after the DDL, or before the constraints with phase: "beforeConstraints" (since 0.1.165 / 0.1.168, see Data steps) |
The plan() method accepts only force, safe and dataSteps.
Pass a logger in production
Index and FK sync failures (e.g. a unique index over data that already contains duplicates) do not throw — they are logged, recorded on the entry (status: 'error', errors: [...]), and the schema hash is not persisted so the next boot retries. With the default NoopLogger those log lines go nowhere. Pass { logger: console } to syncSchema() (or new SchemaSync(db, console)) so they surface, or inspect result.entries for errored tables after every run.
TSyncPlan
Returned by sync.plan():
interface TSyncPlan {
status: "up-to-date" | "changes-needed";
schemaHash: string;
entries: SyncEntry[];
pendingDataSteps?: string[]; // since 0.1.165, when dataSteps were passed
}When status is 'up-to-date', the entries still list all tables/views (normally 'in-sync') — useful for displaying a full schema overview. The safe option is honoured here too (since 0.1.128): a table or view that an earlier safe run retained shows as a pending drop unless safe is set.
TSyncResult
Returned by sync.run() and syncSchema():
interface TSyncResult {
status: "up-to-date" | "synced" | "failed" | "synced-by-peer" | "refused";
schemaHash: string;
entries: SyncEntry[];
// since 0.1.165, when dataSteps were passed; notes and failed since 0.1.175
dataSteps?: {
ran: string[];
pending: string[];
notes?: Record<string, string>; // by step id — present when a step returned a note
failed?: Array<{ id: string; error: unknown }>; // onError: "warn" steps that failed
};
}| Status | Meaning |
|---|---|
'up-to-date' | Schema hash matched, no sync needed |
'synced' | This process applied changes, every entry landed |
'failed' | This process ran the sync, but at least one entry is an error entry (its DDL failed, or a constraint the stored rows break was not created): the other entries are applied, the hash is withheld and the next sync retries (since 0.1.170; before, 'synced') |
'synced-by-peer' | Another process completed sync while this one was waiting for the lock (never for a force run) |
'refused' | Pre-flight refused the run (since 0.1.128): no DDL ran, nothing was persisted, the lock was released. entries is the full plan; refused entries are error entries with refused: true |
'failed' and 'refused' follow the onError policy like error entries do — "warn" (default) logs each refusal at error level and returns, "throw" throws after the lock is released, "silent" returns. plan() reports the same refusals with its status unchanged ('changes-needed').
Data steps
Schema sync changes structure only — it never backfills existing rows (a new @db.default applies to new rows). For a one-time data change that belongs to a schema change, pass it as a data step (since 0.1.165):
await syncSchema(db, types, {
dataSteps: [
{
id: "2026-10-users-tier", // stable and unique — the step is recorded under it
async run(space) {
await space.getTable(User).updateMany({ tier: null }, { tier: 3 });
},
},
],
});- Steps run in order, after the DDL, under the sync lock — also when the schema itself is up to date, so a step added later runs on the next sync.
- Each step runs once per database: it runs in its own transaction (on adapters with transactions), together with its record in
__atscript_control(data_step:<id>). A step that throws is rolled back and not recorded; the sync throws its error after releasing the lock, the steps after it stay pending, and the next sync runs it again. - The record is insert-only and is written before the step, in the same transaction. If another sync took over an expired lock and recorded the step first, the step does not run again: the sync logs a warning and the step is in neither
rannorpending. Without transactions (the in-memory adapter, MongoDB without a replica set) the record is checked right before the step and written right after it; a step that another sync records while it runs here runs on both, and a warning says so. - Steps do not run when the sync is
'refused'or an entry errored. result.dataStepsreports{ ran, pending }:ranlists the steps this call ran,pendingthe steps still not recorded after it — the ones a later sync runs. A step an earlier sync recorded is in neither list, sopendingis empty once every step has run (also on an'up-to-date'or'synced-by-peer'result).plan()reports the samependinglist aspendingDataSteps, and a pending step makes the plan'changes-needed'.- Never change what a recorded step does — add a new step with a new id. Duplicate or empty ids throw.
Step notes
A step can return { note } (since 0.1.175) to keep a short record of what it did — which rows it merged, which users it raised:
{
id: "2026-11-raise-limits",
async run(space) {
const { modifiedCount } = await space.getTable(User).updateMany({ limit: 5 }, { limit: 10 });
return { note: `raised ${modifiedCount} users` };
},
}- The note is stored with the step's record in
__atscript_control(data_step:<id>, a JSON value{ ranAt, podId, note }), in the same transaction as the step. result.dataSteps.notesholds the notes of the steps this call ran, by step id.- A note is kept up to 4096 characters; a longer one is cut and ends in
… [truncated].
Continue after a failed step
By default a failing step stops the run. With onError: "warn" (since 0.1.175) the sync logs the error and goes on with the next step:
{
id: "2026-11-merge-legacy-tags",
onError: "warn",
async run(space) {
await mergeLegacyTags(space); // may fail on data nobody has cleaned up yet
},
}- The failed step is rolled back (on adapters with transactions) and not recorded, so the next sync runs it again. Without transactions its writes so far stay — write such a step so it can run again.
- The error is logged through the sync's
logger(consolewhen none is set) and listed inresult.dataSteps.failedas{ id, error }; the step stays inpending. - The steps after it run and are recorded without it. Use
"warn"only for a step no later step depends on. "throw"is the default."warn"on abeforeConstraintsstep throws when the sync starts: the indexes and foreign keys after it need its work.
Fix rows before a new constraint
A new @db.index.unique or @db.rel.FK cannot be created over rows that break it, and a default step runs after the DDL — too late to merge the duplicates first. Give the step phase: "beforeConstraints" (since 0.1.168):
await syncSchema(db, types, {
dataSteps: [
{
id: "2026-11-merge-duplicate-codes",
phase: "beforeConstraints",
async run(space) {
// the tables and their new columns exist; the new unique index does not yet
await mergeDuplicateCodes(space.getTable(Product));
},
},
],
});- A
beforeConstraintsstep runs after every table and its new columns exist, before any table's indexes and foreign keys are synced; views are not synced yet either. - All
beforeConstraintssteps run before the"after"(default) ones. When the schema is already up to date they simply run first. - A
beforeConstraintsstep that throws (rolled back, not recorded) stops the run there. What the run already applied — renamed and created tables, new columns — is recorded; every table still waiting for its indexes and foreign keys gets anerrorentry (Data step "<id>" failed: …), views are not synced (a view this run dropped to change it stays dropped), removed tables are not dropped, and the schema hash is withheld. The sync then throws the step's error after releasing the lock. The next sync picks up from there: it runs the step again and applies the constraints and views. A renamed table is not renamed twice: when the old name is gone and the new one exists, the adapters treat the rename as done. - On SQLite a new foreign key rebuilds the table during the DDL, before the step runs — the rows are copied with foreign-key checks off, and SQLite never checks existing rows against a new constraint. Dangling references survive that rebuild, so clear them in the step anyway. The step still runs before the new unique indexes. Other values of
phasethrow.
Rewrite stored rows after a type change
Tightening a type does not touch the rows already stored. Lower @expect.maxLength on a @db.json array from 50 to 20, and the old rows still hold 50 items: they read fine, but the next update of such a row fails validation. rewriteRowsStep (since 0.1.175) builds a data step that brings the stored rows in line:
import { rewriteRowsStep, syncSchema } from "@atscript/db/sync";
await syncSchema(db, types, {
dataSteps: [
// keep the last 20 turns of every stored chat
rewriteRowsStep(Chat, { field: "turns", map: (turns) => turns.slice(-20) }),
],
});- The id follows the validation rules. It is
rewrite:<table>.<field>@<hash>, where the hash covers what decides which values are valid: the field's kind and primitive type, optional / nullable, the structure of objects and arrays by property name, and the@expect.*(their messages excluded),@meta.required,@normalize.*and@db.jsonannotations. When you change the limit again, the hash changes, the step is pending again and the next sync runs it once more. Renaming a nested type, labels, descriptions,@ui.*, other annotations and upgrading@atscript/typescriptdo not change it. Passidto choose the part before@— change it to run the step again after changingmap. mapmust be idempotent, so thatmap(map(x))equalsmap(x). The step runs again when its id changes, and after a failed attempt on an adapter without transactions the retry sees the rows the first attempt already rewrote. A clamp (turns.slice(-20)) or a trim is idempotent;v => v * 100is not and corrupts the data on a rerun. Derive the new value from other fields, or guard it:v => (v < 1000 ? v * 100 : v).- Not a key, not a relation.
fieldcannot be a primary-key column (the patch would address the wrong row) or a relation; the step refuses it when you create it. fieldform:map(value, row)returns the field's new value;undefinedleaves the row as it is. A dottedfieldreaches into a nested object.- Whole-row form: without
field,map(row)returns the row with your changes and the hash covers every column of the table, so adding or removing a column (or changing a column's validation) runs the step again. Top-level fields left out of the result are not changed; the primary key never is. - It reads the rows in primary-key order,
batchSize(default 500) at a time, and writes only the rowsmapchanged, as a patch validated against the current type. A rowmapleaves invalid fails the step: it is rolled back (on adapters with transactions) and runs again on the next sync. - The note it stores says how many rows it rewrote.
phaseandonErrorare passed through to the step.
The rewrite runs at sync, once per type change — not at read time. There are no read hooks that fix values on the way out on purpose: filters, sorts, aggregates and exports run in the database on the stored values, so a value fixed only when read would still be found, sorted and counted by its stored form.
SyncEntry
Each entry in the plan/result represents a table or view:
interface SyncEntry {
name: string;
status: "create" | "alter" | "drop" | "in-sync" | "error";
viewType?: "V" | "M" | "E"; // V=virtual, M=materialized, E=external
// Plan fields — what will change
columnsToAdd: TDbFieldMeta[];
columnsToRename: Array<{ from: string; to: string }>;
typeChanges: Array<{ column: string; fromType: string; toType: string; waitsFor?: string[] }>; // waitsFor (since 0.1.173): removed tables safe mode keeps that still reference the column — the change is skipped ('retype')
nullableChanges: Array<{ column: string; toNullable: boolean }>;
defaultChanges: Array<{ column: string; oldDefault?: string; newDefault?: string }>;
columnsToDrop: string[];
optionChanges: Array<{ key: string; oldValue: string; newValue: string; destructive: boolean }>;
fkAdded: Array<{ fields: string[]; targetTable: string }>;
fkRemoved: Array<{ fields: string[]; targetTable: string }>;
fkChanged: Array<{ fields: string[]; targetTable: string; details: string }>;
// Result fields — what was applied
columnsAdded: string[];
columnsRenamed: string[];
columnsDropped: string[];
recreated: boolean;
errors: string[];
renamedFrom?: string;
// Since 0.1.128
pkChange?: { from: string[]; to: string[]; rebuild: boolean; populated?: boolean }; // primary-key field set change; rebuild=false when safe mode skipped it; populated=true when the table has rows (since 0.1.155)
dependsOn: string[]; // tables and views this entry's DDL waits for (FK parents / view sources / referencing children of a drop)
dropGroup?: string[]; // set when a foreign-key cycle is dropped as one group
refused: boolean; // this `error` entry is a pre-flight refusal — no DDL ran
skipped: ReadonlyArray<
"pk-rebuild" | "recreate" | "table-options" | "nullable-defaults" | "derived" | "retype"
>; // work safe mode skipped ('derived' since 0.1.141, 'retype' since 0.1.173)
toInit(): TSyncEntryInit; // the init object, for deriving a modified copy
// Since 0.1.141
derivedChanges: Array<{
column: string;
reason: "kind" | "expression" | "type";
derived: boolean;
}>; // derived-column rebuilds (drop + add)
cascadeFrom: string[]; // upstream views whose recreation recreates this unchanged view
// Since 0.1.162
definitionChanged: boolean; // a managed view whose own definition changed (the reason it is recreated)
indexChanges: Array<{ name: string; action: "add" | "drop" | "rebuild" }>; // managed index work on an existing table: planned (plan) or done (run); empty for a created or recreated table
// Computed properties
destructive: boolean; // involves drops, type changes, recreation, or a primary-key rebuild
hasChanges: boolean; // status is not 'in-sync' or 'error'
hasErrors: boolean; // status is 'error' or errors array is non-empty
pending: boolean; // (since 0.1.128) desired work not applied — an `error` entry (not an external view) or non-empty `skipped`
}Entries come back in execution order — tables parents-first, then views, then drops children-first — identically from plan() and run(). Safe mode is reported identically as well: a skipped primary-key rebuild is pkChange: { from, to, rebuild: false } in both (printed ! PK … — skipped (safe mode), not destructive). What each skipped value means and why a pending entry withholds its snapshot and the schema hash is covered in Safe Mode.
Plan-Then-Decide Pattern
Use plan() to inspect changes before deciding whether to apply:
const sync = new SchemaSync(db);
const plan = await sync.plan(types);
if (plan.status === "up-to-date") {
console.log("Nothing to do");
return;
}
// Check for destructive changes
const hasDestructive = plan.entries.some((e) => e.destructive);
if (hasDestructive) {
console.log("Destructive changes detected:");
for (const entry of plan.entries.filter((e) => e.destructive)) {
console.log(` ${entry.name}: ${entry.status}`);
for (const col of entry.columnsToDrop) {
console.log(` - drop column: ${col}`);
}
}
// Require explicit approval in production
if (!approved) return;
}
// Apply with force to skip hash check (we already know changes are needed)
const result = await sync.run(types, { force: true });Integration with Application Startup
A common pattern is to sync on startup in development and skip in production:
const db = new DbSpace(adapterFactory);
if (process.env.NODE_ENV !== "production") {
const { syncSchema } = await import("@atscript/db/sync");
await syncSchema(db, allTypes);
}The hash check makes this very cheap when nothing has changed — only a lightweight control table read occurs, skipping all schema introspection and DDL.
Error Handling
Sync can fail for several reasons:
try {
await syncSchema(db, types);
} catch (error) {
if (error.message.includes("lock wait timed out")) {
// Another process holds the lock and didn't release in time
// Increase waitTimeoutMs or investigate the other process
}
if (error.message.includes("lock was stolen")) {
// Another pod took over the lock mid-sync — the current sync aborted safely.
// Usually transient (network partition recovery). Retry or rely on `synced-by-peer`.
}
// Other errors: DB connection issues (also while taking the lock), DDL failures
}Schema-level errors don't throw — they appear as entries with status: 'error' and populated errors arrays: rename conflicts, type changes without a sync method and, since 0.1.129, any DDL the engine refuses inside a table's step (<phase> failed on <table>: … — the run completes and the other tables are persisted; see What triggers error status). What still rejects run() is what happens outside a table's DDL: lock problems, a connection failure, an error during discovery.
Error entries have retry semantics: the schema hash and the errored table's snapshot are not persisted, so the next run() (or application boot) attempts the same changes again instead of reporting 'up-to-date' over a diverged schema. Once the underlying conflict is resolved (data cleaned up, annotation fixed), the retry converges and the hash settles:
const result = await syncSchema(db, types);
const failed = result.entries.filter((e) => e.hasErrors);
for (const entry of failed) {
console.error(`${entry.name}: ${entry.errors.join("; ")}`);
}
// failed entries re-attempt on every subsequent run until they succeedPrinting the Plan
SyncEntry instances render themselves to coloured terminal output via entry.print(mode, colors?) — mode is 'plan' (preview) or 'result' (after run()). It returns an array of lines you can console.log directly:
const plan = await sync.plan(types);
for (const entry of plan.entries) {
for (const line of entry.print("plan")) {
console.log(line);
}
}Pass a colour adapter (matching the TSyncColors shape — green/red/cyan/yellow/bold/dim/underline) as the second argument to control styling. Omit it for plain text output suitable for logs.
A 'result' entry with status alter lists every change the run applied. Since 0.1.162 that includes in-place type, nullability and default changes and foreign keys, which earlier releases recorded only on plan entries (or when safe mode skipped them):
~ invoices — altered
~ amount: DOUBLE → decimal — type changed
~ amount — default 0.00 → 0
+ FK(teamId) → teams — addedAn alter entry is never printed as — in sync. A foreign key that is only added makes the run entry alter too, as the plan already reported. A managed view whose own definition changed prints · definition changed, and its entry has definitionChanged: true.
Syncing a module namespace
A compiled .as module exports more than its tables — helper interfaces, @db.alias types, plain type aliases. isDbEntityType (from @atscript/db, since 0.1.141) keeps only what a DbSpace accepts: types whose own declaration carries @db.table, @db.view or @db.view.for. A plain export type Admin = User is User itself (since @atscript/typescript 0.2), so it passes too; the sync lists and hashes each type once, however many export names it has. It turns a namespace into an inventory:
import { isDbEntityType } from "@atscript/db";
import * as models from "./schema/index.as.js";
await syncSchema(db, Object.values(models).filter(isDbEntityType));A @db.alias type in the list is skipped by the sync itself; any other non-entity type would be synced as a table named after its type id, so filter first. The generated model manifest applies the same selection at build time.
Exported Utilities
The @atscript/db/sync sub-entry exports the building blocks used by the CLI:
| Export | Purpose |
|---|---|
SchemaSync | Full sync class with plan() and run() |
SyncEntry | Plan/result entry with print() and computed flags |
syncSchema() | One-liner convenience: new SchemaSync(db).run(types) |
rewriteRowsStep() | A data step that rewrites stored rows when a type changes (since 0.1.175) — see Rewrite stored rows |
Lower-level diff/snapshot helpers are also exported for building custom dashboards or sync UIs — consult the package source if you need them.
Next Steps
- CI/CD Integration — deployment strategies and pipeline examples
- What Gets Synced — detailed change categories
- How Sync Works — architecture and internals