This content originally appeared on DEV Community and was authored by Peshkov Max
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:
- Install the toolkit:
pip install metabase-migration-toolkit
- Configure your credentials in a .env file:
# Source instance
MB_SOURCE_URL=https://source-metabase.company.com
MB_SOURCE_USERNAME=admin@company.com
MB_SOURCE_PASSWORD=source_password
# Target instance
MB_TARGET_URL=https://target-metabase.company.com
MB_TARGET_USERNAME=admin@company.com
MB_TARGET_PASSWORD=target_password
- Export from source:
metabase-export \
--export-dir "./migration_2025" \
--include-dashboards \
--include-permissions \
--root-collections "24,13,26"
- Create database mapping (db_map.json):
{
"by_id": {
"3": 7,
"5": 9
},
"by_name": {
"analytics_db": 7,
"warehouse_db": 9
}
}
- 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.
This content originally appeared on DEV Community and was authored by Peshkov Max
Peshkov Max | Sciencx (2025-11-17T07:11:47+00:00) Migrating Metabase Content Between Instances: A Production-Ready Solution for Data Teams. Retrieved from https://www.scien.cx/2025/11/17/migrating-metabase-content-between-instances-a-production-ready-solution-for-data-teams/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.