V2 migrations¶
TypeBridge V2 migrations move a declared Split-YAML schema through an ordered, binding-neutral history. Generated Python, TypeScript, and Rust packages are projections of the resulting schema; they are not migration authority.
Configure the workspace¶
format: typebridge.workspace/v1
schema:
root: schema/schema.yaml
ownership: exclusive
managed-scope: application
migrations:
directory: migrations/v2
app-label: application
destructive: require-approval
bindings:
python:
output: generated/python/app_models
environments:
development:
database: application
uri: localhost:1729
tls: 'false'
migrate: 'true'
credential:
username: env:TYPEDB_USERNAME
password: env:TYPEDB_PASSWORD
migration make and migration plan are offline. Connected commands resolve
one named environment and enforce its migrate policy. TypeDB-backed
migration apply, migration verify, migration rollback --execute,
migration adopt, and migration upgrade-profile run only on these
profile/server pairs: workspace semantic profile typedb-3.12.1/v1 with a
negotiated TypeDB 3.12.3+ server, or typedb-3.13.6/v1 with TypeDB 3.13.6+ or
3.14.0+ and newer lines. Here, + admits later patches on the same minor
line. Newer lines reuse the newest measured profile and protocol assumptions
and warn once per connection that they are
"not tested or supported by this TypeBridge release". No compatibility is
guaranteed. Older profiles still reject other server lines. General version
admission requires >=3.11.0; supported lines remain the measured 3.11–3.14.
Offline authoring remains available for supported semantic profiles.
Author and apply a change¶
type-bridge --manifest typebridge.yaml schema check
type-bridge --manifest typebridge.yaml schema generate
type-bridge --manifest typebridge.yaml migration make --name add-person
type-bridge --manifest typebridge.yaml migration plan
type-bridge --manifest typebridge.yaml migration apply --environment development
type-bridge --manifest typebridge.yaml migration verify --environment development
Review the committed migration and preview before applying. When the workspace requires approval for destructive changes, approve the exact compound migration identity:
type-bridge --manifest typebridge.yaml migration apply \
--environment production \
--approve application/0002_remove-old-field
Generation is deliberately separate from migration application and never contacts TypeDB. It emits every configured binding from one captured workspace, and each package privately embeds the verified authority needed by its managers and query sessions. Ordinary applications need no standalone authority JSON; generated packages remain projections rather than migration or authoring authority.
State authority¶
For managed database NAME, TypeBridge owns a companion journal database named
NAME__tbv2_journal. Reserve that suffix. Back up, restore, clone, and delete
the managed database and journal together.
The journal is bootstrapped only when its exact owner, control schema, and
managed scope can be established. A partial/foreign journal, wrong owner,
missing manifest, checksum drift, or schema-fingerprint mismatch fails closed.
migration verify is read-only and never creates a database.
The committed history, declared-schema fingerprint, journal head, and live managed schema form one state triad. Apply advances them under a lease and execution journal so interruption can be diagnosed and retried without silently skipping a step.
Safety and replay¶
Each migration has a stable identity, exact parents, checksum, normalized operations, safety classification, and resulting declared schema. A clean database can replay the committed V2 chain without importing the current application package.
Use expand/backfill/contract as separate migrations when data must move:
- expand the schema so old and new facts coexist;
- backfill through a reviewed binding-neutral operation or application job bound to the intermediate generated projection;
- verify the backfill;
- contract the old schema in a separately approved migration.
Do not place target-language callbacks or model declarations in new migration authority. Application data jobs use generated bindings for the exact intermediate schema and are coordinated explicitly around migration apply.
Adopt a frozen V1 history¶
Existing root Python/JSON migration histories are recovery inputs, not active writers. Quiesce the old migrator and revoke its write authority before the one-way cutover:
type-bridge --manifest typebridge.yaml migration adopt \
--environment production \
--archive-directory path/to/frozen-history
The adopter requires bounded regular files and verifies dependencies, original
source/sidecar checksums, snapshots, metadata, and the applied ledger. It
reconstructs the independently verified head, compares it with the live managed
schema, and publishes an archive-frontier genesis plus zero-operation bridge.
It never executes archived RunPython callbacks.
Adoption is idempotent for the same exact authority and rejects drift or a
competing canonical publisher. After it succeeds, continue only with V2
make/plan/apply/verify commands.
The retained Python loader, checksum, snapshot metadata, state reader, and sidecar converter are read-only recovery components. They cannot author a new root history, update an applied ledger, or write a historical snapshot.
Move a history to a new TypeDB line¶
A migration history is bound to the semantic profile it was authored on. A
typedb-3.13.6/v1 history moves between TypeDB 3.13.6 and 3.14.0 without a
bridge, since both lines share that profile. To continue a typedb-3.12.1/v1
history on TypeDB 3.13.6 or 3.14.0, record one profile
bridge per history:
- Quiesce writers and move the managed database and its migration journal
(
<database>__tbv2_journal) to the 3.13.6 server with TypeDB's owndatabase exportanddatabase import. - Set the workspace profile in
typebridge.yaml:
- Point the environment at the new server and run, once per environment:
type-bridge --manifest typebridge.yaml migration upgrade-profile \
--environment production --to typedb-3.13.6/v1
- Commit the new bridge manifest and continue with
migration makeandmigration applyas usual.
Until the bridge exists, make, plan, apply, and verify refuse the
older history with migration_history_profile_upgrade_required and print the
command above. --to must equal the workspace profile, be a supported
migration profile, and be newer than the history's profile; anything else is
refused before credentials are read or files are written.
The command writes a zero-operation bridge manifest named like migration make
names migrations (0004_profile_upgrade_typedb_3_13_6.tbmigration.json;
--name replaces the descriptive part). Then it connects and records the
bridge in the ledger. Recording requires the ledger to stand at the history
head and the live schema to equal that head's schema; out-of-band changes are
refused with migration_upgrade_profile_live_drift. A second run reports the
bridge as already recorded. Once the committed bridge exists, other moved
environments can also catch up with an ordinary migration apply.
New environments on the newer server need no export. migration apply into
an empty database on 3.13.6 replays the whole bridged history: the 3.12.1
migrations before the bridge are lowered and verified under their own
profile, the bridge switches the recorded state to typedb-3.13.6/v1, and the
later migrations apply as usual. Every step is checked as in any other apply,
and the ledger records each migration. Older-profile migrations replay only as
ancestors of a bridge to the server's profile; without such a bridge they are
refused.
The bridge is one-way. A history crosses at most one bridge, and rollback
refuses the bridge and every migration before it
(migration_rollback_profile_bridge); returning to 3.12 needs a database
restored on the old server.
Historical TOML¶
TOML desired-schema authoring is not a migration path. Convert an immutable
historical TOML document with type_bridge_core.toml_to_typeql, review its
meaning, express the target in Split-YAML, and use the V2 flow above. See
TOML recovery.
CI acceptance¶
For every migration change, test:
- offline check/make/plan determinism;
- apply and verify against a clean database;
- interruption/retry and lease behavior;
- destructive approval rejection and acceptance;
- full replay from empty;
- archive adoption followed by a new V2 migration when recovery changes;
- generated package regeneration and application operation parity.
See schema workflows, schema commands, and the Split-YAML reference.