Skip to main content
This page needs to be completed with best practices from the Forest team.
When you add a table, rename a column, or change a relationship in your database, Forest needs to learn about those changes. This page explains how schema synchronization works and how to handle common scenarios.

​
What is the schema?

Forest introspects your database at startup and builds an internal representation of your data model, the schema. This schema drives everything: which collections appear, what fields are available, and how relationships are represented. For self-hosted back-ends, the schema is also saved to a local file called .forestadmin-schema.json. This file acts as a cache and allows Forest to detect changes between restarts.

​
Automatic schema detection

For self-hosted back-ends, schema updates are detected automatically on back-end restart. When your back-end starts up:
  1. It connects to your database and introspects the current schema
  2. It compares the result with .forestadmin-schema.json (if it exists)
  3. If changes are detected, it updates the file and notifies the Forest cloud
This means the typical workflow for a database change is: 
# 1. Make your database change (migration, ALTER TABLE, etc.)
# 2. Restart your agent
npm run start
# 3. The new fields/tables appear in Forest automatically
During development, back-ends often restart on file change (via nodemon or similar). Schema changes show up immediately.

​
Cloud Back-end schema sync

For Forest Cloud (where Forest manages the back-end), you trigger schema synchronization manually from the UI:
  1. Go to Project Settings → Environments
  2. Click on the environment you want to sync
  3. In the Back-end section, click Synchronize schema
Forest will connect to your database and pull the latest schema. New tables and columns will appear in your back-office. You can also trigger a sync from the quick access icon in the left navigation bar.

​
The .forestadmin-schema.json file

This file is auto-generated and lives in your project root. It contains a snapshot of your data model as Forest sees it. Do:
  • Commit it to your repository, it ensures schema consistency across team members and environments
  • Review changes in pull requests to catch unexpected schema drift
Don’t:
  • Edit it manually, changes will be overwritten on the next back-end start
  • Delete it unless troubleshooting, the back-end will regenerate it, but this forces a full re-introspection

​
Common scenarios

​
Adding a new table

After running your database migration:
  1. Restart your back-end
  2. The new table appears as a new collection in Forest
  3. Configure its layout and permissions as needed

​
Adding a new column

After adding a column to an existing table:
  1. Restart your back-end
  2. The new field appears in the collection’s configuration
  3. It’s hidden by default, enable it in the Layout Editor if needed

​
Renaming a column

Renaming a column is treated as removing the old field and adding a new one. This means:
  • Any widget configuration, segments, or actions referencing the old name will break
  • You’ll need to update your Forest configuration to reference the new name
To minimize disruption, consider adding a database view or alias that preserves the old column name temporarily.

​
Removing a column

After dropping a column from your database and restarting your back-end, the field disappears from Forest. If it was referenced in segments, actions, or custom code, you’ll see errors, clean those up first.

​
Changing a column type

Type changes may cause widget incompatibilities (e.g. a field that was a String and is now a JSON object). After the schema update, review the field’s widget configuration and update it if needed.

​
Troubleshooting

​
New fields aren’t appearing

  • Confirm your database migration ran successfully
  • Restart your back-end (a running back-end doesn’t auto-detect database changes)
  • Check your back-end logs for introspection errors

​
Schema conflict errors

If the back-end reports a schema conflict, it means the .forestadmin-schema.json file is out of sync with the current database. Delete the file and restart the back-end to regenerate it from scratch.

​
Missing relationships

Relationships are inferred from foreign keys in the database. If a relationship isn’t showing up:
  • Verify the foreign key constraint exists in the database
  • If you’re using a non-standard naming convention, you may need to declare the relationship explicitly in your back-end configuration
See Relationships for how to define relationships in code.

​
Best practices

  • Run migrations before deploying back-end changes, the back-end should start against the already-migrated database
  • Test schema changes in a development branch, use Environments & branches to validate layout impact before hitting production
  • Commit .forestadmin-schema.json, keeps all team members on the same schema version
  • Review the schema diff in PRs, catching an unintended table rename in review is much easier than debugging it in production