Migrating your Metabase instance to a new server without downtime

Thinking about moving your Metabase dashboards to a new server, but the thought of downtime makes you nervous? You’re not alone. Whether you’re outgrowing your current setup, switching cloud providers, or just need better hardware, migrating Metabase with zero downtime isn’t magic—but it does take some prep. This guide is for admins and devs who want a no-nonsense, step-by-step path to move their Metabase instance safely, without losing sleep (or users).

Let’s get right into it.

Why migrate Metabase at all?

Maybe your server is running out of steam, or your company wants everything on AWS instead of DigitalOcean. Sometimes it’s just housekeeping—cleaning up old infrastructure or moving to a containerized environment. Whatever the reason, the main worry is always the same: don’t break anything and don’t disrupt users.

This guide covers migrations for self-hosted Metabase instances using the default H2 or a production database (Postgres/MySQL). If you’re still running on H2, this is a good time to switch to a real database—you’ll thank yourself later.

What actually matters for a smooth migration

Let’s be blunt: the official docs gloss over the messy bits. Most “how-tos” skip the details that bite you at 2am. Here’s what you really need to keep in mind:

  • Metabase’s “application database” holds everything: questions, dashboards, users, permissions. If you lose this, you lose it all.
  • Your Metabase version should match across servers. Don’t upgrade and migrate at the same time—do one thing at a time.
  • Your data sources (the databases Metabase connects to) are not stored in Metabase. But their connection info is. Test your new server’s ability to reach them.
  • DNS and SSL can be easy or a pain, depending on your setup. Plan ahead.

Step-by-step: Migrating Metabase with zero downtime

Here’s how to do it, start to finish. You’ll need admin access to both old and new servers, and enough permissions to move files, manage databases, and change DNS.

1. Prep the new server

  • Provision the new box (VM, cloud instance, or container). Match the OS and specs as closely as possible, unless you’re deliberately upgrading.
  • Install Java. Metabase needs it. OpenJDK 11 or 17 is safest; don’t get clever unless you need to.
  • Download Metabase (same version as your current server). Don’t mix versions—if you want to upgrade, do that after migration.
  • Open required ports (by default, 3000).

Pro tip: If you use Docker, just match the image tag to what you’re running now.

2. Backup everything—twice

  • Backup your Metabase application database. If you’re using H2 (the old default), copy the entire metabase.db directory. For Postgres or MySQL, use pg_dump or mysqldump.
  • Backup the Metabase config files and environment variables. Especially if you use external auth or SMTP.
  • Keep a copy of your old server snapshot handy. If you have the option, take a full server snapshot so you can roll back if you really mess up.

What not to skip: Don’t rely on “I’ll just copy the H2 file real quick.” If Metabase is running, you’ll get a corrupt backup. Always shut down Metabase first if you’re copying the H2 file.

3. Set up the application database on the new server

  • For H2: Copy the metabase.db directory to the new server, same path as before.
  • For Postgres/MySQL:
    • Create a blank database on the new server (or point to the same remote DB, if that’s your setup).
    • Restore from your dump file.
    • Double-check user permissions.

4. Configure Metabase on the new server

  • Set environment variables (MB_DB_TYPE, MB_DB_FILE, MB_DB_HOST, etc.) so Metabase points to the restored database.
  • Copy any custom config (SSL certs, plugins, or dependencies).
  • Test your connection to your data sources from the new server. Use psql, mysql, or telnet to confirm the new server can actually reach your data warehouses. Don’t assume.

5. Dry run: Test Metabase on the new server (in isolation)

  • Start Metabase (don’t expose it yet!).
  • Visit the new server’s IP and port. Make sure dashboards, questions, and permissions look right.
  • Log in as an admin, poke around, run a few queries.
  • Check the logs for errors.

What to ignore: Don’t worry about SSL or pretty URLs yet. Focus on making sure the data and config are right.

6. Plan the cut-over: minimize (or eliminate) downtime

Here’s the real trick: you want to switch users over with as little interruption as possible. The basic idea is:

  • Keep the old server running until the new one is verified.
  • Update DNS or load balancer to point to the new server.
  • Handle SSL/TLS certs as needed.

Common scenarios:

A. You control DNS for a friendly URL (e.g., metabase.yourcompany.com):

  1. Lower the DNS TTL (Time To Live) to 5 minutes (or as low as your DNS provider allows) at least an hour before migration.
  2. When ready, stop Metabase on the old server.
  3. Start Metabase on the new server.
  4. Update the DNS to point to the new server’s IP.
  5. Wait for DNS to propagate (should be quick if you set TTL low).
  6. Test from multiple networks (use your phone’s data, for example).

B. You use a load balancer:

  • Swap the backend target from old to new.
  • For zero downtime, you can briefly run both servers behind the load balancer, but make sure only one instance writes to the application database.

C. No DNS, just IP access:

  • Change your documentation.
  • Tell users when the switch happens.

SSL/TLS tips

  • If using Let’s Encrypt, you may need to re-issue certs for the new server.
  • For reverse proxies (Nginx, Apache), copy your config and certs over.

7. Final checks and monitoring

  • Check user logins, dashboard loads, and query runs.
  • Monitor logs on the new server for errors or odd behavior.
  • Watch resource usage (CPU, RAM, disk). Sometimes a hardware mismatch bites here.

Don’t rush to delete the old server. Keep it for at least a few days, just in case you missed something.

Common pitfalls (and how to dodge them)

  • Live H2 backup: If you back up H2 while Metabase is running, you risk corruption. Always shut down first.
  • Version mismatch: Upgrading Metabase while migrating is asking for trouble. Move first, upgrade later.
  • Firewall rules: The new server can’t reach your data sources—check security groups and firewalls.
  • Hardcoded IPs: If your data sources whitelist the old server’s IP, update them.
  • Env vars or configs missing: Double-check everything, especially integrations (auth, SMTP, SSO).

What about scaling or cloud-native deployments?

Moving to Kubernetes? Using Docker Compose? The same principles apply: focus on the application database and the environment variables. For Docker, mounting the correct volume for the Metabase DB is key. For K8s, config maps and secrets must match.

Skip the hype—K8s won’t magically make your migration easier, but it does make rollbacks safer (if you know what you’re doing).

Keep it simple, iterate fast

Migrations get messy when you try to do too much at once. Move your Metabase instance first, then make improvements once you’re stable. Don’t stress about a few minutes of downtime if it means doing things safely. The real win is a migration you barely notice—because nothing broke, and nobody complained.

If you hit a snag, don’t panic. Roll back, fix the problem, and try again. Good backups and a methodical approach beat clever hacks every time.