> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Incorporating database changes with schema refreshes

> Trigger manual or scheduled schema refreshes to keep your Omni model in sync when database tables, columns, or schemas change.

export const XCircleIcon = ({label}) => {
  return <span>
      <Icon icon="circle-xmark" iconType="solid" color="#ff2465" />
      {label && ` ${label}`}
    </span>;
};

export const CheckIcon = ({label}) => {
  return <span>
      <Icon icon="circle-check" iconType="solid" color="#26bd6c" />
      {label && ` ${label}`}
    </span>;
};

When your database schema changes — new tables, renamed columns, removed schemas — your Omni model can fall out of sync. Run a schema refresh to tell Omni about those changes.

## Requirements

To trigger schema refreshes, you'll need **Modeler** or **Connection Admin** permissions:

* **Modelers** can perform schema refreshes on connections with exactly **one** shared model
* **Connection Admins** can refresh schemas on any connection they are an admin of, whether the connection has one or multiple models

<Note>
  Refreshes to multi-model connections affect every shared model on the connection, so they can only be triggered by Connection Admins.
</Note>

## Types of schema refreshes

There are two types of schema refreshes: hard and soft.

| Type             | What's refreshed?                           | What's reflected in Omni?                                                                                                                                        |
| ---------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hard refresh** | Entire model (all schemas and tables)       | **All** changes: <br /><br /><CheckIcon label="New objects" /><br /><CheckIcon label="Updated objects" /><br /><CheckIcon label="Removed objects" />             |
| **Soft refresh** | Entire model or specific schemas and tables | **Additive** changes only: <br /><br /><CheckIcon label="New objects" /><br /><CheckIcon label="Updated objects" /><br /><XCircleIcon label="Removed objects" /> |

## Triggering schema refreshes

Schema refreshes can be triggered manually or automated on a schedule. Kicking off a refresh starts a background job that can take several minutes depending on the size of the database.

### Manually

Schema refreshes can be triggered on an as-needed basis from the model IDE, from a connection's settings page, or with the API.

<AccordionGroup>
  <Accordion title="In the IDE" icon="code">
    <Steps>
      <Step title="Open the model IDE" noAnchor>
        Navigate to the model IDE.
      </Step>

      <Step title="Open the refresh schema dialog" noAnchor>
        Click **Model > Refresh schema**.
      </Step>

      <Step title="Choose hard or soft refresh" noAnchor>
        * **Hard refresh** of the entire model: leave the schema and table fields blank.
        * **Soft refresh** of specific schemas and tables: add the objects you want to refresh, individually or with wildcard syntax (e.g., `sales_*`).
      </Step>

      <Step title="Trigger the refresh" noAnchor>
        Click **Refresh schema**.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="In the connection's settings" icon="database">
    <Steps>
      <Step title="Open the connection settings" noAnchor>
        Navigate to **Settings > Connections** and open the connection.
      </Step>

      <Step title="Open the refresh schema dialog" noAnchor>
        Click **Refresh now**.
      </Step>

      <Step title="Choose hard or soft refresh" noAnchor>
        * **Hard refresh** of the entire model: leave the schema and table fields blank.
        * **Soft refresh** of specific schemas and tables: add the objects you want to refresh, individually or with wildcard syntax (e.g., `sales_*`).
      </Step>

      <Step title="Trigger the refresh" noAnchor>
        Click **Refresh schema**.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="With the API" icon="cloud">
    Use the [Refresh schema endpoint](/api/models/refresh-schema) to manually trigger a refresh.
  </Accordion>
</AccordionGroup>

### On a schedule

<Note>
  Scheduled refreshes don't currently support selectively refreshing schemas and tables.
</Note>

Use scheduled refreshes to automatically pull database changes into your Omni model. You can create refresh schedules in Omni on a connection's settings page or with the API.

<AccordionGroup>
  <Accordion title="In the connection's settings" icon="database">
    <Steps>
      <Step title="Open the connection settings" noAnchor>
        Navigate to **Settings > Connections** and open the connection.
      </Step>

      <Step title="Open the refresh schedule dialog" noAnchor>
        Click **Create schedule**.
      </Step>

      <Step title="Define the schedule" noAnchor>
        Enter a cron string to define the schedule.

        <Tip>
          Omni uses Amazon Web Services (AWS) syntax for cron expressions. Refer to the [AWS documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) for more information and examples.
        </Tip>

        If your organization has [AI enabled](/ai/settings/features), you can use the AI cron generator to create cron expressions from natural language. Click the sparkle icon next to the cron input field and describe your desired schedule, such as "every day at 6am" or "every Monday and Thursday at midnight."
      </Step>

      <Step title="Choose hard or soft refresh" noAnchor>
        **Optional**. By default, scheduled refreshes perform soft refreshes. Check the **Hard refresh** option to create a schedule that discards the existing schema model and rebuilds it from scratch.
      </Step>

      <Step title="Create the schedule" noAnchor>
        Click **Schedule**.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="With the API" icon="cloud">
    Use the [Create schema refresh schedule endpoint](/api/schema-refresh-schedules/create-schema-refresh-schedule) to programmatically create a schedule, and the [Update schema refresh schedule](/api/schema-refresh-schedules/update-schema-refresh-schedule) to modify it.
  </Accordion>
</AccordionGroup>

## Requiring branches for schema refreshes

If you prefer to review schema changes before they impact the shared model, enable the connection's **Branch based schema refresh** setting. This will force schema refreshes to be performed in an [Omni branch](/content/develop/branch-mode) before they can be promoted to the shared model.

When this setting is enabled:

* **On-demand and scheduled refreshes will be disabled**
* **Schema refreshes can only be triggered from the IDE**. If you're not in an existing branch, selecting **Model > Refresh schema** will prompt you to create a branch first.

<Note>
  Branch-based schema refreshes can't be enabled if a connection has multiple models or if connection environments ([dynamic connections](/connect-data/dynamic-environments)) are currently in use.
</Note>

## Resolving broken references

Changes made as a result of a schema refresh may result in broken references in Omni. Use the [Content Validator](/modeling/develop/content-validator) to identify and resolve any issues. If you need to update references after renaming tables in your database, use [table migration](/modeling/develop/table-migration).