Metabase
Metabase is an open source analytics/BI platform that provides intuitive data visualization and exploration capabilities. This guide details how to connect Metabase to both local DuckDB databases and MotherDuck.
Prerequisites
- Metabase installed (self-hosted)
- Admin access to your Metabase instance
- For MotherDuck connections: valid MotherDuck token
Metabase Cloud
Metabase Cloud does not currently support installing custom drivers. Support for the DuckDB/MotherDuck driver on Metabase Cloud is under development.
Until Cloud support is available, use Self-hosted Metabase to connect to DuckDB or MotherDuck.
Self-hosted Metabase
Install the DuckDB driver
- Dockerfile (bundled plugin)
- Manual
- Remote (SSH)
- Create a
Dockerfile
that includes the latest Metabase plus the DuckDB driver:
FROM eclipse-temurin:21-jre
ENV MB_PLUGINS_DIR=/plugins
RUN mkdir -p ${MB_PLUGINS_DIR} /app
# Latest Metabase
ADD https://downloads.metabase.com/latest/metabase.jar /app/metabase.jar
# Latest DuckDB driver
ADD https://github.com/MotherDuck-Open-Source/metabase_duckdb_driver/releases/latest/download/duckdb.metabase-driver.jar ${MB_PLUGINS_DIR}/
EXPOSE 3000
CMD ["java", "-jar", "/app/metabase.jar"]
- Build and run:
docker build -t metabase-duckdb:latest .
docker run -d --name metaduck -p 3000:3000 -e MB_PLUGINS_DIR=/plugins metabase-duckdb:latest
Tip: For reproducible builds, pin versions instead of latest
:
# Example of pinning versions (replace X.Y.Z)
ADD https://downloads.metabase.com/vX.Y.Z/metabase.jar /app/metabase.jar
ADD https://github.com/MotherDuck-Open-Source/metabase_duckdb_driver/releases/download/1.X.Y/duckdb.metabase-driver.jar ${MB_PLUGINS_DIR}/
Note: Use a Debian/Ubuntu-based JRE image (not Alpine) to avcodoid glibc issues with the DuckDB driver.
- Download the latest DuckDB driver
.jar
:
curl -L -o duckdb.metabase-driver.jar \
https://github.com/MotherDuck-Open-Source/metabase_duckdb_driver/releases/latest/download/duckdb.metabase-driver.jar
- Copy it to the Metabase plugins directory:
- Standard installation (example): If your
metabase.jar
is at~/app/metabase.jar
, place the driver in~/app/plugins/
mkdir -p ~/app/plugins
mv duckdb.metabase-driver.jar ~/app/plugins/
- On Mac: The plugins directory is
~/Library/Application Support/Metabase/Plugins/
(if you are using a Mac)
mkdir -p "${HOME}/Library/Application Support/Metabase/Plugins/"
mv duckdb.metabase-driver.jar "${HOME}/Library/Application Support/Metabase/Plugins/"
- Custom location or Docker: set
MB_PLUGINS_DIR
to point Metabase at your plugins directory and place the.jar
there (if you are using a custom location or Docker).
- Restart Metabase so it picks up the new plugin.
- SSH to the host and download to the plugins directory. Replace user/host and adjust
MB_PLUGINS_DIR
as needed.
ssh user@your-host "bash -lc '
set -euo pipefail
MB_PLUGINS_DIR=${MB_PLUGINS_DIR:-/app/plugins}
mkdir -p "$MB_PLUGINS_DIR"
if command -v wget >/dev/null; then
wget -qO "$MB_PLUGINS_DIR/duckdb.metabase-driver.jar" \
https://github.com/MotherDuck-Open-Source/metabase_duckdb_driver/releases/latest/download/duckdb.metabase-driver.jar
else
curl -L -o "$MB_PLUGINS_DIR/duckdb.metabase-driver.jar" \
https://github.com/MotherDuck-Open-Source/metabase_duckdb_driver/releases/latest/download/duckdb.metabase-driver.jar
fi
'"
- Restart Metabase on the remote host:
- systemd:
ssh user@your-host 'sudo systemctl restart metabase'
- Docker:
ssh user@your-host 'docker restart <metabase_container_name>'
Restart required: Metabase must be restarted after adding or upgrading plugins. Hot-reload of drivers is not supported.
Compatibility and upgrades: New DuckDB driver releases are designed to be backward compatible with recent Metabase versions. Upgrading to the latest driver is recommended for bug fixes and stability. If you run a significantly older Metabase version, validate in staging first.
Add your database connection
After installing the driver, you can add MotherDuck as a data source in Metabase.
- Log in to Metabase with admin credentials
- Navigate to Admin Settings > Databases > Add Database
- Select DuckDB as the database type
Since DuckDB does not do implicit casting by default, the old_implicit_casting
config is currently necessary for datetime filtering in Metabase to function. It's recommended to keep it set.
Connecting to MotherDuck
To connect to MotherDuck:
- Database name: In the Database file field, enter
md:[database_name]
where[database_name]
is your MotherDuck database name - MotherDuck token: Paste your MotherDuck token (retrieve from the MotherDuck UI)
- Configuration: Enable
old_implicit_casting
(recommended) for proper datetime handling
DuckLake on Metabase
DuckLake is supported with the DuckDB driver in Metabase. Use the latest DuckDB driver release and a DuckDB version that supports DuckLake (DuckDB v1.3.2 or newer is recommended).
MotherDuck-managed DuckLake
If your DuckLake database is managed by MotherDuck, you can connect the same way you connect to any MotherDuck database:
- Select DuckDB as the database type
- Database file:
md:[ducklake_database_name]
- MotherDuck token: paste your token
- Keep
old_implicit_casting
enabled (recommended)
No extra Init SQL is required. Query your tables normally in Metabase.
Own compute + DuckLake catalog (attach in Init SQL)
If you want Metabase’s embedded DuckDB to query a DuckLake stored externally, attach the DuckLake catalog in the connection’s Init SQL. This works for both MotherDuck-managed catalogs and self-managed catalogs.
- Init SQL for a MotherDuck-managed DuckLake catalog:
-- Attaches the DuckLake metadata catalog hosted in MotherDuck
ATTACH 'ducklake:md:__ducklake_metadata_[database_name]' AS dl1;
- Init SQL for a self-managed DuckLake catalog (local metadata DB) with S3 data path:
-- Replace the path to your DuckLake metadata DB and bucket prefix
ATTACH 'ducklake:/duckdb/my_ducklake_metadata.ducklake' AS dl1 (
DATA_PATH 's3://my_bucket/lake/'
);
Once attached, reference tables with the alias, for example: FROM dl1.my_table
.
Connecting to a Local DuckDB database
To connect to a local DuckDB database:
- Database file: enter the full path to your DuckDB file (e.g.,
/path/to/database.db
) - Configuration: enable
old_implicit_casting
(recommended) to ensure proper datetime filtering
DuckDB's concurrency model supports either one process with read/write permissions, or multiple processes with read permissions, but not both at the same time. This means you will not be able to open a local DuckDB in read-only mode, then the same DuckDB in read-write mode in a different process.
Configuration Best Practices
- Connection pooling: For production instances, set an appropriate connection pool size based on expected concurrent users
- Query timeouts: Configure timeouts in Metabase settings to prevent long-running queries from affecting system performance
- Data access: Use database-level permissions in Metabase to control who can access which data sources
Troubleshooting
Issue | Solution |
---|---|
Driver not detected | Ensure driver is in the correct plugins directory and Metabase has been restarted |
Connection failures | Verify database path (local) or database name and token (MotherDuck) |
Permission errors | Check file permissions for local databases |
Datetime filtering issues | Enable old_implicit_casting in the connection settings |
Add MotherDuck token in the connection string | Specify a correct MotherDuck token or MotherDuck database name after the md: prefix |
Updating the MotherDuck token
Metabase keeps long-lived database connections alive. When you update only the MotherDuck token while an existing connection is still cached, Metabase raises Connection error: Can't open a connection to same database file with a different configuration than existing connections
.
Use one of the following approaches to refresh the token successfully:
-
Add a cache buster while editing the database. Edit the connection under Admin Settings > Databases, then update both the Database file field and the MotherDuck Token field with a small cache-busting change (for example, append
?refresh=20250917
). Updating both values at the same time forces Metabase to treat the configuration as new. Save the connection, then optionally revert the fields to their clean values once the change is persisted. -
Restart Metabase before updating the token. Restart the Metabase service and, immediately after it starts, go straight to
/admin/databases
to update the token field. Do not open the Metabase home screen before editing the database connection, or the previous connection (with the old token) will be re-established.
Connecting to a Local DuckDB database
To connect to a local DuckDB database:
- Database file: Enter the full path to your DuckDB file (e.g.,
/path/to/database.db
) - Configuration: Enable
old_implicit_casting
(recommended) to ensure proper datetime filtering - Additional settings:
- Read only: Toggle as appropriate for your use case
- Naming strategy: Choose your preferred table/field naming strategy
DuckDB's concurrency model supports either one process with read/write permissions, or multiple processes with read permissions, but not both at the same time. This means you will not be able to open a local DuckDB in read-only mode, then the same DuckDB in read-write mode in a different process.