Which application database should a self-hosted Metabase use?
A team that started with Metabase on a laptop and is now moving to a shared production instance should stop using the embedded H2 default. Metabase ships H2 so it is easy to demo locally, and its documentation says to avoid it in production, because a corrupted H2 file can lose questions, dashboards and collections. Choose PostgreSQL as the application database unless your organization has already standardized on MySQL or MariaDB, in which case that engine is supported and fits the same role.
PostgreSQL is the documented recommendation, and the Metabase migration guide sets PostgreSQL 14 as the minimum for it. Note that PostgreSQL 14 is listed as supported only until November 12, 2026, so pick a version that is still in support on your go-live date, such as 15 or later, and confirm it against the PostgreSQL versioning policy. For MySQL, Metabase's minimum is 8.4.0, and MariaDB's is 10.6.0. Either engine must use the utf8mb4 character set, utf8mb4_unicode_ci collation and innodb_large_prefix, so check those settings with your DBA before installing anything.
Confirm three things in your own environment before you pick. First, whether your platform team already runs and backs up PostgreSQL or MySQL, since the application database needs regular backups and a tested restore. Second, which Metabase version you will run, because the one-time load-from-h2 migration must use the same version that last wrote the H2 file, and it runs only against a brand-new empty database with Metabase stopped. Third, your upgrade plan: Metabase runs application database migrations automatically, so back up that database first. The Metabase application database documentation is the place to verify current requirements.
H2, PostgreSQL and MySQL compared for the Metabase application database
This table compares the three choices for where a self-hosted Metabase keeps its questions, dashboards and settings. Read each row as a decision input: intended use and documented minimums come first, then the operating work that stays with your team. The main takeaway is that H2 is a demo default, while PostgreSQL and MySQL are the production choices, and PostgreSQL is the one Metabase recommends.
| Factor | H2 (embedded default) | PostgreSQL | MySQL or MariaDB |
|---|---|---|---|
| Intended use | Local demos, per Metabase docs | Recommended for production | Supported for production |
| Documented minimum version | Bundled with Metabase | PostgreSQL 14 minimum for the recommended database | MySQL 8.4.0 or MariaDB 10.6.0 minimum |
| Character set and collation | Not applicable | Confirm encoding with the migration guide | utf8mb4 with utf8mb4_unicode_ci and innodb_large_prefix required |
| Database engine license | Bundled, part of Metabase | PostgreSQL License, similar to BSD or MIT | MySQL Community under GPL; confirm MariaDB terms separately |
| Load-from-h2 migration target | Source only | Supported, run against a brand-new empty database | Supported, run against a brand-new empty database |
| Backups you run | Back up the H2 file regularly, since corruption can lose questions and dashboards | Regular backups and point-in-time recovery are your responsibility | Regular backups are your responsibility, including hot backup tooling choice |
| Upgrades and replication you run | Not suited to replication | You select replication and failover tooling; PostgreSQL does not provide automatic failover | You select the replication model; Group Replication offers automated failover in Community Edition |
Why Metabase says to avoid H2 in production
Metabase ships with an embedded H2 application database so that a local demo works with no extra setup, and the Metabase documentation says not to run production on that default. The application database is where Metabase keeps saved questions, dashboards, collections, users and instance settings. It is not your warehouse data, but it is the part of the instance that people spend time building and that is hardest to recreate. Treat the H2 default as a trial setting only, and make the production database choice a deliberate decision rather than something left at install time.
The migration guide warns that without regular backups, the H2 application database could become corrupted, and the loss would cover questions, dashboards and collections. That risk is the reason to set a backup routine before you decide anything else about the database. Confirm three things in your own environment: where the H2 file lives on the host, how often it is copied, and whether a restore has ever been tested. A backup that has never been restored is an assumption, not a control. The Metabase migrating from H2 guide is the natural next read for the file-level details.
Once the backup routine is running, the choice of PostgreSQL or MySQL becomes a question about your operating standards: which engine your team can back up, restore, patch and monitor. Whichever you pick, keep the same Metabase version throughout any move off H2, because the one-time load-from-h2 step depends on it. Write the backup schedule, the restore test and the target database owner into your runbook before the first production user logs in.
How the one-time load-from-h2 migration works
The documented sequence moves an existing embedded H2 application database into a new PostgreSQL or MySQL database, so questions, dashboards, collections and settings carry over without rebuilding them. It runs once, and the Metabase version used must match the one that last wrote to the H2 file.
Confirm the running Metabase version
Before anything else, record the exact Metabase version that last updated the H2 file. The load-from-h2 command must be run with that same version, so this number drives every later step. Check the running version in the admin settings or the deployment image tag, and write it down with the date. Done means you have one version string that every following step will use. Confirm the exact steps against the migrating-from-H2 documentation for your release, because the procedure can change between versions.
Provision a brand-new empty target database
Create a new, empty PostgreSQL or MySQL database for the Metabase application data. PostgreSQL is the recommended choice, and the migration guide lists PostgreSQL 14 as the minimum for it. For MySQL, use a supported version with the utf8mb4 character set, utf8mb4_unicode_ci collation and innodb_large_prefix enabled. The database must be empty, because the load command does not merge into existing data. Done means you can connect to the empty database with a dedicated account and the settings match the documented requirements.
Stop Metabase completely
Shut down every Metabase process that uses the H2 file, including any second node in a cluster. Metabase must not be writing to the H2 file while it is copied or read. Confirm no process holds the file by checking the service status or container state. Done means Metabase is stopped and nothing else has the H2 application database open, so the file is in a consistent state for the next step.
Back up the H2 application database file
Copy the H2 application database file to a separate, protected location before running any command. The Metabase migration guide warns that without regular backups the H2 database could become corrupted and lose questions, dashboards and collections, so this copy is your rollback point. Store it with the same access controls as production data, since it contains query definitions and connection settings. Done means the copy exists, its size matches the original, and you can read it back from the backup location.
Run the load-from-h2 command
Run Metabase's load-from-h2 command against the H2 file and the new empty database, using the same Metabase version recorded in the first step. The command is one-time: it copies the application data into the target and is not a sync that runs later. Point the connection settings at the new database, not the H2 file as the destination. Done means the command finishes without errors and reports that the data was loaded. If it fails, leave the target as is, fix the cause, and rerun against an empty database.
Start Metabase on the new application database
Configure the Metabase application database connection to point at the PostgreSQL or MySQL database, then start Metabase at the same version. Metabase runs its own application database migrations on startup, so the database should be the one loaded in the previous step. Watch the startup logs for database errors. Done means the instance starts, the login page loads, and an admin account can sign in.
Verify questions, dashboards and collections
Sign in and check that a representative set of questions, dashboards, collections, permissions and database connections appears as before. Run a few saved questions and confirm they return results against the data sources. Compare counts of dashboards and collections with the notes taken before the migration. Done means the checks match what you recorded, and you have confirmed the old H2 backup can stay in cold storage until the retention period set by your own policy ends.
Set up backups for the new database
Once the instance works, schedule regular backups of the new PostgreSQL or MySQL application database, since the H2 file's backup routine no longer applies. Metabase upgrades also run application database migrations, so take a backup before each upgrade. Confirm the restore procedure works in a test environment. Done means a recent backup exists, a restore has been tested, and the upgrade routine references this backup step.
Supported database versions and their requirements
Metabase sets a floor for each application database engine, and the floor is only the starting point. The cards below cover the minimum PostgreSQL and MySQL or MariaDB versions, the character set and collation rules, and the support window you should confirm before you pick a major version for go-live.
PostgreSQL 14 as minimum
Metabase lists PostgreSQL 14 as the minimum for its recommended application database. PostgreSQL 14 is already close to its end of support, so a new deployment should start on a newer major version. Confirm the version your Metabase release accepts in the current migration guide before you provision the server, because the minimum and the version you should choose are not the same thing.
Check your PostgreSQL support window
PostgreSQL supports each major version for five years after its first release. Supported majors listed in the versioning policy run from 18 down to 14, with 14 ending first. Before go-live, record the end-of-support date for the major you chose and put the next upgrade on the calendar, since a major upgrade of the application database is a planned change rather than a patch.
MySQL 8.4.0 or MariaDB 10.6.0 minimum
For MySQL, the minimum recommended version is 8.4.0. For MariaDB, it is 10.6.0. Metabase supports both engines, but its guidance favors PostgreSQL for production. If your organization already standardizes on MySQL or MariaDB, confirm that the chosen release is on the vendor's current support track, since MySQL releases split into LTS and Innovation tracks with different support lengths.
utf8mb4 with utf8mb4_unicode_ci
Metabase requires the utf8mb4 character set and the utf8mb4_unicode_ci collation for MySQL and MariaDB. Set both at the database level before Metabase first starts, because questions, dashboard names and collection names with non-Latin characters or emoji can fail to store correctly under the older utf8 default. Check the character set on the server, the database and each connection, and do not assume the installer set them.
innodb_large_prefix for MySQL
Metabase's migration guide requires innodb_large_prefix to be enabled for MySQL. This setting governs index key prefix length in InnoDB, and it matters for the application database because Metabase creates indexes on text columns. Confirm the setting in your MySQL configuration and on any managed service you use, since a missing setting can cause the schema creation or the load-from-h2 step to fail partway through.
When PostgreSQL fits and when MySQL or MariaDB is the right call
Choose PostgreSQL as the application database for a self-hosted Metabase unless your organization already runs MySQL or MariaDB well and wants that engine for this workload too. Metabase's documentation recommends PostgreSQL for production, its migration guide sets PostgreSQL 14 as the minimum for the recommended database, and PostgreSQL is released under the PostgreSQL License, a permissive license similar to BSD or MIT. Its versioning policy gives each major version five years of support, with PostgreSQL 14 supported until November 12, 2026, so any new deployment should start on a version with a later end-of-life date such as 17 or 18.
MySQL Community Edition is available under the GPL and offers an LTS track, and MariaDB is supported from 10.6.0 with utf8mb4 settings. These engines make sense when your database team already has tested backup, restore and patching runbooks for one of them, when your monitoring and on-call tooling covers it, or when a support contract from the vendor sits on the same engine. The MySQL requirements also include the utf8mb4 character set, the utf8mb4_unicode_ci collation and innodb_large_prefix, so confirm those settings in your own configuration before the load-from-h2 step, not after. Ask whether the MySQL or MariaDB build you plan to run is covered by the support you rely on.
The engine choice matters most where an organization already has operational skills, backup tooling and a support contract for one engine. A second engine adds a second upgrade path, a second set of restore drills and a second source of security advisories to track. For a small team with no database operations staff, PostgreSQL's widely documented high availability and upgrade paths are the simpler starting point, but automatic failover still needs external tooling. Before you commit, write down who restores the Metabase database, how often that restore is tested, and which engine version your Metabase release supports.
Operating each database under Metabase
This table compares what it takes to back up, upgrade, keep highly available and staff each application database under Metabase. Read it as a checklist of operating conditions rather than a ranking, since the H2 default is meant for demos and the other two options carry real ongoing work. The main takeaway is that PostgreSQL and MySQL both shift backup, failover and upgrade responsibility onto your team, and that the work is manageable only if you plan for it.
| Operating concern | PostgreSQL (recommended) | MySQL or MariaDB |
|---|---|---|
| Backups | Back up the application database before every Metabase upgrade and on a regular schedule. Metabase's migration guide warns that H2 without regular backups can corrupt and lose questions, dashboards and collections. | Same requirement. Back up before upgrades and on a schedule. Hot backups are an Enterprise Backup feature in MySQL Enterprise Edition, so Community users should confirm their own backup tooling. |
| Metabase upgrade migrations | Metabase runs application database migrations automatically on upgrade. Back up first, and upgrade release by release if the installed version is older than 40. | Same automatic migrations apply. Confirm the utf8mb4 character set, utf8mb4_unicode_ci collation and innodb_large_prefix settings before upgrading. |
| Major upgrades in a cluster | Reduce the Metabase cluster to a single node for major upgrades because of the migration lock, then scale back out after the upgrade completes. | Same single-node reduction applies because of the migration lock. Plan a maintenance window for each step. |
| Automatic failover | PostgreSQL does not include software to detect a primary failure and notify a standby. Automatic failover needs external tools that your team selects, deploys and tests. | MySQL Community Edition includes InnoDB Cluster and Group Replication with automated failover, which is a condition to validate in your own environment rather than a default. |
| Replication and read scaling | Hot standby servers serve read-only queries, with synchronous or asynchronous replication. Confirm the replication setup Metabase supports before relying on it. | Replication is included in Community Edition. Confirm topology choices with your DBA and with Metabase's documentation before you deploy. |
| Minor and major version maintenance | Minor releases do not change storage format, so updates mean replacing executables and restarting. Major upgrades use pg_upgrade, pg_dumpall with restore, or logical replication, which can work with only several seconds of downtime. | Innovation releases are supported only until the next Innovation release, so pick the LTS track for stability. Confirm the support window for your chosen version under Oracle's policy. |
| Skills your team needs | Database administrators comfortable with backup tooling, replication, failover tooling and major version upgrades. Ask your provider which of these they will run for you. | Database administrators for replication topology, character set settings and backup tooling. Community Edition operations rely on your team's own runbooks. |
| Who carries the operating load | Your team, your cloud or data center, or DeployOpen under a written scope covering backup, upgrade and failover runbooks. | Same split: your team or a written-scope implementation partner owns backups, failover testing and upgrade runbooks. |
Which setup fits which team
A single team evaluating Metabase on a laptop or test virtual machine can keep the embedded H2 default for a short demo. Metabase ships H2 so the first run needs no database setup, but the documentation says to avoid it in production. The common trap is treating a pilot as throwaway when it quietly accumulates questions, dashboards and collections that the team later wants to keep. Decide early whether the pilot is disposable. If it may continue, point it at a new, empty PostgreSQL database from the start so no migration is needed later.
- Keep H2 only for disposable tests: Use the default for a demo you will delete, and record that decision in the project notes.
- Start on PostgreSQL if the pilot may continue: PostgreSQL is the recommended production choice, and PostgreSQL 14 is the minimum the migration guide lists.
- Back up the H2 file before any change: The migration guide warns that without regular backups the H2 file can corrupt, losing questions, dashboards and collections.
- Use one Metabase version throughout: The load-from-h2 command must run with the same version that last updated the H2 file.
- Plan the move before the pilot grows: Moving later means stopping Metabase, backing up the H2 file and running the one-time migration into a brand-new empty database.
Confirm with your platform team who provisions the pilot database and who owns its backups before anyone loads business data into it.
A standard production instance should use PostgreSQL as its application database, operated by the team that already runs PostgreSQL for other workloads. Choose a major version that stays in support for the expected life of the instance. According to the PostgreSQL versioning policy, version 18 is supported until November 14, 2030, and version 17 until November 8, 2029. Metabase 64 is an LTS release with end of life on 1 December 2027, so the application and database lifecycles can be planned together on the same calendar.
- Choose a supported PostgreSQL major: Confirm the version against the policy on the day you deploy, since support windows are fixed dates.
- Schedule backups and test restores: Continuous archiving and point-in-time recovery are documented PostgreSQL options. A backup that has never been restored is unproven.
- Back up before every Metabase upgrade: Metabase runs application database migrations automatically, so a fresh backup is your rollback point.
- Reduce to one node for major upgrades: The upgrade documentation describes a migration lock, so clusters should be scaled down before a major version change.
- Plan failover deliberately: PostgreSQL does not include software that detects a primary failure and notifies standbys, so automatic failover requires external tooling.
Confirm with your DBA the backup retention, recovery targets, failover tooling and connection pooling approach before go-live, and confirm the Metabase upgrade window against your change calendar.
A team already standardized on MySQL or MariaDB can use that engine for Metabase's application database, provided the instance meets the documented minimums and character settings. The minimums are MySQL 8.4.0 or MariaDB 10.6.0. The migration guide also requires the utf8mb4 character set, the utf8mb4_unicode_ci collation and innodb_large_prefix, so verify these before creating the database. PostgreSQL remains Metabase's stated production recommendation, so the MySQL path is supported but carries more configuration to get right.
- Confirm the version floor: MySQL 8.4.0 or MariaDB 10.6.0 are the minimum recommended versions for this path.
- Set the character set and collation first: Create the database with utf8mb4 and utf8mb4_unicode_ci, and check the innodb_large_prefix setting on the server.
- Prefer an LTS track for MySQL: The 8.4 line is LTS, and features are fixed in the first release of the series. Innovation releases are supported only until the next Innovation release.
- Use a dedicated, empty database for the migration: The load-from-h2 command runs against a brand-new empty database, so prepare one in advance.
- Confirm backup tooling for your edition: Enterprise Backup for hot backups is part of MySQL Enterprise Edition, so confirm the method your team will use under Community Edition.
Confirm with your DBA that the server settings match the migration guide, and confirm whether your support requirements call for the Community or Enterprise edition.
Questions teams ask before moving off H2
How much effort does moving Metabase off H2 actually take?
The migration itself is a single one-time load-from-h2 run, but the effort around it depends on how much data sits in the H2 file, how long you can keep Metabase stopped, and how carefully you match versions and check the result. Metabase documents that the load must target a brand-new, empty PostgreSQL or MySQL database and must be run with the same Metabase version that last updated the H2 file. The main drivers are:
- Data volume in the H2 file, which affects how long the load runs
- The downtime window you can agree with the business users who rely on dashboards
- Version matching between the H2 file and the Metabase build you run
- Validation after the load, including checking questions, dashboards, collections and permissions
The engineering work is modest for a small instance and grows with the number of environments, backups and users who must re-verify their content.
Can our own team run the H2 to PostgreSQL migration without outside help?
Yes, many teams do, provided someone can administer the target database and follow the Metabase migration steps closely. The work needs skills in PostgreSQL or MySQL administration, including creating an empty database with the right settings, managing backups and restoring them, and checking that the Metabase process can connect. For MySQL, you also need to set the utf8mb4 character set, utf8mb4_unicode_ci collation and innodb_large_prefix. Metabase's migration guide lists PostgreSQL 14 as the minimum for the recommended database. Your team should also be comfortable reading Metabase logs and rolling back to the stopped H2 file if something fails. If nobody on the team has run a stateful database migration before, that gap is the main reason to consider outside help.
What should a consultant scope before quoting an H2 migration?
A consultant should first confirm your Metabase version, deployment type, application database target, data volume and the environments that need the change. They should also agree on the backup approach, the maintenance window, rollback steps and how success will be checked. A fixed-scope quote should list these items in writing: the target PostgreSQL or MySQL platform and its version, the Metabase version used for the load, the backup and restore steps, the number of environments covered, the validation checks and the handover documentation. DeployOpen plans and implements engagements like this as fixed-scope work, with scope, deliverables and timelines agreed in writing before work starts. DeployOpen does not publish a price list, so ask for a quote tied to that written scope.
How long should we plan for the migration window?
Plan around the steps Metabase documents rather than a generic number. The window must cover stopping Metabase, backing up the H2 file, preparing an empty target database, running the load, starting Metabase on the new database and checking your content. The Metabase migration guide does not give a single duration, so the elapsed time depends on your data volume and environment. Ask your vendor or consultant to estimate timing from a test run on a copy of your H2 file. Upgrade planning also matters: Metabase runs application database migrations automatically during upgrades and recommends backing up the application database first, so schedule the migration separately from any version upgrade where possible.
Does upgrading to Metabase Pro change which database we should choose?
No. The application database is a separate decision from the Metabase plan. Metabase Pro and Enterprise add paid features such as SSO, row and column level permissions and auditing, but the recommendation for production remains PostgreSQL, with MySQL 8.4.0 or MariaDB 10.6.0 as supported alternatives. Choose the database based on the engines your organization can operate, back up and patch, then select the Metabase plan that covers the features you need. Keeping these two decisions apart avoids mixing licensing questions with infrastructure ones.
What happens to the H2 files after the migration is complete?
Keep the H2 file as a backup until you have verified the new application database and run it through at least one normal cycle of use. Metabase's guidance is to stop Metabase and back up the H2 file before the load, so that file is your rollback point. Once the new database is confirmed, archive the H2 file according to your retention policy rather than deleting it immediately. Remove the H2 path from your configuration only after Metabase is running on PostgreSQL or MySQL, and record the decision in your change documentation so auditors and future administrators can trace where the application data lives.
Why does Metabase say not to keep production data in H2?
Metabase ships H2 as an embedded default so it is easy to try on a local machine, and its documentation says to avoid using that default in production. The migration guide also warns that without regular backups the H2 application database could become corrupted, which would lose questions, dashboards and collections. A production instance needs a database with its own backup, restore and monitoring practices, which is why Metabase recommends PostgreSQL. Moving off H2 early, before dashboards become business critical, usually makes the migration simpler.
Official sources for the application database decision
Before you choose an application database for self-hosted Metabase, read the Metabase application database page first, because it sets out the default and the production recommendation in the vendor's own words. The page states that the embedded H2 database exists for demos on a local machine and should not be used in production, and it names PostgreSQL as the recommended engine, with MySQL 8.4.0 or MariaDB 10.6.0 as the minimum versions for those engines. Pair it with the Metabase migrating from H2 guide, which covers the one-time load-from-h2 command, the empty target database requirement and the need to stop Metabase and back up the H2 file first. For the PostgreSQL side, the PostgreSQL versioning policy tells you which major versions are still supported and when each one reaches end of life. Check that date against your planned go-live and your own upgrade calendar, since a database that leaves support during the life of the Metabase deployment adds a forced upgrade. For MySQL, the vendor's release documentation is the equivalent source, and you should confirm which track (LTS or Innovation) your standards allow. Confirm current requirements in the docs for your exact Metabase release before you commit to an engine, because minimum versions, required character sets and collations, and migration steps can change between releases. Record the version you checked, the date you checked it, and the Metabase version you plan to run, so the decision can be re-verified at your next upgrade.
How DeployOpen plans and runs a Metabase database move
DeployOpen plans and implements self-hosted open-source platforms inside the client's own infrastructure, so a move off the embedded H2 database is handled as a scoped project in your environment. We agree the target database, the migration steps and the evidence to hand over before any work starts.
How we scope
- Confirm the current Metabase version and the H2 file's last update, since the load-from-h2 step must match it.
- Agree whether the target is PostgreSQL or MySQL or MariaDB, and which hosting model your infrastructure supports.
- Record the written scope, deliverables and timeline for the engagement, which is fixed-scope and agreed in writing before work begins.
How we build
- Provision a brand-new empty target database and confirm its version, character set and collation requirements.
- Stop Metabase, back up the H2 file and run the one-time load-from-h2 migration with the matching Metabase version.
- Test that questions, dashboards, collections and settings load correctly before the instance returns to users.
How we hand over
- Document the final configuration, connection settings, backup routine and the upgrade order for future Metabase releases.
- Provide a record of the migration run, the versions used and the verification checks completed for your audit file.
- Walk your operations team through restore testing so backups of the new application database are proven, not assumed.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the handover is complete.
- Plan the next Metabase upgrade against the database version support window, confirming dates with the vendor directly.
- Agree the support boundaries, escalation path and change process in the written scope so responsibilities stay clear.
