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

Installing the DuckDB/MotherDuck Driver

Self-hosted Metabase

1. Download the latest driver release
2. Copy the downloaded .jar file into your Metabase plugins directory:
   • Standard installation: If your metabase.jar is located at ~/app/metabase.jar, place the driver in ~/app/plugins/
   • Mac App: The plugins directory is ~/Library/Application Support/Metabase/Plugins/
3. Restart your Metabase instance for the new driver to be detected

Metabase Cloud

Coming soon! Support for Metabase Cloud is under development and coming soon.

Connecting to DuckDB/MotherDuck

After installing the driver, you can add DuckDB or MotherDuck as a data source in Metabase.

1. Log in to Metabase with admin credentials
2. Navigate to Admin Settings > Databases > Add Database
3. Select DuckDB as the database type

note

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:

1. Database name: Enter md:[database_name] where [database_name] is your MotherDuck database name
2. MotherDuck token: Paste your MotherDuck token (retrieve from the MotherDuck UI)
3. Configuration: Enable old_implicit_casting (recommended) for proper datetime handling

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

Connecting to a Local DuckDB database

To connect to a local DuckDB database:

1. Database file: Enter the full path to your DuckDB file (e.g., /path/to/database.db)
2. Configuration: Enable old_implicit_casting (recommended) to ensure proper datetime filtering
3. Additional settings:
   • Read only: Toggle as appropriate for your use case
   • Naming strategy: Choose your preferred table/field naming strategy

note

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.