Skip to content

docs(cli): document os migrate + dev autoMigrate self-heal (#2186 follow-up)#2205

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xuyushun441-sys merged 1 commit into from
Jun 22, 2026
Merged

docs(cli): document os migrate + dev autoMigrate self-heal (#2186 follow-up) #2205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions content/docs/getting-started/cli.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -419,6 +419,49 @@ os info --json # JSON output for tooling
Loaded in 90ms
```

### Schema migrations

The metadata→database sync is **additive-only**: on boot it creates missing
tables and adds new columns, but never alters or drops existing ones. So a
*non-additive* change to an object already backed by a database — relaxing
`required` (drop `NOT NULL`), changing a field's type/length, or removing a
field — silently diverges from the live schema, and the physical column wins at
write time. `os migrate` reconciles the database to the metadata (the source of
truth).

| Command | Description |
|---------|-------------|
| `os migrate plan` | Dry-run: show how the database has drifted from metadata, categorised safe / needs-confirm / destructive (no changes applied) |
| `os migrate apply` | Reconcile the database to metadata. Applies loosening changes; destructive ones require `--allow-destructive` |

```bash
os migrate plan # Preview drift (no changes)
os migrate apply # Apply safe (loosening) changes, with a confirm prompt
os migrate apply --yes # Skip the prompt (CI / scripts)
os migrate apply --allow-destructive --yes # Also drop orphaned columns, tighten NOT NULL, narrow types
os migrate plan --json # Machine-readable output
```

| Category | Examples | Applied by |
|----------|----------|------------|
| `safe` | relax `NOT NULL` → nullable, widen a `varchar` | `os migrate apply` (and dev auto-reconcile) |
| `needs_confirm` | non-narrowing type change | `os migrate apply` |
| `destructive` | drop an orphaned column, tighten `NOT NULL`, narrow a type | `os migrate apply --allow-destructive` |

<Callout type="tip">
**Dev self-heal.** `os dev` runs the SQL driver with `autoMigrate: 'safe'`, so
loosening changes (e.g. you just made a field optional) are applied to your
existing dev database automatically on restart — no `os migrate` needed, no data
loss. Auto-reconcile is **dev-only and never destructive**; it is force-disabled
under `NODE_ENV=production`, where you run `os migrate` deliberately.
</Callout>

<Callout type="warn">
`os migrate` only sees objects in your **compiled artifact** — run `os build`
first. It never drops a table that is absent from your metadata, and on SQLite
it reconciles via a table rebuild (copy → swap) that preserves your data.
</Callout>

### Scaffolding

| Command | Alias | Description |
Expand Down
21 changes: 21 additions & 0 deletions skills/objectstack-data/SKILL.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -260,6 +260,27 @@ export default ObjectSchema.create({

---

## Schema evolution on an existing database

The metadata→DB sync is **additive-only**: new tables/columns are created on
boot, but existing columns are **never** altered or dropped. A non-additive
change to an object that already has data silently diverges from the physical
schema, and the **database column wins at write time** (#2186):

| Change | Existing DB on restart |
|--------|------------------------|
| add object / field / index | ✅ applied automatically (additive) |
| `required: true → false` (relax `NOT NULL`) | dev auto-heals (`autoMigrate:'safe'`); otherwise `os migrate apply` |
| type / length change, drop field, rename | `os migrate apply` (`--allow-destructive` for drops / tightenings) |

Tell-tale: `/meta` reports a field optional but a write still 400s
`"<field> is required"` — that is a stale `NOT NULL` column (physical drift),
**not** a validator bug. `os dev` reconciles loosening automatically; otherwise
`os migrate plan` to preview and `os migrate apply` to reconcile. CLI details:
see **objectstack-platform**.

---

## Common Patterns

### Naming Rules Summary
Expand Down
2 changes: 2 additions & 0 deletions skills/objectstack-platform/SKILL.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -563,6 +563,8 @@ cd my-app && pnpm install
os dev --ui # dev server + Studio (auto-hops port if taken)
os validate # metadata cross-reference checks
os compile # produce dist/ artifact
os migrate plan # preview metadata↔DB schema drift (additive sync never alters existing columns)
os migrate apply # reconcile DB to metadata (loosening only; --allow-destructive for drops/tightenings)
PORT=8080 os start # production — pin the port explicitly (see Ports & networking)
```

Expand Down