Schema changes

Editing a class in rayfin/data/ does not change anything by itself — Rayfin only reads your entities and generates Data API Builder (DAB) configuration when you explicitly apply it. This page covers the commands that do that, and how to verify the apply actually took effect.

rayfin up is the canonical command

npx rayfin up is the command to reach for any time you want your latest entity changes live on your deployed Fabric app. It is not schema-only: it syncs runtime settings, applies the database schema generated from your rayfin/data decorators, and builds and deploys static content if staticHosting is enabled, all in one step. Run it after every change to a file under rayfin/data/.

npx rayfin up

Running it again after the first deploy updates the same deployment rather than creating a new one, so it is safe to run repeatedly as you iterate.

rayfin up db apply: the schema-only escape hatch

npx rayfin up db apply generates and applies only the database schema, without touching runtime settings or static content. It is an advanced subcommand — reach for it when you specifically want to push a schema change without re-running the full rayfin up flow (for example, while iterating locally with npm run dev serving your frontend and the backend already deployed).

npx rayfin up db apply

If the change could cause data loss — dropping a column, narrowing a type, renaming a table — the CLI blocks it and explains what it found. Add --force once you have reviewed the listed operations and accept the loss:

npx rayfin up db apply --force

Verify the change actually reached the server

npx rayfin up status

Add --json for machine-readable output, useful in a script that waits for a healthy deployment before running further checks:

npx rayfin up status --json

Typical workflow

# 1. Edit rayfin/data/Todo.ts, add a field or a new entity

# 2. Apply the change
npx rayfin up

# 3. Verify the deployment is healthy
npx rayfin up status

# 4. If a new entity errors at runtime despite a successful deploy, apply schema explicitly
npx rayfin up db apply --force

Troubleshooting

GraphQL returns "Internal server error" after a successful deploy — check every @text() field on the affected entity for a missing max. On MSSQL, @text() without max generates an NVARCHAR(MAX) column, which can break GraphQL schema generation. Add explicit max values (see Field types) and redeploy with npx rayfin up db apply --force.

rayfin up db apply reports a potentially destructive change — review the listed operations (dropped columns, narrowed types, renamed tables). Re-run with --force only once you have confirmed the data loss is acceptable.

rayfin up db apply fails outright — wait for services to report healthy (rayfin up status) before retrying.

Enabling data without a dialect — rayfin.yml requires dialect: mssql whenever services.data.enabled is true. Omitting it causes a 400 error at apply time.