# Database Migration Scripts in the Plane Repository: Location and Usage Guide

> Find database migration scripts in the makeplane/plane repository. Learn their location and how to use them for your project. Essential guide for developers.

- Repository: [Plane/plane](https://github.com/makeplane/plane)
- Tags: how-to-guide
- Published: 2026-06-25

---

**Yes, the makeplane/plane repository contains extensive database migration scripts organized within Django's standard `migrations` directories, specifically under `apps/api/plane/db/migrations` and `apps/api/plane/license/migrations`.**

The open-source project management tool **Plane** is built on the **Django** framework, which relies on Python-based database migration scripts to manage schema evolution. These scripts ensure that the PostgreSQL database structure remains consistent across development environments and production deployments by versioning every structural change from initial table creation through field alterations.

## Where Database Migration Scripts Are Located in Plane

Plane organizes its database migration scripts following Django's convention of placing a `migrations` package inside each Django app. The repository contains two primary locations where these schema evolution files reside.

### Core Data Model Migrations (`apps/api/plane/db/migrations`)

The main application logic resides in `apps/api/plane/db/migrations`, which contains sequentially numbered Python modules ranging from [`0001_initial.py`](https://github.com/makeplane/plane/blob/main/0001_initial.py) to [`0121_alter_estimate_type.py`](https://github.com/makeplane/plane/blob/main/0121_alter_estimate_type.py) and beyond. These files handle the complete lifecycle of Plane's data models, including the creation of tables for users, projects, issues, and comments, as well as subsequent schema adjustments like adding new columns, indexes, and renaming fields.

### License Subsystem Migrations (`apps/api/plane/license/migrations`)

The licensing infrastructure maintains its own migration history in `apps/api/plane/license/migrations`. This directory includes files such as [`0001_initial.py`](https://github.com/makeplane/plane/blob/main/0001_initial.py) and [`0006_instance_is_current_version_deprecated.py`](https://github.com/makeplane/plane/blob/main/0006_instance_is_current_version_deprecated.py), which manage the schema for product licensing, instance tracking, and version deprecation markers.

## Anatomy of Plane's Database Migration Scripts

Each database migration script in the Plane repository follows Django's standard `Migration` class pattern. These Python modules define a `dependencies` list to ensure proper execution order and an `operations` list containing the specific schema changes.

In [`apps/api/plane/db/migrations/0001_initial.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/db/migrations/0001_initial.py), the migration structure appears as follows:

```python
from django.db import migrations, models

class Migration(migrations.Migration):
    initial = True

    dependencies = []

    operations = [
        migrations.CreateModel(
            name='User',
            fields=[ … ],
        ),
        # … more CreateModel / AddField / AlterField ops …

    ]

```

When the Django management command processes these scripts, it reads the `operations` list and applies each transformation atomically to ensure database consistency.

## Running Database Migration Scripts in Plane

Developers interact with Plane's database migration scripts through Django's [`manage.py`](https://github.com/makeplane/plane/blob/main/manage.py) command-line interface. The standard workflow involves applying pending migrations to update the database schema.

To apply all pending database migration scripts:

```bash
python manage.py migrate

```

To apply migrations for a specific app only:

```bash
python manage.py migrate plane

```

To view the migration history and check which scripts have been applied:

```bash
python manage.py showmigrations plane

```

When modifying models in [`models.py`](https://github.com/makeplane/plane/blob/main/models.py), generate a new migration script using:

```bash
python manage.py makemigrations plane

```

This command creates a new numbered Python file in the appropriate `migrations` directory containing the auto-detected schema changes.

For development rollback scenarios, you can revert to a specific migration version by targeting its sequence number:

```bash
python manage.py migrate plane 0120

```

This command rolls back any migrations applied after `0120` in the `plane` app.

## Notable Database Migration Scripts in the Repository

Understanding specific examples from the Plane codebase demonstrates how the project manages schema evolution over time.

**[`apps/api/plane/db/migrations/0001_initial.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/db/migrations/0001_initial.py)** establishes the foundational tables for the entire application, creating the initial schema for users, workspaces, and projects when Plane is first deployed.

**[`apps/api/plane/db/migrations/0121_alter_estimate_type.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/db/migrations/0121_alter_estimate_type.py)** demonstrates a mid-project schema change, modifying the `estimate` field to utilize a new enumeration type as requirements evolved.

**[`apps/api/plane/db/migrations/0109_issuecomment_description_and_parent_id.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/db/migrations/0109_issuecomment_description_and_parent_id.py)** shows incremental feature development, adding `description` and `parent_id` columns to the `IssueComment` model to support nested comment threads.

**[`apps/api/plane/license/migrations/0001_initial.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/license/migrations/0001_initial.py)** and **[`apps/api/plane/license/migrations/0006_instance_is_current_version_deprecated.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/license/migrations/0006_instance_is_current_version_deprecated.py)** handle the licensing subsystem's evolution, from initial table creation to marking legacy license instances as deprecated.

## Summary

- **Plane** uses Django's migration framework to manage database schema evolution through Python-based database migration scripts.
- Core migrations reside in `apps/api/plane/db/migrations`, while licensing migrations are stored in `apps/api/plane/license/migrations`.
- Migration files follow a sequential numbering pattern (e.g., [`0001_initial.py`](https://github.com/makeplane/plane/blob/main/0001_initial.py), [`0121_alter_estimate_type.py`](https://github.com/makeplane/plane/blob/main/0121_alter_estimate_type.py)) and contain `Migration` classes with `dependencies` and `operations`.
- Use `python manage.py migrate` to apply scripts and `python manage.py makemigrations` to generate new ones after model changes.
- Rolling back to specific versions is supported via `python manage.py migrate <app_name> <migration_number>`.

## Frequently Asked Questions

### How does Plane automatically discover database migration scripts?

Django's migration framework automatically discovers database migration scripts by scanning the `migrations` package within each installed app. When `manage.py migrate` executes, Django reads the migration files in sequence, checks the `dependencies` defined in each `Migration` class, and determines which operations have not yet been applied to the target database by comparing against the `django_migrations` table.

### Can database migration scripts in Plane be manually edited?

While developers typically allow Django to auto-generate database migration scripts via `makemigrations`, manual editing is sometimes necessary for complex schema changes that require data migrations or custom SQL. In the Plane repository, developers should exercise caution when editing existing migration files, as altering already-applied migrations can cause environment inconsistencies; instead, creating new migrations is the standard practice for production deployments.

### What happens if a database migration script fails during deployment in Plane?

If a database migration script fails during execution, Django's transaction handling rolls back any partial changes within that specific migration, maintaining database integrity according to the atomicity guarantees provided by PostgreSQL. The deployment will halt with an error message indicating which operation in the migration file caused the failure, allowing developers to fix the underlying issue or adjust the migration logic before retrying the `migrate` command.