> ## Documentation Index
> Fetch the complete documentation index at: https://forest-chore-open-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema updates

> Keep your Forest back-office in sync when your database schema changes.

<Note>This page needs to be completed with best practices from the Forest team.</Note>

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:

```bash theme={null}
# 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
```

<Info>
  During development, back-ends often restart on file change (via nodemon or similar). Schema changes show up immediately.
</Info>

## 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](/product/build/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](/product/process/relationships/overview) 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](/product/process/advanced-concepts/developer-workflow/environments-and-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