Migrating Metabase Content Between Instances: A Production-Ready Solution for Data Teams

Overview

Migrating Metabase dashboards, questions, and collections between instances is notoriously difficult due to database ID mismatches, permission complexities, and broken references. The Metabase Migration Toolkit is an open-source Python tool that automates this process with intelligent ID remapping, dependency resolution, and conflict handling — saving data teams hours of manual work and preventing costly migration errors.

Why Metabase Migrations Are Harder Than They Should Be

If you’ve ever tried to migrate Metabase content between environments — say, from staging to production, or from an old instance to a new one — you know the pain. What should be a straightforward export and import operation quickly becomes a nightmare of broken dashboards, missing questions, and cryptic 403 errors.

Here’s what typically goes wrong: You export a dashboard from your source instance, import it into your target instance, and everything looks fine. But when users try to view it, they see data from the wrong database, or worse, no data at all. The problem? Metabase uses internal IDs for databases, tables, and fields — and these IDs are different across instances. A table called customers might be ID 42 in your source instance but ID 87 in your target instance. Your carefully crafted questions are now querying the wrong tables entirely.

Then there are the permissions. After migration, users suddenly can’t access the dashboards they should have access to. Collections appear empty. The permission groups you painstakingly configured don’t exist on the new instance. You’re left manually recreating permissions for hundreds of users, hoping you remember who had access to what.

For data teams managing multiple Metabase instances across development, staging, and production environments — or organizations consolidating analytics platforms — this isn’t just annoying. It’s a blocker that can delay critical migrations by days or weeks.

What is Metabase Migration Toolkit?

The Metabase Migration Toolkit is an open-source Python package that solves these migration challenges with a production-ready, automated approach. Think of it as infrastructure as code for your Metabase analytics — you can version, backup, and deploy your entire analytics stack just like you do with application code.

Built by data engineers who’ve felt this pain firsthand, the toolkit handles the complex ID remapping, dependency resolution, and permission migration that make Metabase migrations so challenging. It’s not a quick script or a hacky workaround — it’s a thoroughly tested, well-documented tool designed to handle real-world scenarios with thousands of dashboards and questions.

The toolkit provides two command-line tools: metabase-export for extracting content from a source instance, and metabase-import for recreating that content on a target instance. Between these two steps, it intelligently maps database IDs, table IDs, field IDs, and permissions to ensure everything works correctly in the new environment.

Key Features That Set It Apart

• Intelligent ID Remapping: Automatically remaps database, table, and field IDs — the critical feature that prevents “wrong data” bugs that plague manual migrations




• Recursive Dependency Resolution: Automatically includes all dependent questions when exporting a dashboard, preventing broken references




• Permissions Migration: Exports and imports permission groups and access control settings, eliminating post-migration 403 errors




• Conflict Resolution Strategies: Choose how to handle existing content — skip duplicates, overwrite with new versions, or rename to avoid conflicts




• Dry-Run Mode: Preview exactly what will be created, updated, or skipped before making any changes to your production instance




• Collection Hierarchy Preservation: Maintains your carefully organized folder structure across migrations




• Production-Ready Reliability: Built-in retry logic with exponential backoff, comprehensive error handling, and detailed logging




• Multiple Authentication Methods: Supports username/password, session tokens, and personal API tokens for maximum flexibility

The Export-Import Workflow

At its core, the toolkit follows a three-step process that transforms the complex task of migration into a repeatable, automated workflow.

Step 1: Export from Source

The export process connects to your source Metabase instance and recursively traverses your collection hierarchy. For each collection, it exports all questions (cards) and dashboards, along with their complete metadata. Critically, it also captures table and field metadata from your databases — information that will be essential for the remapping process later.

The export creates a structured directory with JSON files for each piece of content, plus a manifest.json file that serves as an index of everything that was exported. This manifest includes database mappings, collection hierarchies, and dependency relationships between questions and dashboards.

Step 2: Configure Database Mapping

This is where the magic happens. You create a db_map.json file that tells the toolkit how to map source database IDs to target database IDs. For example, if your analytics_db is ID 3 in the source instance but ID 7 in the target instance, you specify that mapping.

The toolkit uses this mapping — combined with the table and field metadata it captured during export — to build intelligent remapping tables. It matches tables by name within each database, then matches fields by name within each table. This ensures that a question querying customers.email in the source will query the correct customers.email field in the target, even though the underlying IDs are completely different.

Step 3: Import to Target

The import process reads the export package, applies all the ID remappings, and recreates your content on the target instance. It processes collections first to establish the hierarchy, then imports questions (resolving dependencies in the correct order), and finally imports dashboards with all their cards properly linked.

Throughout this process, the toolkit handles conflicts according to your chosen strategy, applies permissions if requested, and generates a detailed import report showing exactly what was created, updated, or skipped.

Real-World Use Cases

Scenario 1: Multi-Environment Deployment Pipeline

Your data team develops new dashboards and questions in a staging Metabase instance, tests them thoroughly, and then promotes them to production. With the toolkit, this becomes a repeatable CI/CD process:

# Export from staging

metabase-export --export-dir "./staging_export" --root-collections "24,13"



# Import to production with conflict resolution

metabase-import --export-dir "./staging_export" --db-map "./prod_db_map.json" --conflict overwrite

