Ready to move your existing Metabase instance to Metabase Cloud? We’ve put together this guide to make sure your migration goes as smoothly as possible. And don’t stress; if anything goes wrong, we’re here to help.
How it’s going to work: you’ll prep for the migration, including upgrading to the latest Metabase version. Then you’ll sign up for a free trial of Metabase and initiate a migration. You’ll get a script that will automate dumping your application data - your questions, dashboards, collections, users, and other data specific to your instance - from your self-hosted Metabase to your new home on Metabase Cloud. The actual migration process shouldn’t take more than 15 minutes, but you’ll need to take care of a few odds and ends before and after migrating to make sure the everything goes off without a hitch.
Prepare to migrate
Before you migrate:
Confirm you have the right access
In order to migrate, you’ll need shell access to your self-hosted Metabase environment, and your Metabase environment will need access to the Internet.
Upgrade to the latest version of Metabase
Follow the instructions outlined in our upgrade guide to bring your Metabase up to speed. If you have any problems upgrading, we can get those resolved before migrating to Metabase Cloud.
Schedule some downtime
Be sure to let your users know that your Metabase instance will be unavailable for the duration of the migration (ideally during off-hours). The migration process usually takes less than 15 minutes.
Shut down your Metabase instance
All you need to do is stop the Metabase JAR process or Docker container to make sure your Metabase has shut down. The idea here is to prevent people from creating more questions or dashboards that could put your instance in an inconsistent state during the migration.
Back up your application database
In the unlikely event that something goes wrong, you’ll want a backup. See Backing up Metabase Application Data.
Migrate to Metabase Cloud
Now you’re ready to start the migration process. The process itself is largely automated, but it’s unique to your instance. Let’s walk through it.
Create a trial Metabase Cloud instance
The first thing to do is to create a new home to migrate to. Sign up for a free trial of Metabase Cloud. You’ll get a brand new instance of Metabase Cloud. You can play around with your new instance if you like; just know that any questions or dashboards you create will be overwritten when you upload the application data from your existing, self-hosted Metabase instance.
Generate a migration script
Visit your Metabase Store account. From the Instance settings in your account, in the Migration section, select the version of your self-hosted instance (the one you’ll be migrating from) and click Initiate Migration.
Follow the migration instructions
You’ll get a command to run that will download a script to manage your migration. There is one command for the Metabase JAR, and one if you’re running Metabase via Docker. If you’re running Docker, the environment variables will already be set, but if you’re running the JAR, you’ll need to make sure to set any
MB_DB_* environment variables you normally use to configure your application database.
Execute the script in your self-hosted environment
The script will upload your application data to your new Metabase Cloud instance, which will overwrite any data in the cloud instance. If all goes well, the script will print
Note that the token generated for the migration script is only valid for one hour, and can only be used once. We limit the lifetime of these tokens to prevent accidental overwrites of your data. If you need to run the migration script again, contact us and we’ll generate another script with a new token for you.
If anything goes sideways, just send us an email and we’ll help you troubleshoot.
After migrating to Metabase Cloud
Once the script finishes, there are a few things left to button up.
Verify your site URL
After a successful migration, log in to your shiny new Metabase Cloud instance. You should see all of your questions and dashboards just as you did in your self-hosted instance.
Go to Admin > Settings > General > Site URL, and confirm that the Site URL has been updated to your new Metabase Cloud URL (something like mycompany.metabaseapp.com.)
For Enterprise customers using SAML SSO, you’ll need to update your settings with your identity provider to change the Redirect URL and the Base URL to your new Metabase Cloud URL, otherwise your identity provider will still redirect people to your old (and shut down) Metabase instance. See Authenticating with SAML for details on how to set these URLs.
Once you’ve confirmed the URL, go ahead and tell everyone the new address they should use to log in to Metabase. People should be able to log in as usual and pick up right where they left off.
If you’re embedding Metabase in an application, be sure to update your code to reflect the new URL.
Put your old Metabase out to pasture
Though you should have already shut down your old Metabase instance, if you were self-hosting via a third-party, be sure to clean up and cancel any services to avoid any unnecessary charges (like storage for old backups, for example).
And that’s it — we’ll take care of your Metabase and keep it up to date from here on out. Welcome to Metabase Cloud!
Limitations with Metabase Cloud
Note that there are some limitations that could impact or prevent you from migrating to Metabase Cloud.
- It’s currently not possible to use custom domains like metabase.mycompany.com.
- Metabase Cloud only works with Metabase’s officially supported databases (see our full list of supported databases). At this time, Metabase Cloud does not support third-party, community database drivers, including drivers with dependencies (like Oracle).
- With the exception of MongoDB, you cannot use database connections that require custom certificates, as there’s currently no way to upload the certificates.
- Database connections through SSH tunnels may cause timeouts after a short period. We are working on fixing that issue, but just know that this can be a thing.
If you have any questions, just send us an email.