Does changing a field type in SurrealDB convert existing records?

Field type changed in place

Warning: the statement succeeds, then writes fail, access changes, or the table is held up.

What happens

Observed on SurrealDB 3.0.2: a record stored with age = 'twelve' keeps that value after DEFINE FIELD OVERWRITE age ON person TYPE int, and its next write fails with "Couldn't coerce value for field `age`". INFO FOR TABLE shows the DEFAULT and ASSERT the old definition had are gone.

Why it is dangerous on a populated table

SurrealDB checks a schema change against new writes, not the records already stored, so an empty table hides it: on a populated one every old record is a write waiting to fail, and whole-table work runs for the length of the table in one transaction.

Fires on

DEFINE FIELD OVERWRITE age ON TABLE person TYPE int;

The safe pattern

DEFINE FIELD age_years ON TABLE person TYPE option<int>;
-- batched job: UPDATE person SET age_years = <int> age WHERE age_years IS NONE AND ...;
-- later migration: REMOVE FIELD age ON TABLE person;

Fixtures

The rule ships with these files and the test suite runs them on every change: the first set must fire, the second must stay silent.

ALTER FIELD age ON TABLE person TYPE int;

DEFINE FIELD OVERWRITE age ON TABLE person TYPE int;

DEFINE FIELD age_years ON TABLE person TYPE option<int>;

DEFINE TABLE person SCHEMAFULL;
ALTER FIELD age ON TABLE person TYPE int;

DEFINE FIELD OVERWRITE age ON TABLE person TYPE any COMMENT 'years';

How to check locally

npx bolvrk check migration.surql --engine=surrealdb