Connect Metabase to PostgreSQL with read-only access

Configure Metabase analytics on PostgreSQL with scoped read-only credentials, explicit views, TLS and denied-write tests across query and export paths.

Last updated

In short

  • A read-only database role is the primary protection against writes.
  • Metabase permissions and database privileges protect different boundaries.
  • Write features need a separate deliberate connection and entitlement review.
On this page (7)

Integrations · Part of Metabase

Separate the analytics connection from the application database

Metabase has its own application database for questions, dashboards, users and configuration. It can also connect to PostgreSQL as an analytical datasource. Those are different database roles and recovery responsibilities. This guide concerns a read-only datasource connection, not the internal Metabase application database.

This is a reference procedure with acceptance checks, not a tested configuration. Pin the Metabase release and edition, PostgreSQL major version and analytical schema. The PostgreSQL connection documentation lists supported connection features and version considerations for the selected Metabase release.

Expose an intentional analytical surface

A dedicated reporting schema or set of views can reduce the amount of operational data the BI tool needs to see. Decide which fields belong in analytics before granting access. A hidden column in the Metabase interface is not equivalent to a database privilege boundary.

Data object Intended exposure Example decision
Order summary view Approved business metrics Include date, region and net amount
Customer contact table Restricted Exclude from the analytics role unless needed
Authentication tables None Never part of general BI access
Audit records Separate controlled use Review identifiers and retention
New tables Denied until approved Avoid automatic broad future grants

If a reporting view depends on underlying tables or functions, review its security semantics for the PostgreSQL version in use. Views are useful interfaces, but their ownership and execution behavior still need database review.

Grant the minimum database permissions

Metabase’s database-privilege guidance recommends a dedicated user with minimum read access. PostgreSQL’s GRANT reference defines the distinct database, schema and object permissions involved.

Capability Intended permission Denied capability
Connect Connect to the selected database Connect to unrelated databases where not needed
Resolve reporting objects Usage on approved schema Create arbitrary schema objects
Query approved data Select on named views or tables Insert, update, delete and truncate
Discover metadata Necessary catalog visibility Administrative or superuser privileges
Future schema changes Reviewed grant update Uncontrolled access to newly sensitive tables

Avoid granting ownership or a broad administrative role. Also inspect inherited role memberships, public privileges and callable functions; a nominally read-only role can still have a write path through an explicitly granted function. Use the actual datasource credential for acceptance tests, not an administrator’s convenient session.

Configure the connection and limits

Set the hostname, port, database and dedicated credential in Metabase. Use the appropriate TLS mode and certificate trust for the network boundary. Restrict PostgreSQL network access to the Metabase runtime and approved operators. A successful connection test does not prove the credential is limited to the intended objects.

Decide whether queries run against the primary database or a reporting replica. A replica can reduce some workload contention, but replication lag changes data freshness and recovery behavior. Define a visible freshness expectation for dashboards rather than assuming that every result is current to the second.

Set operational query limits appropriate to the workload, including timeout and connection budget. A read-only query can still consume substantial resources or hold a long snapshot. Test representative dashboard refreshes concurrently with normal application activity before expanding access.

Keep write features outside this connection

Metabase supports features that intentionally write data, including actions, uploads, persistence and transforms in applicable versions and editions. The privilege documentation recommends separate writable connections for those use cases. Leave them unavailable on this connection unless a separately reviewed design requires them.

Authentication-provider integration, database impersonation and advanced permission features can have paid-plan requirements. Record the actual edition rather than treating all permission mechanisms as available in the base distribution. A shared datasource credential also means PostgreSQL may see one service identity for many Metabase users; end-user isolation must be designed accordingly.

Run query, export and denied-access checks

Create synthetic orders for two departments and one restricted contact record. Define the expected totals and which user may see each dataset.

Check Passing evidence
Approved dashboard Matches known synthetic totals
Direct SQL with datasource credential Can read only approved objects
Attempted write Database rejects the operation
Restricted table query Database denies access
Metabase user without collection access Cannot open, export or share the restricted question
Subscription or public link Does not bypass the intended data boundary
Expensive query Stops or is controlled within the agreed limits
Newly created sensitive table Remains inaccessible until reviewed

Test downloads and scheduled delivery as well as the dashboard screen. A user may lack interactive access while a subscription still sends data to an old address; include those paths in offboarding.

Preserve and recover the analytical service

Back up Metabase’s application database and the secrets needed to recover datasource configuration. Preserve reporting-view definitions and database grants as reviewed configuration. The source database needs its own backup and recovery process; exporting a dashboard does not back it up.

For rollback, disable the new connection and remove only the reviewed grants that were introduced, after checking shared dependencies. Do not drop a role or view that another integration uses without an impact review. After upgrades or schema changes, rerun the synthetic totals, denied-write and restricted-data checks. The connection is accepted when it provides useful analytics while database-level evidence confirms the intended read-only boundary.

Sources and further reading

Use the linked documentation to confirm the version, edition and contract that apply to your project.

Scope our database analytics

Bring the analytical tables or views, sensitive fields, dashboard freshness target and Metabase edition.