Connecting Your First Database to Metabase

Metabase works by connecting directly to your database and running queries against it at runtime. It does not ingest, copy, or store your data. The connection you configure tells Metabase where your data lives and how to authenticate — from there, it can query any table the connected user has access to.

This guide covers how to set up a database connection, what permissions the Metabase database user needs, how Metabase uses the connection after setup, and the most common connection issues.

---

Supported Databases

Metabase connects natively to most databases teams are likely to be running:

Relational databases

• PostgreSQL (v9.4+)

Data warehouses

Other

The full list, with version requirements and known limitations, is in Metabase's documentation.

---

Step 1: Create a Read-Only Database User

Before adding a connection in Metabase, create a dedicated database user for Metabase with read-only access. Using a dedicated user:

PostgreSQL

sql
-- Create the user CREATE USER metabase_reader WITH PASSWORD 'a-strong-password'; 
-- Grant connection to the database GRANT CONNECT ON DATABASE your_database TO metabase_reader; 
-- Grant usage on the schema GRANT USAGE ON SCHEMA public TO metabase_reader; 
-- Grant read access to existing tables GRANT SELECT ON ALL TABLES IN SCHEMA public TO metabase_reader; 
-- Grant read access to future tables (important — without this, -- Metabase won't be able to query new tables you add later) ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO metabase_reader;

MySQL

sql
CREATE USER 'metabase_reader'@'%' IDENTIFIED BY 'a-strong-password'; GRANT SELECT ON your_database.* TO 'metabase_reader'@'%'; FLUSH PRIVILEGES;

Snowflake

sql
CREATE USER metabase_reader PASSWORD='a-strong-password'; CREATE ROLE metabase_role; GRANT ROLE metabase_role TO USER metabase_reader; GRANT USAGE ON WAREHOUSE your_warehouse TO ROLE metabase_role; GRANT USAGE ON DATABASE your_database TO ROLE metabase_role; GRANT USAGE ON ALL SCHEMAS IN DATABASE your_database TO ROLE metabase_role; GRANT SELECT ON ALL TABLES IN DATABASE your_database TO ROLE metabase_role; GRANT SELECT ON FUTURE TABLES IN DATABASE your_database TO ROLE metabase_role;

---

Step 2: Configure the Network Connection

Metabase needs to reach your database over the network. Depending on where your database is running, you may need to configure firewall rules or security groups.

Common Network Configurations

Database on the same host as Metabase (Docker) Don't use localhost inside the Metabase container — it refers to the container itself, not your host machine. Use:

Database on AWS RDS Add an inbound rule to the RDS security group allowing TCP on port 5432 (PostgreSQL) or 3306 (MySQL) from the IP or security group of your Metabase server.

Database on a private VPC If Metabase is not in the same VPC as your database, you'll need either VPC peering or an SSH tunnel (see below).

Metabase Cloud Metabase publishes its IP ranges in its documentation. Add these to your database's allowlist.

SSH Tunneling

If your database is not directly accessible from the network where Metabase runs, Metabase supports connecting through an SSH tunnel. Configure this in the connection settings by enabling the SSH tunnel option and providing:

---

Step 3: Add the Database in Metabase

Navigate to Admin → Databases → Add a database.

You'll be prompted to select your database type and fill in connection details:

Connection String Alternative

Some database types accept a connection string instead of individual fields. For example, for PostgreSQL:

postgresql://metabase_reader:a-strong-password@your-host:5432/your_database

SSL / TLS

For production databases, enable SSL in the connection settings. Most managed database services (RDS, Cloud SQL, Snowflake) require or strongly recommend SSL. Metabase supports:

Upload your CA certificate and client certificates in the advanced connection settings.

---

What Metabase Does After Connecting

Once a database is added, Metabase performs an initial schema sync:

This sync runs immediately after connection and then on a recurring schedule (default: every hour). The sync reads only metadata — it does not read the contents of your tables (except for a sample of values for certain column types).

Schema Sync vs. Data Sync

A common point of confusion: Metabase's schema sync is not copying your data. It's reading metadata about your tables (what tables exist, what columns they have, what types they are). Your actual data stays in your database and is only queried when a user runs a question or loads a dashboard.

---

Database-Level Permissions in Metabase

After connecting a database, you control which Metabase users can query which tables through Metabase's permission system (separate from database-level permissions).

Metabase's permissions are configured in Admin → Permissions and work at the group level:

For embedded deployments with row-level security (data sandboxing), permissions are configured separately to restrict which rows a user can see based on their user attributes.

---

Adding Multiple Databases

Metabase can connect to multiple databases simultaneously. There's no limit on the number of database connections. Users can query across databases (within their permission boundaries) and create dashboards that pull from multiple sources.

Common multi-database patterns:

---

Troubleshooting Connection Issues

"Connection refused" The database is not reachable at the specified host and port. Check:

"Authentication failed" The username or password is incorrect, or the user doesn't have permission to connect to the specified database. Verify with a direct database client using the same credentials.

"SSL connection required" The database requires SSL but Metabase isn't configured to use it. Enable SSL in the advanced connection settings.

"Schema sync is taking a long time" Normal for databases with hundreds of tables. Large schema syncs can take 10–20 minutes on first connection. Subsequent syncs are faster because Metabase only processes changes.

Tables are not appearing after adding the database Wait for the initial schema sync to complete. Check Admin → Databases and look at the sync status for your database. You can also trigger a manual sync from this page.

Can't find tables the user should have access to Verify the database user's permissions directly in the database. Remember to grant DEFAULT PRIVILEGES for future tables in PostgreSQL, or the user won't see tables created after the grant was made.

---

Keeping Connections Secure

Rotate passwords regularly — Metabase stores database credentials encrypted in its application database. When you rotate a database password, update the connection in Metabase Admin before the old password expires.

Use a secrets manager — For self-hosted deployments, consider passing database credentials via environment variables sourced from a secrets manager (AWS Secrets Manager, HashiCorp Vault) rather than hardcoding them.

Audit connection usage — Metabase's audit log (Pro/Enterprise) records who ran which queries against which database. This helps identify unusual query patterns or unauthorized access attempts.

Principle of least privilege — The read-only user should only have access to the schemas and tables it needs. If Metabase only needs access to a reporting schema, don't grant access to the entire database.

---

Summary

Connecting a database to Metabase takes under five minutes once you have the credentials ready. Create a dedicated read-only user, configure network access, and enter the connection details in the Admin panel. Metabase syncs the schema automatically after connection, making tables available immediately in the query builder. For production deployments, enable SSL, use a dedicated credentials user, and configure Metabase's permission system to control which users can access which data.