Plan schema changes

A schema change can affect stored records, indexes, foreign keys, application validation, and the queries that use a field. Treat every change as a data migration, even when it looks small.

Changing a table's schema requires an organization owner or admin, or another cloud user with access to the site.

Protect stored data

• Affected resource and cascade: Type, constraint, key, and foreign-key changes can change stored values, indexes, relationships, and the application code that uses the table.
• Reversibility: Removing a field or narrowing a type can discard data that a later change can't bring back.
• Authorization: Requires an organization owner or admin, or another cloud user with access to the site.
• Backup or export: Export the table's data before the change: open the table's menu in Datatables and select Export data.
• Confirmation: Confirm the site, app, table, and the complete new schema before you send it.
• Success response and postcondition: The update returns 200, and Definition shows the new schema.
• Recovery: There is no undo. Restore by updating the schema again and importing the exported data.

Classify the change

Change	Typical effect	Review before applying
Add an optional field	Existing rows can remain unchanged	New application fallback and backfill plan
Add a required field	Existing rows need a valid value	Backfill before enforcing the constraint
Increase a text bound	Usually widens accepted data	Client validation and index impact
Reduce a bound or numeric range	Existing values can become invalid	Data scan and remediation
Change a field type	Values may require conversion	Conversion query, rejected values, and recovery
Rename a field	Queries and payloads must move together	Compatibility window or dual-read strategy
Remove a field	Stored values are discarded	Export, dependency search, and retention approval
Add or change a foreign key	Existing values must resolve	Referenced table, deletion action, and load order
Change a primary key	Record URLs and relationships change	Treat as a new-table migration

Prepare the change

1. Export the table's data.
2. Search your application code, jobs, dashboards, policies, and event subscribers for every field you are changing.
3. Count the existing records that would break the new schema.
4. Write down the new schema, how you will check it, and how you will undo it.
5. Try the change in a development app with representative data.
6. Pick a quiet time if the change could block writes.

Apply the change

Send the complete updated schema — every field, not only the changed ones — as json_schema:

curl -sS -X PATCH "${TARUVI_SITE_URL}/api/apps/APP_SLUG/datatables/TABLE_NAME/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @updated-schema.json

updated-schema.json contains {"json_schema": {...}} with the full descriptor. See the schema reference for its format. Apply one change at a time.

Verify the result

After the change:

1. Confirm is_materialized is true for the table.
2. In Definition, compare every field, key, constraint, and foreign key with the schema you sent.
3. Create and read a record through each interface your application uses.
4. Check that an invalid record, such as one missing a required value, is rejected.
5. Repeat your allowed and denied access checks for the changed fields.
6. Check your jobs and event subscribers before releasing application code.

Change in stages

Prefer small, compatible steps:

1. Add the new field as optional.
2. Release code that writes both the old and new fields.
3. Backfill existing records and check them.
4. Switch reads to the new field.
5. Make the new field required, if needed.
6. Once nothing uses the old field, take it out of the schema.

Each step keeps your application working, so you can stop or roll back between them.

Continue with:

• Manage tables
• Plan indexes
• Database reliability