OrchardCore Data Migration

This skill guides you through writing OrchardCore data migrations following project conventions.

A data migration is a class that inherits DataMigration. OrchardCore discovers its methods by reflection and runs them sequentially, per tenant, on application start. The chain starts at CreateAsync() and continues through UpdateFrom1Async(), UpdateFrom2Async(), … Each method returns the schema version number the next method must match.

When to use a migration

• Define or alter content types / parts / fields (IContentDefinitionManager).
• Create or alter SQL index tables (SchemaBuilder).
• Patch existing content item data (query + ISession.SaveAsync).
• Run a setup recipe at install/upgrade (IRecipeMigrator).
• Seed roles, settings, or other documents.

The version-chain rule (read first)

The migration runner stores the last returned number per migration class per tenant. It then calls the method whose name matches: returned 4 → runs UpdateFrom4Async(). The method's return value is the new stored version.

Migration Workflow

Step 1: Create the Migrations class

Place Migrations.cs in the module root (or a Migrations/ subfolder for multiple classes, e.g. Migrations/PermissionMigrations.cs).

using OrchardCore.ContentManagement.Metadata;
using OrchardCore.Data.Migration;

namespace YourModule;

public sealed class Migrations : DataMigration
{
    private readonly IContentDefinitionManager _contentDefinitionManager;

    public Migrations(IContentDefinitionManager contentDefinitionManager)
    {
        _contentDefinitionManager = contentDefinitionManager;
    }

    public async Task<int> CreateAsync()
    {
        // ... define schema ...

        // Return the latest version so new installs skip every UpdateFromX.
        return 1;
    }
}

SchemaBuilder is injected by the base class — do not add it as a constructor parameter.

Step 2: Register the migration

In the module Startup.cs:

services.AddDataMigration<Migrations>();

Register each migration class separately if the module has more than one.

Step 3: Write the initial CreateAsync

Return the highest version your module currently ships. Example (content part):

public async Task<int> CreateAsync()
{
    await _contentDefinitionManager.AlterPartDefinitionAsync("TitlePart", builder => builder
        .Attachable()
        .WithDescription("Provides a Title for your content item."));

    // Shortcut other migration steps on new content definition schemas.
    return 2;
}

Step 4: Add UpdateFromX for each shipped change

When you change the schema in a release, append a new UpdateFromXAsync — never edit a prior one. Bump the number CreateAsync returns to match.

// This code can be removed in a later version.
public async Task<int> UpdateFrom1Async()
{
    await SchemaBuilder.AlterIndexTableAsync<LinkFieldIndex>(table => table
        .AddColumn<string>("BigUrl", column => column.Nullable().Unlimited()));

    return 2;
}

Step 5: Test the migration

1. Fresh install — run on a clean tenant; only CreateAsync executes, schema lands at the latest version.
2. Upgrade — start from a DB at the previous version; confirm each UpdateFromX runs in order.
3. Test on every targeted provider (SQLite, SQL Server, MySQL, PostgreSQL). SQLite cannot drop columns — guard with try/catch (see references/schema-builder.md).

Method signatures

Static or instance, sync or async — all supported. Async (...Async) is the convention for new code.

Quick Reference

Common operations

Type definition builder methods

Gotchas

• Always set column length on string index columns (.WithLength(n)) or .Unlimited() — unlengthed columns fail on some providers.
• CreateAsync should return the latest version, not 1, once UpdateFromX methods exist.
• Patch loops must page by DocumentId and call FlushAsync() periodically (see references/patterns.md).
• Mark obsolete UpdateFromX methods with // This code can be removed in a later version. but keep them until you drop support for that upgrade path.

References

• references/patterns.md — content definition changes, content-item data patching, recipe migrations
• references/schema-builder.md — index tables, columns, indexes, provider quirks
• src/docs/reference/modules/Migrations/README.md (repo) — official reference
• AGENTS.md (repo root) — build commands