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

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 to 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 and 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, the migration structure appears as follows:

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 command-line interface. The standard workflow involves applying pending migrations to update the database schema.

To apply all pending database migration scripts:

python manage.py migrate

To apply migrations for a specific app only:

python manage.py migrate plane

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

python manage.py showmigrations plane

When modifying models in models.py, generate a new migration script using:

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:

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 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 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 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 and 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}