How Metabase database connections work in a self-hosted deployment
A team that needs governed dashboards over a warehouse it already runs can connect a self-hosted Metabase to that warehouse through an official driver or a community driver. Metabase maintains official drivers for Athena, BigQuery, ClickHouse, Databricks, Druid, MongoDB, MariaDB, MySQL, Oracle, PostgreSQL, Presto, Redshift, Snowflake, SparkSQL, SQL Server, SQLite, Starburst and Vertica. Databases outside that list may be reachable through community drivers, which Metabase documents separately. The first step is to confirm which engine the warehouse runs and whether it appears on the official list, because that decision sets the support path before any connection is configured.
In a self-hosted deployment, the connection runs from the Metabase server to the database. The Metabase process, packaged as a JAR, opens the connection, sends queries and receives results, so the network path that matters is between the Metabase host and the database listener. Firewall rules, DNS names, TLS settings and the database account Metabase uses all sit in the client's own infrastructure, and the warehouse data stays there too. Users' browsers talk to Metabase, not to the warehouse. Metabase keeps its own metadata in the application database, which is a separate component from the warehouse connection. Ask the team that owns the warehouse to confirm the host and port the Metabase server will use and whether the account is read-only.
Community drivers need more planning than official ones. Before committing to one, confirm which Metabase version it targets, how it handles the database's authentication method, and who will patch it when the database or Metabase is upgraded. Test the driver against a copy of representative tables and the queries analysts will run, including date handling, large result sets and any unusual column types. Record the driver version alongside the Metabase version so an upgrade does not silently break a connection. If neither your team nor a partner can maintain the driver, treat that database as a higher risk connection and plan a fallback, such as a supported export into a database with an official driver.
Support for official drivers is a plan question, not a driver question. Metabase states that customers on Pro and Enterprise get official support for its official drivers, and that it supports each database from the oldest supported version through the latest stable version. According to Metabase's pricing page, Pro costs $575 per month, or $517.50 per month billed yearly, with the first 10 users included. Because Metabase names Pro and Enterprise for that support, a team on Open Source or Starter should confirm in writing what help it can expect for a driver problem. Ask for the support terms in the plan and in any quote, and confirm the community driver position separately, since a driver's presence on a list does not by itself establish who answers when a connection fails.
What you need in place before adding a database connection
Five items decide whether a self-hosted Metabase can connect to a database and stay supported once it does. Each has an owner and a check the team can run before the connection is created, so problems surface during planning instead of during a live analytics rollout.
Supported Metabase version
Confirm that the Metabase version you run is inside its support window on Metabase's version support page. LTS releases are supported for 14 months, while non-LTS releases usually reach end of life after 2 months. Metabase 64 is an LTS release with end of life on 1 December 2027, and Metabase 65 was released on 12 October 2026. Record the end-of-life date of the version you plan to run before you add connections.
Network path to the database
Confirm that the Metabase host can open a connection to the database's listening port through every firewall, security group and route between them. Ask the database owner for the port and the host name the database presents, because Metabase cannot query a database it cannot reach. Test from the Metabase host itself, since the application makes the connection from there. Check name resolution and any TLS requirement the database enforces.
Read-only database account
Create a dedicated database account for Metabase with read-only privileges limited to the schemas and tables analysts need. Verify it by signing in with that account, confirming that writes are rejected and that objects outside the approved schemas are not visible. Do not reuse an administrator or application account, because every saved question and connection then runs with that account's rights.
Database version within vendor support
Confirm that the database version is still supported by its vendor, using the vendor's published support schedule. Metabase says it supports each database from the oldest supported version through the latest stable version. Check the running version with a query against the target environment rather than trusting the install record, and note any version the database owner plans to retire during the rollout.
Plan choice for official drivers
Confirm which plan the instance runs before adding connections, because Metabase's official support for its official drivers is limited to Pro and Enterprise customers. Open Source and Starter instances should not expect that support. Databases outside Metabase's official driver list may need community drivers, which Metabase documents separately, so decide on the plan and the driver source together and record both in the change request.
Which databases Metabase supports with official drivers
Five official drivers connect Metabase to managed analytics services: Athena, BigQuery, Databricks, Redshift and Snowflake. Each service is run by a cloud provider or vendor, so the connection work centers on network paths, credentials and access policy. Your team usually spends less time on database administration and more time on identity and scope.
- Athena and BigQuery query data in object storage or managed tables, so your team's partitioning and query scoping choices shape both performance and spend.
- Redshift is reached through your AWS account, so VPC routing, IAM roles and security group rules decide whether Metabase can connect at all.
- Snowflake and Databricks use vendor-specific authentication and compute settings, which the Metabase connection form exposes as fields you must fill in correctly.
- Service accounts should be read-only, with grants limited to the schemas that saved questions and dashboards require.
Confirm the current driver list and the version range each driver supports in the Metabase connecting docs before you plan a cloud connection.
Six official drivers cover the relational engines that many organizations already run for applications: MariaDB, MySQL, Oracle, PostgreSQL, SQL Server and SQLite. These connections often point at live transactional systems, so the central planning question is how reporting load and access will be controlled. Read-only access and a replica or reporting copy usually matter more than the connection string itself.
- PostgreSQL is released under the PostgreSQL License, a permissive open source license similar to the BSD or MIT licenses. Teams often run the same PostgreSQL service for Metabase's application database, so reporting load should be separated from it.
- MariaDB and MySQL share a connection model, but your team should confirm the exact driver version and character set handling against the Metabase docs.
- Oracle and SQL Server are commercial databases. Reporting access, licensing and support terms come from the vendor, so confirm entitlements with the database owner before rollout.
- SQLite stores data in a local file, so the Metabase process needs file permissions and a stable path, and it suits smaller datasets.
Test saved questions against a replica or reporting copy before pointing production dashboards at a transactional database.
Seven official drivers serve query engines and analytical stores that read large or federated datasets, along with MongoDB, which holds documents instead of tables. Many of these systems are clusters your team operates, so the connection depends on how that cluster is designed, sized and secured. Reachability from the Metabase host and query concurrency are common early constraints.
- ClickHouse server is open source under the Apache License 2.0, and ClickHouse Inc. sells ClickHouse Cloud separately. A self-hosted cluster needs its own replication and backup plan.
- Presto and Starburst query other sources, so access to each underlying catalog depends on credentials and rules configured in the engine.
- SparkSQL, Druid and Vertica require network access from the Metabase host and capacity sized for the number of dashboards users open at once.
- MongoDB stores nested documents, so confirm how fields and arrays appear as tables in Metabase before you build questions on them.
Ask each engine's maintainer which versions they support, then confirm the matching driver coverage in the Metabase connecting docs.
What official driver support depends on
Official driver support depends on your Metabase edition, not only on the database you connect. Metabase states that customers on Pro and Enterprise receive official support for its official drivers. Open Source and Starter deployments do not carry that support commitment, so a team running the open source edition against PostgreSQL, Snowflake or SQL Server uses the same driver code but has no stated support route to Metabase for driver issues. Before you buy, ask Metabase in writing which edition covers each driver on your list, and confirm that the answer applies to the driver version you plan to run.
The Pro plan is the lowest paid tier that carries this commitment. The Metabase pricing page lists Pro at $575 per month, or $517.50 per month billed yearly, with the first 10 users included and additional users at $12 per month. Enterprise is priced by quote starting at $20,000 per year. These are licence fees paid to Metabase. Your team or partner still pays separately for hosting, the database servers, the application database and the work to upgrade and test them. When you request a quote, ask whether the price changes with user count or billing term, and whether any driver you depend on is outside the edition you are pricing.
The database's own lifecycle sets the scope of what Metabase can support. Metabase supports each database from the oldest supported version through the latest stable version, so a database version that its vendor has retired can fall outside what you can reasonably expect Metabase to help with. For example, the PostgreSQL versioning policy lists major versions 14 through 18 as supported, with version 14 reaching end of life on November 12, 2026, and versions 13 and earlier unsupported. An illustrative case: if your PostgreSQL server runs version 13, you should expect to upgrade the database before you raise a driver ticket. Check the vendor's lifecycle for each database, because it can differ from Metabase's own dates.
Build the answer into your connection inventory. For each connected database, record the exact server version, the Metabase driver name, the edition that covers that driver, and the date the database vendor ends support for that version. Databases on Metabase's official list are covered by this commitment only on paid editions, and databases outside that list may depend on community drivers, which Metabase documents separately. Ask Metabase what support, if any, it offers for community drivers before you rely on one. Review the inventory whenever a database vendor announces an end-of-life date, and plan the database upgrade and the matching Metabase test run before that date arrives.
How to add a database connection to self-hosted Metabase
This sequence takes an admin from confirming driver support to a verified connection, so the agreed schemas appear in Metabase with metadata that matches the source system. Each step ends with a check that the reader can repeat before users query the data.
Confirm driver support before any setup
The admin checks the database against Metabase's official driver list, which includes PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, Snowflake, BigQuery and others. If the database is not on that list, the admin identifies a community driver, which Metabase documents separately, and records it as unsupported by official channels. Official support for official drivers is included with Pro and Enterprise plans, so the admin confirms what the organization's plan covers. The step is done when the driver name, the database version and the plan are written down, and the version falls within the range Metabase says it supports.
Create a read-only database user
A database administrator creates a dedicated user for Metabase with read access only, granted on the schemas and tables the organization agreed to expose. Illustrative example on PostgreSQL: the user receives connect and usage rights on the agreed schema and select rights on its tables, with no write, DDL or superuser privileges. The administrator then signs in as that user from a SQL client and attempts an insert and a select on a schema outside the agreement. The step is complete when the agreed tables return rows and both the write and the out-of-scope query fail.
Open the database settings in Metabase admin
A Metabase administrator signs in to the instance, opens the admin settings and goes to the databases section to add a new database. The admin picks the driver confirmed in the first step from the list of options. Before entering connection details, the admin confirms that the Metabase instance is running on the production application database chosen for this deployment, because connection settings are stored there. The step is done when the new database form loads for the chosen driver and no unexpected driver options appear.
Enter host, port and credentials
The admin enters the host name or address, port, database name and the read-only user's credentials in the form. The network path from the Metabase server to the database must already be open, which is usually a firewall or security group rule that the infrastructure team owns, and the admin should confirm whether TLS is required for the connection. The admin saves the connection and reads any error that appears, since authentication, network and TLS failures are reported differently. The step is complete when the connection test succeeds and the database appears in the list of databases.
Set sync and scanning options
The admin chooses how often Metabase syncs table and column metadata and how it scans field values, and limits the scope to the agreed schemas where the form allows. Frequent syncs and value scans add load to the source database, so the database owner should review these settings with the admin before saving. The admin should confirm the schedule with the database owner and record the choice. The step is done when the sync settings are saved and the database owner has approved the load they create on the source system.
Verify synced metadata against the source
After the first sync completes, the admin opens the data model view and checks that only the agreed schemas appear, and that tables and column names and types match what the database owner reports. Any table from an out-of-scope schema, or any missing table, means the sync scope or the user's grants need correction before users see the data. The admin reruns the check after the scheduled sync to confirm that metadata stays consistent. The step is complete when the table and column lists match the agreed scope and the source definitions.
Run a test query in the query builder
The admin opens the query builder, selects a table from the agreed scope, and runs a count of rows with no filters. The database owner runs the same count directly against the source system, using the same table and any agreed filter, and both results are compared. A matching count confirms that the connection, the read-only user and the metadata all point at the intended data. The step is done when the Metabase count equals the source count, and the admin records both numbers with the date of the check.
Which connection settings map to which database objects
This table maps each Metabase connection setting to the database object, account or Metabase object it refers to, along with a check to run before users rely on the connection. Confirm field labels in your Metabase version and driver, since names can differ between releases. The main takeaway is that the database account and schema filter determine what data Metabase can reach, so check them first.
| Setting | Database object or account it refers to | Check before go-live |
|---|---|---|
| Host | The server name or address of the database instance that Metabase opens a network connection to | Resolve the name from the Metabase host itself and confirm it matches the server certificate if TLS is on |
| Port | The port the database engine listens on for client connections on that instance | Confirm the port in the database server configuration and allow it only from the Metabase host |
| Database name | The logical database inside the server that Metabase reads for tables and fields | Point at an analytics database or replica agreed with the data owner, not an application's live write path |
| Schema filter | The schemas (namespaces) inside the database that Metabase includes or excludes when syncing | List the schemas in the database and confirm the included and excluded sets match what the data owner approved |
| Credentials | A database user or role that Metabase logs in with, separate from any Metabase user account | Grant read-only privileges on approved schemas, confirm the account cannot write or alter tables, and name a rotation owner |
| SSL option | The TLS setting for the connection, tied to the server's certificate and the CA trust store on the Metabase host | Confirm the engine accepts TLS, choose the verification mode your policy requires, and test from the Metabase host |
| Sync schedule | How often Metabase reads table and field metadata from the database, stored in the Metabase application database | Agree the schedule with the database owner so syncs do not add load to production, then watch the first runs |
| Access scope | Metabase permission groups that decide which databases, schemas and tables each user can query | Set data permissions per group; row and column level controls need a Pro or Enterprise plan, so confirm your plan first |
How to secure a database connection from Metabase
A Metabase connection is only as tightly scoped as the database account behind it and the people allowed to change it. These cards cover the account, grants, transport, authentication, admin access and plan limits that together define what a self-hosted Metabase can read and who can alter that access.
Dedicated read-only account per connection
Create a separate database login for each Metabase connection and give it read-only privileges only. Do not reuse an application account, a migration account or a personal login, because a shared credential makes it impossible to tell which tool ran a query and forces every connection to share one blast radius. Rotate the password on a schedule your team can actually follow, store it in your secrets process, and confirm that the account cannot write, drop or alter objects by testing those statements directly against the database.
Least-privilege schema grants
Grant the Metabase account access only to the schemas, tables and views that analysts need for saved questions and dashboards. Review grants for default privileges, which can expose new tables automatically, and check whether sensitive columns such as personal identifiers or free-text notes are reachable. Where a column must stay hidden, a database view that omits it is often easier to audit than a long list of table grants. Repeat the review whenever new schemas are added.
Encrypted transport where supported
Require TLS between Metabase and the database wherever the official driver and the database server both support it, and enforce that setting on the server side so a misconfigured client cannot fall back to plaintext. Confirm the driver's SSL options for your database version, decide whether certificate verification is required, and plan how root certificates are distributed to the Metabase hosts. Test the connection with verification enabled before go-live, because a connection that only works with verification turned off hides a trust problem.
Choosing a supported authentication method
PostgreSQL documents password, GSSAPI, LDAP, certificate and OAuth client authentication methods. ClickHouse supports LDAP, Kerberos, SSL X.509 certificates, an HTTP authenticator and JWT as external authenticators. Choose a method that the database's own documentation supports for the version you run, configure it on the database side, and confirm that the chosen driver can use it. Then test the login from a Metabase host and record the result, since a method that works in a lab can fail against your directory or certificate chain.
Restricting who manages connections
Limit database connection creation and editing to a small group of Metabase administrators, because anyone who can change a connection string or driver setting can redirect Metabase to another host or account. Review the admin list during access reviews and remove people who change roles. Confirm in the Metabase documentation for your version which permissions control connection management, and record who holds them. Treat the Metabase application database itself as sensitive, since it stores connection credentials.
Row and column permissions need a paid plan
Metabase's pricing page places row and column level permissions in the Pro and Enterprise plans, so open source and Starter deployments cannot enforce them inside Metabase. If different groups must see different rows or columns from the same connection, either budget for a paid plan or enforce those limits in the database with grants and views. Confirm the current pricing page before deciding, because plan contents can change and the decision affects how you design every connection.
Keeping connected databases on versions Metabase still supports
A Metabase connection can stop working when the database behind it leaves its support window, even if Metabase itself is current. The team should therefore track two lifecycles: Metabase's own version support and the lifecycle of each connected database. Start with an inventory of every connected instance, its major version, and whether Metabase points at a primary, a replica or a managed endpoint. For PostgreSQL, the versioning policy lists versions 14 through 18 as supported. Version 14 is supported until November 12, 2026, 15 until November 11, 2027, 16 until November 9, 2028, 17 until November 8, 2029 and 18 until November 14, 2030. Versions 13 and earlier are unsupported, so any Metabase connection to them carries growing risk without vendor fixes.
ClickHouse follows a different pattern, so the same inventory needs a different rule. Its security policy lists versions 26.9, 26.8, 26.7 and 26.3 as currently supported with security updates, and marks all other versions unsupported. Its releases page shows 26.9 as the latest stable line, with 26.8 and 26.3 as LTS lines. Check each ClickHouse cluster's exact version against these lists and record which release line it follows. A cluster on an unlisted line is a planning item even when queries still succeed through Metabase. Confirm the current lists on the security policy page before each review, because supported lines change as new releases ship.
Plan upgrades so the database change is tested with Metabase before production is touched. The ClickHouse production FAQ recommends a pre-production environment with representative data and queries, and reading the changelog before upgrading, because minor backward-incompatible changes can occur. Build a staging copy of the database, connect a Metabase instance running the same version as production, and run the saved questions, dashboards and native queries that people depend on. Compare results, column types, filter behavior and run times. Record any change in a query result, then decide whether to fix the query, the data model or the upgrade plan.
Before cutover, make the rollback path concrete. Back up the database and the Metabase application database, and confirm that the backup can be restored. The ClickHouse backup documentation warns that a backup never test-restored will probably not restore properly when needed, and it recommends restore tests on spare clusters. For PostgreSQL, pg_upgrade, dump and restore, and logical replication are the documented major upgrade routes, and logical replication can keep downtime to several seconds. Agree who approves the change window, which Metabase checks run after cutover, and who reverts the connection if results differ. Write these steps down before the change date.
Common database connection failures and how to fix them
This table pairs each connection symptom with its likely cause, a check that confirms it, and the fix. Run the checks from the Metabase host itself, since that is the network and credential path Metabase uses. Most failures trace back to network reachability, credentials and privileges, or a driver and server version pair outside the supported range.
| Symptom | Likely cause | Check that confirms it | Fix |
|---|---|---|---|
| Connection timeout when adding or syncing a database | Network route blocked, wrong host or port, or a database firewall that does not allow the Metabase server | Open a connection to the host and port from the Metabase host using the database's own client | Correct the host and port, open the route, and allow the Metabase server in the database firewall |
| Authentication rejected | Wrong username or password, an account without login rights, or a server authentication method the driver cannot negotiate | Log in with the same credentials from the Metabase host using the database's own client and review its authentication docs | Correct the credentials, grant login rights, or move the account to a supported method such as SCRAM |
| Schema or tables missing after sync | The Metabase user lacks privileges on the schema, schema filters exclude it, or the sync has not run | Query the database catalog as the Metabase user and compare schema filter settings in the database admin page | Grant read privileges on the schema, adjust schema filters, then run a manual sync |
| Driver version mismatch | The database version is outside the range Metabase supports, or a community driver is used where an official driver exists | Compare the database version with Metabase's documented supported versions and check the official driver list | Upgrade the database to a supported version or upgrade Metabase, and switch to the official driver where one is listed |
| SSL handshake errors | The server requires TLS but SSL is off in the connection settings, the certificate chain is not trusted by Metabase, or the hostname does not match the certificate | Connect with the database's client using the same CA file and hostname, then review the SSL options in the connection form | Enable SSL in the connection options, add the CA to the truststore Metabase uses, and connect by the certificate hostname |
| Connection drops or fails under load | The database connection limit is reached, or a pooler or proxy between Metabase and the database closes idle connections | Compare the current connection count with the server limit during a dashboard load and check proxy idle timeouts | Lower concurrent query load, raise the server limit within capacity, or add a pooler such as PgBouncer where the database supports it |
| Query results differ from the source system | Different session time zone, a restricted role with row or column limits, or a snapshot that lags the source | Run the same SQL in the source client as the same database role and compare the time zone setting | Align the session time zone, review the role's permissions, and record which system is the source of truth |
Questions teams ask before connecting Metabase to a database
Does my database need an official Metabase driver or a community driver?
If your database is on Metabase's official list, use the official driver. Metabase maintains official drivers for Athena, BigQuery, ClickHouse, Databricks, Druid, MongoDB, MariaDB, MySQL, Oracle, PostgreSQL, Presto, Redshift, Snowflake, SparkSQL, SQL Server, SQLite, Starburst and Vertica. Databases outside that list may be reachable through community drivers, which Metabase documents separately. Community drivers do not carry Metabase's official driver support, so before you depend on one, confirm who maintains it, which database versions it has been tested against, and who fixes it when a Metabase upgrade breaks it.
Can Metabase Open Source connect to an officially supported database?
Yes, in principle. A self-hosted Open Source instance can connect to a database on the official driver list. What Open Source does not include is Metabase's official support for those drivers, which Metabase says it provides to Pro and Enterprise customers. Metabase's pricing page lists Pro at $575 per month, or $517.50 per month billed yearly, with the first 10 users included. Before you rely on Open Source for a production warehouse, confirm the driver version you need, the database version range it covers, and whether your own team will handle driver issues without vendor support.
What makes a Metabase database connection project take longer?
Effort rises with five factors:
- Number of sources: each database needs its own account, network path and test.
- Schema complexity: wide tables, many joins and unclear ownership slow modeling and permission design.
- Authentication method: password accounts are the simplest, while Kerberos, certificate or directory-based sign-in adds configuration and testing.
- Network path: private subnets, VPN, proxies and TLS requirements each need network owner time.
- Governance rules: change approvals, separate environments and audit expectations add review steps.
Ask the partner or your own team to show how each of these factors is counted in the estimate.
Which people do we need from our side for a database connection?
Three roles usually need to be named before work starts:
- Database administrators create read-only service accounts, grant schema privileges, confirm supported versions and agree on connection limits.
- Network owners approve firewall rules, private routing, DNS entries and TLS settings between the Metabase host and the database.
- An identity owner decides how Metabase users and groups map to data access, and who approves changes to those mappings.
If you plan to use row or column level permissions, Metabase lists those as Pro and Enterprise features, so the identity owner should confirm the plan tier before design begins.
Can our internal team connect Metabase to a database without help?
Often yes, for a simple case. One official-driver connection to a database on a network your team already manages, using a read-only account and no row-level rules, is a reasonable first project for an internal team. The work gets harder when you add several sources, private networks, directory-based sign-in, multiple environments or formal change control. Those tasks need the same people to coordinate across database, network and identity teams. If you need official driver support from Metabase, that is available on Pro and Enterprise, so a Pro or Enterprise decision belongs in the same plan as the connection work.
What should a written scope for database connections include?
A useful written scope lists each database, its driver (official or community) and the version range you need. It should name the environments, the network path for each source and the authentication method per connection. Add the permission model, the Metabase plan tier required for the features you plan to use, and who owns credentials and rotation. The scope should also state the testing steps, the sign-off owner, the handover material and what is excluded. Ask the provider to show which items are one-time setup and which items recur, such as credential rotation and driver updates.
What breaks when a database version changes under Metabase?
Metabase says it supports each database from the oldest supported version through the latest stable version, so confirm that range covers your environment before you upgrade the database. Major database upgrades can change query behavior, data types or driver expectations. Test your most important saved questions and dashboards against a staging copy after each database upgrade. Before any Metabase upgrade, back up the application database, because Metabase runs its application database migrations automatically during upgrades.
How DeployOpen scopes and delivers Metabase database connections
DeployOpen scopes each Metabase database connection against the warehouses and databases your analysts use, then confirms which use official drivers and which need community drivers. Work runs in your own infrastructure under a written fixed scope that also states what official driver support depends on, including your Metabase plan.
How we scope
- Inventory every warehouse and database that analysts query, with its version and hosting model.
- Map each source to an official driver or a community driver, and record which support terms apply.
- Confirm your Metabase plan and the driver support that plan includes before any build begins.
How we build
- Create the network paths, service accounts and least-privilege read roles Metabase needs for each source.
- Connect each source in a pre-production Metabase, then test queries, sync and permission scoping with representative data.
- Check each database version against Metabase's supported range before cutover, and record the result.
How we hand over
- A written connection register listing each source, driver type, owner, credential location and network path.
- A runbook for adding a source, rotating database credentials and handling a driver version change.
- Records of tested connections and permission checks, prepared for your internal reviewers and any external assessment.
How we support
- Ongoing support, upgrade planning and continuous testing are available as retainers after handover.
- Review driver and database version changes before each Metabase upgrade, so connection changes reach production only after review.
- Ask Metabase or the driver documentation to confirm support for any database that is not on the official list.
