---
title: "Managing Schema Migrations"
description: "Schema migrations allow you to track changes to your database structure over time and apply those changes to your live database. This is a critical process for keeping your database definition in s..."
last_updated: "2026-07-02T09:37:14.189696+00:00"
canonical_url: "https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/how-to-guides/managing-schema-migrations"
---

Schema migrations allow you to track changes to your database structure over time and apply those changes to your live database. This is a critical process for keeping your database definition in sync with your application requirements.

There are two primary ways to manage these changes: **Generating Migration Files** (for version control) and **Pushing Changes** (for direct, immediate updates).

## Generating Migration Files

Generating migration files creates a historical record of your schema changes. These files contain the SQL statements required to transition your database from one state to another.

1. **Detect Changes**: When you update your application schema, the system compares your current schema against the last known state.
2. **Review Conflicts**: If the system detects ambiguous changes (like renaming a table or moving an entity between schemas), you will be prompted to resolve these conflicts manually.
3. **Generate Files**: Once resolved, the system saves the SQL statements and a snapshot of your current schema to your project. This ensures you can track every evolution of your database.

> [!TIP]
> Use this method if you are working in a team or want to maintain a history of your database changes in your version control system.

## Pushing Changes Directly

If you prefer not to manage individual migration files, you can use the "push" feature to synchronize your database directly.

1. **Introspection**: The system inspects your live database to understand its current structure.
2. **Comparison**: It compares your current application schema against the database state.
3. **Execution**: It calculates the necessary changes and attempts to apply them immediately.

> [!WARNING]
> Pushing changes directly can be destructive. If the system detects operations that might cause data loss (like removing a table or a column), it will pause and prompt for explicit confirmation. Always review these warnings carefully.

## Key Concepts

| Concept | Description |
| :--- | :--- |
| **Introspection** | The process of reading the live database structure to detect how it currently looks. |
| **Snapshot** | A JSON representation of your database structure used to track changes over time. |
| **Journal** | A log file that records the history of applied migrations in order. |
| **Data Loss Warning** | An alert shown when an operation might delete existing data, requiring user approval. |

## Workflow Overview

```mermaid
graph LR
    A[Update Schema] --> B{Choose Workflow}
    B -->|Version Control| C[Generate Migration Files]
    B -->|Fast Sync| D[Push Changes Directly]
    C --> E[Store SQL in Project]
    D --> F[Execute on Database]
```

## Important Considerations

> [!IMPORTANT]
> Always keep backups of your database. While the system identifies potential data-loss operations, it is impossible to predict all scenarios, especially in complex environments.

> [!NOTE]
> If you are using platforms like Expo or React Native, look for the bundle option, which helps package your migration files into a single file for easier deployment.

> [!CAUTION]
> Avoid performing manual changes directly on your database if you are using migrations. Changes made outside the system will conflict with the tool's records, potentially causing errors during future migrations.

## Related

- [Configuration File Reference](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/configuration/configuration-file-reference)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/llms.txt) for all pages in this wiki.