This workflow ensures that your production analytics stay in sync with your development work, just like your application code.

Scenario 2: Instance Consolidation

Your organization has grown through acquisitions, and now you have three separate Metabase instances that need to be consolidated into one. Each instance has hundreds of dashboards, different database connections, and unique permission structures.

The toolkit allows you to export from each source instance, configure appropriate database mappings for each, and import them into different collections on the target instance. The conflict resolution ensures that dashboards with the same name don’t collide, and permissions migration preserves access control for each team.

Scenario 3: Disaster Recovery and Backups

You need a reliable backup strategy for your Metabase analytics. The toolkit enables scheduled exports that capture your entire Metabase configuration as version-controlled JSON files:

# Daily backup script

metabase-export \

  --export-dir "./backups/$(date +%Y%m%d)" \

  --include-dashboards \

  --include-archived \

  --include-permissions

If disaster strikes, you can restore to any point in time. If someone accidentally deletes a critical dashboard, you can recover it from yesterday’s backup.

Scenario 4: Cross-Environment Synchronization

Many organizations run Metabase instances in different environments — development, staging, and production — or even across different cloud regions for compliance reasons. Keeping these instances synchronized is a constant challenge.

The toolkit enables automated synchronization workflows where changes made in one environment can be systematically propagated to others. For example, you might develop new analytics in a dev environment, test them in staging, and then deploy to multiple production instances across different regions — all while maintaining consistent database mappings and permissions for each environment.

A Complete Example

Here’s a practical example showing the full workflow from export to import:

1. Install the toolkit:
   

pip install metabase-migration-toolkit

1. Configure your credentials in a .env file:
   

# Source instance

MB_SOURCE_URL=https://source-metabase.company.com

[email protected]

MB_SOURCE_PASSWORD=source_password



# Target instance

MB_TARGET_URL=https://target-metabase.company.com

[email protected]

MB_TARGET_PASSWORD=target_password

1. Export from source:
   

metabase-export \

  --export-dir "./migration_2025" \

  --include-dashboards \

  --include-permissions \

  --root-collections "24,13,26"

1. Create database mapping (db_map.json):
   

{

  "by_id": {

    "3": 7,

    "5": 9

  },

  "by_name": {

    "analytics_db": 7,

    "warehouse_db": 9

  }

}

1. Import to target:
   

metabase-import \

  --export-dir "./migration_2025" \

  --db-map "./db_map.json" \

  --conflict skip \

  --apply-permissions

That’s it! The toolkit handles all the complexity of ID remapping, dependency resolution, and permission application automatically.

Understanding ID Remapping

The most critical aspect of a successful Metabase migration is understanding why ID remapping matters — and why the toolkit’s approach is essential.

The Database ID Problem

Every Metabase instance assigns unique IDs to databases, tables, and fields. When you have a question that queries SELECT * FROM companies WHERE type = ‘enterprise’, Metabase doesn’t store this as SQL. Instead, it stores a JSON structure with database ID, table ID, and field IDs. If you naively copy this question to another instance without remapping these IDs, it will query the wrong database or fail entirely.

The Table ID Challenge

Here’s where it gets tricky: you might have a table called companies in multiple databases. For example, your company_service database has a companies table, and so does your payment_service database. These are different tables with different schemas, but they share the same name. Without proper table ID remapping, a question that should query company_service.companies might end up querying payment_service.companies instead—showing completely wrong data without any obvious error.

The Solution: Three-Level Remapping

The toolkit solves this with a three-level remapping strategy:

• Database ID remapping: Maps source database IDs to target database IDs using your db_map.json
  


• Table ID remapping: Within each database, maps table IDs by matching table names


• Field ID remapping: Within each table, maps field IDs by matching field names

This ensures that every reference in every question points to the correct database, table, and field in the target instance — even when table names collide across databases.

Production-Ready Quality

What sets the Metabase Migration Toolkit apart from quick scripts or manual processes is its production-ready quality. The project includes:

Comprehensive test suite: Unit tests and integration tests covering all major functionality

CI/CD pipeline: Automated testing, linting, and security scanning on every commit

Detailed documentation: README, quick start guide, troubleshooting docs, and API documentation

Active maintenance: Regular updates and bug fixes from the open-source community

Type safety: Full type hints and mypy checking for reliability

Error handling: Graceful handling of API failures with retry logic and clear error messages

This isn’t a works on my machine solution — it’s a tool you can trust with your production analytics infrastructure.

Take Control of Your Metabase Migrations

Migrating Metabase content doesn’t have to be a manual, error-prone process that takes days of careful work. With the Metabase Migration Toolkit, you can automate the entire workflow, ensure correctness through intelligent ID remapping, and treat your analytics infrastructure with the same rigor as your application code.

Whether you’re managing a multi-environment deployment pipeline, consolidating instances, or just need reliable backups, this toolkit provides the production-ready solution you need.

Ready to get started? 🚀

• Repository: github.com/Finverity/metabase-migration-toolkit


• Installation: pip install metabase-migration-toolkit


• Documentation: Check the README for detailed guides and examples


• Contributing: Issues and pull requests welcome!

The toolkit is open source under the MIT license, actively maintained, and ready for production use. Give it a try on your next Metabase migration — your future self will thank you.