Migrations
How schema.json maps onto a live database: create, validate-only, and additive alter.
weave migrate is the only thing that emits DDL. It's safe by construction: it will create
tables, but it never alters or drops your columns behind your back.
For each object it checks whether a table with that name already exists:
- No table → it creates one from the schema.
- Table exists → it only validates that every declared field is a real column, and emits zero
DDL. A declared field with no matching column aborts with
object.field.columnMissing. "alter": true(top-level inschema.json) → the object opts into additive-only DDL: ADD COLUMN, ADD CONSTRAINT, ADD FK, CREATE INDEX. Column types are never altered and columns are never dropped. A missing primary-key column still aborts.
Because DDL is additive-only, removing a field never drops its column. Delete the field from
schema.json and the database column and its data stay intact; the API stops exposing it, and writes
to it are rejected as an unknown field. To actually drop a column, run your own SQL
(ALTER TABLE ... DROP COLUMN). Re-adding a field with the same name but a different type doesn't
change the column type either — the diff only checks that a column with that name exists.
weave dev applies the same rules on hot-reload and commits schema changes to Git (see
Git-versioned metadata). A change that would touch a read-only
existing table rejects the reload, keeps the running engine on the previous schema, and emits a
schema.drift event.
To see exactly how a schema maps to its live database — each field's expected column, type,
constraints, and any drift — run weave schema:map (CLI reference).
Atomic deploys & schema revisions
weave deploy apply (and weave migrate) commit the DDL, the metadata cache and a global schema
revision in one transaction — an advisory lock serializes concurrent deploys, and any failure
rolls the whole thing back, so Git, PostgreSQL and the metadata cache can never drift apart. Each
apply records a revision in weavekit_schema_revision, keyed on a deterministic aggregate hash of
the schema files; re-applying an unchanged schema writes no new revision. weave deploy plan
previews the changes (read-only) with a schema-impact analysis (added columns/constraints/indexes,
data-compatibility risk, RBAC/scope impact, API-breaking flag), the live schema revision, and a
config-drift flag when the on-disk schema differs from the last applied revision.
Before a deploy — especially against a new or existing database — run weave doctor, a read-only
preflight (connection, PostgreSQL compatibility, schema/DB drift, engine system tables, RLS + sandbox)
that exits non-zero on any failure. weave migrate --preflight runs it first.
Where engine tables live
Besides your objects, weave migrate provisions the engine's own tables: the weavekit_* system
tables (metadata cache, sequence counters, audit, approvals, workflow, evidence, counters), the
weavekit_record__<object> metadata side tables and the weavekit_m2m__* link tables.
By default they are created in the object schema (the connection's current_schema()), alongside
your tables. Set EngineConfig.systemSchema (e.g. "weavekit") to keep them in a dedicated
schema instead — useful when a DBA reviews the customer schema and does not want engine plumbing in
it. When set:
weave migratecreates the schema and qualifies every engine table into it; your object tables stay in the object schema.- the runtime appends the schema to the connection's existing
search_path, so its unqualified engine-table references resolve to the dedicated schema while your tables keep resolving through the object schema (a non-publicobject schema set on the connection — URLoptions, role default orPGOPTIONS— is preserved).
This applies to new databases. For an existing install, move the engine tables yourself
(ALTER TABLE <name> SET SCHEMA <systemSchema>) — the engine does not migrate their location.
Related
- Fields & types
- RBAC
- Git-versioned metadata — where migrations come from
- CLI reference —
weave deploy plan|apply,weave doctor