How I Turned a Month-Long Migration Into a Weekend Project (And You Can Too)

Look, I'm going to level with you. Database migrations are the kind of work that makes developers contemplate career changes. You know the drill: weeks of mapping fields, writing transformation scripts, testing, breaking things, fixing things, breaking them again in a slightly different way.

But what if I told you there's a better way? A way that involves AI doing the tedious stuff while you review JSON files and sip coffee?

Directus is magic, and I'm about to show you why.

The Problem: Legacy Data, New Home

Picture this: You've got a legacy CMS database. Hundreds of tables. Thousands of fields. Relationships nested inside relationships like some kind of relational matryoshka doll situation. Your job? Get all that data into a modern platform without losing your sanity or your data integrity.

Traditional approach:

1. Manually map every table (2-3 weeks)

2. Write transformation scripts (1-2 weeks)

3. Test, break things, cry, repeat (1-2 weeks)

4. Actually run the migration and pray (1 week)

Total time: 5-8 weeks, give or take a few existential crises.

The "Wait, That Actually Worked?" Approach

Here's what I did instead:

Step 1: Install Directus on the Existing Database

This is the part that sounds scary but is actually just... chef's kiss. Directus can sit on top of any existing SQL database and just... work with it. No ETL required for the raw data. The tables are already there; we just need Directus to understand them.

# Point Directus at the existing database
# Tables exist, data exists, we're just adding Directus metadata
npm init directus-project

# Point Directus at the existing database
# Tables exist, data exists, we're just adding Directus metadata
npm init directus-project

# Point Directus at the existing database
# Tables exist, data exists, we're just adding Directus metadata
npm init directus-project

At this point, Directus sees your tables but doesn't know what to do with them. It's like adopting a cat that doesn't know where the litter box is yet.

Step 2: Let AI Do the Boring Stuff

Here's where it gets interesting. I enabled the Directus MCP (Model Context Protocol) server and connected it to Claude CLI. Suddenly, the AI could actually see my database structure. Not just read a schema dump—actually inspect collections, relationships, and data patterns.

The conversation went something like this:

Me: "Hey, analyze the relationships in this database" AI: "I found 47 many-to-one relationships, 23 many-to-many junctions, and 15 polymorphic dynamic zone configurations. Want me to generate mapping files?" Me: "...yes please"

No more manually clicking through admin panels. No more squinting at foreign keys. The AI could query Directus directly and understand the full picture.

Step 3: Generate, Review, Apply

The AI helped me create a system of mapping files—JSON configurations that define how every collection, field, and relationship should be configured:

{
  "mappings": [
    {
      "collection": "articles",
      "directus_singular": "Article",
      "directus_plural": "Articles",
      "folder": "content",
      "icon": "article",
      "status": "auto_generated"
    }
  ]
}

{
  "mappings": [
    {
      "collection": "articles",
      "directus_singular": "Article",
      "directus_plural": "Articles",
      "folder": "content",
      "icon": "article",
      "status": "auto_generated"
    }
  ]
}

{
  "mappings": [
    {
      "collection": "articles",
      "directus_singular": "Article",
      "directus_plural": "Articles",
      "folder": "content",
      "icon": "article",
      "status": "auto_generated"
    }
  ]
}

The beauty of this approach? Human review before anything changes.

Every mapping starts as auto_generated. I review it, maybe tweak the icon or folder assignment, then mark it user_confirmed. The scripts only apply confirmed configurations.

It's like having a very enthusiastic junior dev who does all the grunt work but always runs the important decisions by you first.

Step 4: Iterate Until It Works

Here's the honest part: it didn't work perfectly the first time. Or the second time. The AI suggested some relationship configurations that were... creative. A few junction table names that made sense only if you squinted.

But here's the thing, because everything was in JSON mapping files and SDK scripts, fixing issues was trivial:

1. Find the bad mapping

2. Edit JSON

3. Re-run the script

4. Done

No database rollbacks. No "let me undo the last 47 manual changes." Just edit, run, verify.

# Dry-run first (always dry-run first)
node 35-create-m2o-relations.mjs d

# Looks good? Apply it
node 35-create-m2o-relations.mjs a

# Dry-run first (always dry-run first)
node 35-create-m2o-relations.mjs d

# Looks good? Apply it
node 35-create-m2o-relations.mjs a

# Dry-run first (always dry-run first)
node 35-create-m2o-relations.mjs d

# Looks good? Apply it
node 35-create-m2o-relations.mjs a

The Numbers (Because We're All Adults Here)

Traditional migration approach:

• Time: 5-8 weeks

• Repeatability: "Please don't make me do this again"

• Error recovery: Expensive

MCP + LLM + SDK Scripts approach:

• Time: 2-3 days

• Repeatability: Run the same scripts on any environment

• Error recovery: Edit JSON, re-run

I'm not saying this turned me into a 10x developer. I'm saying it let me work on interesting problems instead of playing table-mapping whack-a-mole for a month.

The Secret Sauce: Controllable AI

I want to be clear about something: this isn't "let the AI do everything and hope for the best." That's how you end up with a database that thinks user_id should relate to the vegetables table.

The pattern that works:

1. AI generates initial mappings by analyzing actual data structures

2. Human reviews each configuration via interactive CLI

3. Scripts apply only confirmed changes

4. Dry-run mode lets you preview before committing

# Interactive review with full control
node 00-collection-mappings-1-review.mjs

# [y]es / [n]o / [e]dit / [s]kip / [a]ll / [q]uit
# Your decision, every time

# Interactive review with full control
node 00-collection-mappings-1-review.mjs

# [y]es / [n]o / [e]dit / [s]kip / [a]ll / [q]uit
# Your decision, every time

# Interactive review with full control
node 00-collection-mappings-1-review.mjs

# [y]es / [n]o / [e]dit / [s]kip / [a]ll / [q]uit
# Your decision, every time

The AI is like a very fast research assistant. It proposes. You dispose (or approve).

Why This Matters

Every migration project has the same skeleton:

• Collections to configure

• Relationships to define

• Fields to map

• Permissions to set up

The specifics change, maybe you're coming from a different CMS, or a custom Rails app, or that Access database someone built in 2003 and everyone's been too scared to touch since.

The approach stays the same:

1. Let Directus sit on the existing database

2. Use MCP + LLM to analyze and generate configurations

3. Review everything in human-readable JSON

4. Apply with scripts that support dry-run mode

What You Need

• Directus (obviously)

• Directus MCP Server

• Claude (or any LLM with MCP support)

• A healthy respect for the d (dry-run) flag

The Part Where I Admit This Isn't Perfect

Look, I'm not going to pretend this is a magic wand. (Okay, it's kind of a magic wand, but a responsible one.)

Things that still require human brains:

• Business logic decisions (what should this relationship be?)

• Permission configurations (who should access what?)

• Edge cases the AI doesn't understand

• That one table named temp_backup_final_v2_FIXED that nobody remembers creating

The AI accelerates. It doesn't replace your judgment.

Go Forth and Migrate

If you're staring down a database migration and considering whether to fake your own death, maybe try this first:

1. Install Directus on your existing database

2. Connect MCP and ask the AI what it sees

3. Generate some mapping files

4. Review them like the responsible adult you are

5. Run the scripts

6. Take the rest of the month off (or, you know, work on something actually interesting)

The data stays where it is. Directus learns to manage it. You get to keep your sanity.

That's the magic.

Got questions? Ran into something weird? Drop into our Community Forum or open an issue. We've seen some things. We can help.

And if you try this approach and it saves you weeks of work? Tell us about it. We live for that stuff.

Happy migrating!

🐰