Skip to main content
The application database is where Metabase stores information about user accounts, questions, dashboards, and any other data needed to run the Metabase application. This is distinct from your data warehouse where your actual data lives.
For production deployments, we strongly recommend using PostgreSQL as your Metabase application database.

​
Supported databases

Metabase supports the following databases for storing application data:
  • PostgreSQL (recommended for production)
  • MySQL or MariaDB (also works for production)
  • H2 (default for local demos - avoid in production)
Metabase reads the database configuration when the application starts. You cannot change the application database while Metabase is running.
PostgreSQL is the recommended database for production Metabase deployments. Metabase supports PostgreSQL versions from the oldest supported version through the latest stable version.

​
Create the database

First, create an empty PostgreSQL database for Metabase: 
createb --encoding=UTF8 -e metabase
Metabase will automatically create all necessary tables on first startup.

​
Configure with environment variables

Set each connection parameter separately:
export MB_DB_TYPE=postgres
export MB_DB_DBNAME=metabase
export MB_DB_PORT=5432
export MB_DB_USER=<username>
export MB_DB_PASS=<password>
export MB_DB_HOST=localhost
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

​
Docker configuration

For Docker deployments, pass environment variables with the -e flag: 
docker run -d -p 3000:3000 \
  -e "MB_DB_TYPE=postgres" \
  -e "MB_DB_DBNAME=metabase" \
  -e "MB_DB_PORT=5432" \
  -e "MB_DB_USER=<username>" \
  -e "MB_DB_PASS=<password>" \
  -e "MB_DB_HOST=my-database-host" \
  --name metabase metabase/metabase

​
SSL configuration

For PostgreSQL connections with SSL certificate validation: 
export MB_DB_CONNECTION_URI="postgres://localhost:5432/metabase?user=<username>&password=<password>&sslmode=verify-ca&sslrootcert=<path to certificate>"
Metabase removed the PostgreSQL NonValidatingFactory in version 0.38. If upgrading, configure SSL certificate validation or enable the factory manually (not recommended for production).

​
MySQL or MariaDB

While we recommend PostgreSQL, MySQL and MariaDB are also supported for production deployments.

​
Version requirements

  • MySQL: version 8.0.17 or higher
  • MariaDB: version 10.2.2 or higher
  • Character set: utf8mb4 is required
ApsaraDB MySQL is not supported. Use ApsaraDB PostgreSQL instead.

​
Create the database

Create a MySQL database with the correct character set: 
CREATE DATABASE metabase CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

​
Configure with environment variables

export MB_DB_TYPE=mysql
export MB_DB_DBNAME=metabase
export MB_DB_PORT=3306
export MB_DB_USER=<username>
export MB_DB_PASS=<password>
export MB_DB_HOST=localhost
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

​
H2 database (development only)

For production installations, replace the default H2 database with PostgreSQL. H2 is file-based and only suitable for local testing.
By default, Metabase ships with an embedded H2 database for easy demos on your local machine. If you don’t provide environment variables specifying a production database, Metabase will create an H2 database in the same directory as the JAR file.

​
H2 database files

You can see the H2 database files in your Metabase directory: 
ls metabase.*
# Output:
# metabase.db.h2.db  (or metabase.db.mv.db)
# metabase.db.trace.db

​
Custom H2 location

To use an H2 database file in a specific directory: 
export MB_DB_TYPE=h2
export MB_DB_FILE=/the/path/to/my/h2.db
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar
H2 automatically appends .mv.db or .h2.db to the path you specify. Exclude these extensions in MB_DB_FILE.

​
Key environment variables

​
MB_DB_TYPE
string
Database type: postgres, mysql, or h2
​
MB_DB_DBNAME
string
Name of the Metabase application database
​
MB_DB_PORT
integer
Database port (5432 for PostgreSQL, 3306 for MySQL)
​
MB_DB_USER
string
Database username
​
MB_DB_PASS
string
Database password
​
MB_DB_HOST
string
Database hostname or IP address
​
MB_DB_CONNECTION_URI
string
Full JDBC connection string (overrides individual parameters)
​
MB_DB_FILE
string
Path to H2 database file (H2 only)

​
Cloud database services

​
Amazon RDS

Metabase works well with Amazon RDS for PostgreSQL or MySQL. Follow AWS best practices for:
  • Automated backups
  • Multi-AZ deployments for high availability
  • Parameter groups for performance tuning
  • Security groups for network access control
See the Amazon RDS documentation for setup instructions.

​
Creating an RDS instance

For guidance on creating an RDS database specifically for Metabase, see our AWS RDS setup guide.

​
Troubleshooting

​
Connection timeout

If you experience connection timeouts, especially over SSH tunnels: 
export MB_DB_CONNECTION_TIMEOUT_MS=30000  # 30 seconds instead of default 10

​
Query timeout

For long-running queries during migrations or heavy usage: 
export MB_DB_QUERY_TIMEOUT_MINUTES=30  # 30 minutes instead of default 20

​
SSL certificate issues

If you can’t enable certificate validation, you can temporarily enable NonValidatingFactory (not recommended): 
export MB_DB_CONNECTION_URI="postgres://localhost:5432/metabase?ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory"

​
Migrating from H2

If you’ve been using the default H2 database and want to migrate to a production database without losing your data:

Migrate from H2 to production

Learn how to migrate your H2 data to PostgreSQL or MySQL

​
Next steps

Environment variables

View all available configuration options

Backing up Metabase

Set up regular backups of your application database

Running on Docker

Deploy Metabase with Docker and database configuration

Upgrading Metabase

Learn how to safely upgrade your Metabase instance

Build docs developers (and LLMs) love

Get started for freeTalk to us