To give your team dashboards over your Django app’s PostgreSQL database, connect Metabase to it with a read-only role that you create in a Django migration. Run Metabase on Metabase Cloud or as a service in your docker-compose.yml, and give it the host and database name from your DATABASES setting. Your team then builds charts with the query builder or SQL, and a dashboard subscription sends them by email or Slack every week, with no new code in your app.
Metabase’s Open Source edition is free to self-host with unlimited users, and dashboard subscriptions come with every plan. Metabase Cloud Starter costs $100 a month with 5 users included, and it starts with a 14-day free trial (prices checked on November 12, 2026). If you’re still choosing between dashboards built into your app and a BI tool, start with our guide to internal dashboards. This recipe also exists for Rails, Next.js and Go.
How do I create a read-only Postgres user for Metabase in Django?
Metabase recommends a dedicated metabase database user with read-only access. Create it in a migration, so every environment gets the same role and your team reviews it like any other change. Let Django create an empty migration in one of your apps, here core:
python manage.py makemigrations core --empty --name metabase_readonly_role
Fill in the file as below, keeping the dependencies that Django wrote. The SQL follows the “Minimum database privileges” example in the Metabase docs, with the option that grants read access to specific tables:
from django.db import migrations
CREATE_READONLY_ROLE = """
-- Roles belong to the whole PostgreSQL server, so create them only once.
DO $$
BEGIN
IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'analytics') THEN
CREATE ROLE analytics;
END IF;
IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'metabase') THEN
CREATE USER metabase; -- no password here: set it outside the migration
END IF;
-- Each environment has its own database name, so read it from the connection.
EXECUTE format('GRANT CONNECT ON DATABASE %I TO analytics', current_database());
END
$$;
GRANT analytics TO metabase;
GRANT USAGE ON SCHEMA public TO analytics;
-- List the tables your teams need. Leave out tables with password hashes, tokens or sessions.
GRANT SELECT ON TABLE public.core_order, public.core_customer TO analytics;
"""
REVOKE_READONLY_ROLE = """
-- Revokes the privileges in this database. The roles stay for other databases.
REVOKE SELECT ON TABLE public.core_order, public.core_customer FROM analytics;
REVOKE USAGE ON SCHEMA public FROM analytics;
DO $$
BEGIN
EXECUTE format('REVOKE CONNECT ON DATABASE %I FROM analytics', current_database());
END
$$;
"""
class Migration(migrations.Migration):
dependencies = [
("core", "0001_initial"),
]
operations = [
migrations.RunSQL(sql=CREATE_READONLY_ROLE, reverse_sql=REVOKE_READONLY_ROLE),
]
On PostgreSQL, Django runs each SQL string whole, so the DO block works, and %I needs no escaping because no parameters are passed. Roles belong to the whole server, and Django’s test runner applies your migrations to a test_ database on that server, so the migration creates each role only when it’s missing. current_database() names each environment’s database. Replace core_order and core_customer with the tables your teams need, leave out tables that hold password hashes, tokens or sessions, such as auth_user, and grant each new table in the migration that creates it. To create roles, your app’s database user needs the CREATEROLE attribute or superuser rights. If it has neither, ask whoever runs the database to create both roles, run GRANT analytics TO metabase and set the password. Then delete that GRANT analytics TO metabase; line from your migration, because PostgreSQL refuses it for a user without those rights, and refuses \password metabase too.
The password stays out of the migration and out of Git. Run the migration, then open psql with dbshell, which uses your DATABASES settings. Each database server keeps its own roles, so set the password on every server that Metabase connects to, such as production:
python manage.py migrate
python manage.py dbshell
At the psql prompt, run \password metabase and type the new password twice. psql encrypts the password before it sends it, so it doesn’t appear in your shell history or in the server log.
Where does Django keep the settings for Metabase’s connection form?
Django keeps its connection in the default alias of the DATABASES setting. Metabase needs the HOST, PORT and NAME values from your production settings, and for the username you use metabase, not the USER of your app.
If your app reads from a replica, DATABASES has a second alias for it, used by a router in DATABASE_ROUTERS. Give Metabase that alias’s HOST, so dashboard queries don’t add load to the primary. A replica accepts only read-only queries, so the migration runs on the primary. A streaming replica, such as a Cloud SQL read replica, then receives the new role and its password, so metabase can sign in there too. On a PostgreSQL replica, changes from the primary can cancel a long query. For a replica that serves dashboards, the PostgreSQL docs suggest a high max_standby_streaming_delay.
How do I run Metabase next to a Django app?
Metabase Cloud. Start a trial from the pricing page, and Metabase runs, backs up and upgrades the server for you. Metabase Cloud connects to your database from three fixed IP addresses in each region, so allow them in your database’s firewall or security group. If the database has no public endpoint, connect through an SSH tunnel, as Dashboards on a private database explains.
Docker Compose. Add Metabase to your app’s docker-compose.yml, with a small Postgres of its own for its application database, which holds Metabase’s users, questions and dashboards apart from your app’s data. This excerpt comes from Run Metabase in production with Docker, which explains every setting:
# Add to your docker-compose.yml (Postgres names changed to avoid clashes).
services:
metabase:
# Pin a full version. Replace it with the newest release in
# https://www.metabase.com/changelog/65
image: metabase/metabase:v0.65.4.1
restart: unless-stopped
ports:
- "127.0.0.1:3000:3000" # only this host can connect; put a reverse proxy with TLS in front
environment:
MB_DB_TYPE: postgres
MB_DB_DBNAME: metabaseappdb
MB_DB_PORT: 5432
MB_DB_USER: metabase
MB_DB_PASS_FILE: /run/secrets/metabase_db_password
MB_DB_HOST: metabase-postgres
MB_ENCRYPTION_SECRET_KEY: ${MB_ENCRYPTION_SECRET_KEY:?set MB_ENCRYPTION_SECRET_KEY in .env}
MB_SITE_URL: https://metabase.example.com
JAVA_OPTS: -Xmx2g
JAVA_TIMEZONE: UTC # match the time zone of your reports
secrets:
- metabase_db_password
mem_limit: 3g
depends_on:
metabase-postgres:
condition: service_healthy
healthcheck:
test: curl --fail -I http://localhost:3000/api/health || exit 1
interval: 15s
timeout: 5s
retries: 5
start_period: 5m
metabase-postgres:
image: postgres:17 # with postgres:18 and later, mount the volume at /var/lib/postgresql
restart: unless-stopped
environment:
POSTGRES_USER: metabase
POSTGRES_DB: metabaseappdb
POSTGRES_PASSWORD_FILE: /run/secrets/metabase_db_password
secrets:
- metabase_db_password
volumes:
- metabase_pg_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U metabase -d metabaseappdb"]
interval: 10s
timeout: 5s
retries: 5
volumes:
metabase_pg_data:
secrets:
metabase_db_password:
file: ./metabase_db_password.txt
Create the encryption key and the password file, then start Metabase, and Compose starts metabase-postgres with it. The >> adds the key to your existing .env file instead of replacing it, and both files should stay out of Git:
echo "MB_ENCRYPTION_SECRET_KEY=$(openssl rand -base64 32)" >> .env
openssl rand -base64 24 > metabase_db_password.txt
docker compose up -d metabase
Open Metabase through your reverse proxy, or at http://localhost:3000 on the Docker host, and create the first admin account. If your app’s Postgres runs in the same compose file, use its service name, such as db, as the host in the next step, not localhost, because Metabase connects from inside its own container.
How do I connect the Django database in Metabase?
Click the grid icon at the top right, go to Admin > Databases, click Add database and choose PostgreSQL. Fill in the form with your Django settings:
- Display name: any name, such as “Django app”.
- Host: the primary’s or the replica’s
HOST. - Port: the
PORT, usually5432. - Database name: the
NAME. - Username:
metabase. - Password: the password you set with
\password.
Keep Use a secure connection (SSL) on when your database supports it, as Metabase recommends, and turn on Use an SSH tunnel only for a bastion host. Click Save, and Metabase syncs the schema right away and then every hour by default, so each table that a later migration grants shows up on its own.
How do I build a first question and a dashboard?
Start with orders per week, from an Order model in core with a created_at field:
- Click + New > Dashboard, name it “Weekly metrics”, pick a collection and click Create.
- Click + New > Question and pick the Core Order table. Metabase shows
core_orderas Core Order andcreated_atas Created At, because it makes table and column names more readable by default. - In the Summarize step, pick Count of rows and group by Created At, then click by month and change it to week.
- Click Visualize, then Save, and save the question to the Weekly metrics dashboard. Place the card and save the dashboard.
Django names each table after the app label and the model, so Order in core is core_order. If your team prefers SQL, click + New > SQL query, run this query with the read-only role and save it to the same dashboard:
-- Orders per week in UTC, for this week and the 12 weeks before it. Weeks start on Monday.
SELECT date_trunc('week', created_at, 'UTC') AS week, count(*) AS orders
FROM core_order
WHERE created_at >= date_trunc('week', now(), 'UTC') - interval '12 weeks'
GROUP BY 1
ORDER BY 1;
PostgreSQL’s date_trunc starts weeks on Monday, while the query builder starts them on Sunday by default, so set First day of the week to Monday in Admin > Settings > Localization if you use both. Django’s PostgreSQL backend stores datetimes as timestamp with time zone. On these columns, date_trunc uses the session’s time zone, and Metabase sets it to the Report timezone on the same page when you choose one. The query passes 'UTC' to keep its weeks in UTC, so change it to the zone your app uses for its weeks.
How do I email or Slack the dashboard every week?
An admin sets up email or Slack once. On Metabase Cloud, Metabase manages an email server for you, so email works right away. On a self-hosted Metabase, go to Admin > Settings > Email, click Configure next to Self-Hosted SMTP and enter your SMTP server’s details. For Slack, go to Admin > Settings > Slack, click Create Slack App and install the app in your workspace. Then paste its Bot User OAuth Token into Slack bot user OAuth token and click Connect.
Then create the subscription on the dashboard:
- Open the dashboard and click the Subscriptions icon at the top right, next to the edit and sharing icons.
- Choose email or Slack, then add Metabase users by name, anyone else by email address, or a Slack channel such as #metrics.
- Set the frequency to Weekly, then pick the day and the time.
- Click Send email/Slack now to check the message, then save the subscription. The test goes to every recipient, so Metabase suggests that you test with only your own address first and add the team after.
Recipients don’t need a Metabase account, and they see the data that the subscription’s creator can see. You don’t need a refresh job, because Metabase runs the dashboard’s questions against your database each time it sends. An email can attach the results as .csv or .xlsx files, and any subscription can attach a PDF of the dashboard.
Next steps
- Database users, roles, and privileges
- Connect Metabase to PostgreSQL
- Run Metabase in production with Docker
- Dashboards on a private database
- Dashboard subscriptions and scheduled email and Slack reports
- Start free with Open Source or Metabase Cloud
- Internal dashboards: build them in your app or add Metabase
- The same recipe for Rails, Next.js and Go