Schema deployment and migrations

A schema deployment updates the project’s data model and what Studio shows. In a project whose schema is managed in the app, each change the agent proposes and you approve in the chat is a deployment. In a project managed from code, flexkit deploy is what makes a config change visible. Either way the deployment is recorded with who started it; see flexkit deployments.

Many deployments are the second half of a question you could not answer yet: add the field or relationship, deploy, then backfill. The design loop is in iterating your schema.

Safe change workflow

For a schema managed in the app, read the agent’s review card before approving: it lists every entity and attribute that is added, changed or removed, and flags breaking changes. For larger changes, try them in a test project first.

For a schema managed from code:

1. Commit the current configuration and identify the target project.
2. Export and validate the data you need using the public CLI.
3. Develop the change in a disposable project first.
4. Run CLI deploy, inspect validation and completion, and stop if it fails.
5. Reload the Studio and check representative reads and writes in Desk and Explorer.
6. Backfill or start writing any new fields.

Breaking changes

Removing an entity or attribute and changing a data type can cause validation errors or data loss. Follow the specific schema error guide rather than forcing deployment blindly.

For a type migration, prefer adding a new field, transforming and checking data, updating consumers, and only then retiring the old field through the supported removal process. Test relationships and scoped values as well as simple scalar values.

Reverting code does not restore removed data. An export must be validated for its actual contents before you rely on it for recovery. Inspect deployment for application and tool rollout checks.