Metabase Databricks SQL Driver

A Metabase driver that connects to Databricks SQL Warehouses over JDBC, letting you query Unity Catalog tables and build dashboards on top of your lakehouse.

---

Why this exists

Metabase ships with a Spark SQL driver, but it does not speak the Databricks SQL Warehouse dialect: it has no notion of Unity Catalog, it does not handle the AuthMech=3 personal-access-token flow, and its date functions diverge from what Databricks Runtime actually accepts.

This driver extends Metabase's sql-jdbc base with the official Databricks JDBC driver and overrides the query processor where the two dialects disagree — date truncation, interval arithmetic, datetime-diff, regex functions, percentiles and schema introspection.

Compatibility

Component	Version
Metabase	v0.46.6.4
Databricks JDBC	2.6.36
Clojure	1.11.1
Driver	1.0.0-SNAPSHOT-0.0.2

The driver is compiled against a specific Metabase release. Driver interfaces change between Metabase minor versions, so a build targeting v0.46.x is not expected to load cleanly on v0.47+ without a rebuild.

Requires the Spark SQL driver. The plugin manifest declares a dependency on Metabase's built-in Spark SQL Driver, which must be available in the target instance.

Installation

1. Download databricks-sql.metabase-driver.jar from the releases page, or build it yourself.

2. Drop it into your Metabase plugins/ directory:

   cp databricks-sql.metabase-driver.jar /path/to/metabase/plugins/

3. Restart Metabase. Databricks SQL will appear in the database list under Admin → Databases → Add database.

Docker

FROM metabase/metabase:v0.46.6.4
COPY --chown=2000:2000 databricks-sql.metabase-driver.jar /plugins/databricks-sql.metabase-driver.jar

The repo ships this as Dockerfile.dev.

Configuration

Pull these values from your warehouse's Connection details tab in the Databricks workspace.

Field	Required	Default	Notes
Host	yes	—	Workspace hostname, no scheme. e.g. dbc-a1b2c3d4-e5f6.cloud.databricks.com
HTTP path	yes	—	e.g. /sql/1.0/warehouses/abc123def456
Personal Access Token	yes	—	Generated under User Settings → Developer → Access tokens
Catalog	yes	default	Unity Catalog catalog name
Schema	yes	default	Schema within the catalog

Connections are established on port 443 with transportMode=http, ssl=1 and AuthMech=3 (token authentication), with the token passed as the JDBC password and token as the literal username — the scheme Databricks expects for PAT auth.

Features

Supported:

• Basic and expression aggregations
• Standard deviation aggregations
• Custom expressions
• Binning
• Native SQL with parameters
• Nested queries
• Foreign keys
• Full date bucketing — minute through year, plus ISO week-of-year and day-of-week

Not supported:

• JVM timezone setting (test/jvm-timezone-setting)
• Plain Statement execution — every query runs through a PreparedStatement

Type mapping

Databricks	Metabase base type
boolean	type/Boolean
tinyint, smallint, int	type/Integer
bigint	type/BigInteger
float, double	type/Float
double precision	type/Double
decimal(p,s)	type/Decimal
char, varchar, string	type/Text
date	type/Date
time	type/Time
timestamp	type/DateTime
array<T>	type/Array
map	type/Dictionary
binary, interval	type/*

DATE, TIME and TIMESTAMP columns are read back as UTC-anchored java.time values rather than JDBC's timezone-sensitive defaults, which keeps results stable regardless of the JVM's local zone.

Building from source

The build runs inside Docker, so the only requirement on your machine is Docker itself. Metabase drivers must be compiled against a Metabase source checkout, and the Dockerfile handles fetching it.

git clone https://github.com/CarlosNeto2804/metabase-databricks-driver.git
cd metabase-databricks-driver

./bin/generate-jar.sh

This builds the image, extracts databricks-sql.metabase-driver.jar into the current directory and cleans up the intermediate container and image.

To target a different Metabase release, override the build argument:

docker build --build-arg METABASE_VERSION=v0.46.6.4 -t dbricks_driver .

Bear in mind that the driver namespace imports Metabase internals such as metabase.util.honey-sql-2 and metabase.driver.sql.util.unprepare, whose signatures shift across versions — expect to fix compilation errors when moving to a new major release.

Local development

Run a REPL with the Metabase sources on the classpath via the :dev alias:

clojure -A:dev

The driver namespace is metabase.driver.databricks-sql, registered as :databricks-sql with :sql-jdbc as its parent. project.clj also defines a user/databricks-sql alias that mounts a local driver checkout and points Metabase at the plugin manifest through -Dmb.dev.additional.driver.manifest.paths.

Implementation notes

Native query parameters are hex-encoded. Metabase's unprepare step inlines parameters into the SQL string. This driver binds *param-splice-style* to :paranoid for query execution, which encodes string parameters as decode(unhex('...'), 'utf-8') instead of quoting them — SQL injection through native parameters becomes structurally impossible, at the cost of unreadable generated SQL. The :friendly style, which escapes and quotes normally, remains the default for the "convert to SQL" view.

Schema discovery walks show schemas / show tables. describe-database iterates every schema and lists its tables rather than relying on JDBC metadata, which the Databricks driver reports inconsistently across warehouse types. Introspection cost therefore grows with the number of schemas in the catalog.

Identifiers are quoted MySQL-style (backticks), matching Databricks' own parser. Hyphens in schema and table names are rewritten to underscores before describe calls.

The week starts on Sunday, matching Databricks' dayofweek semantics. Metabase's start-of-week setting is honoured through adjust-start-of-week.

Limitations

• Pinned to a single Metabase version; upgrading Metabase requires rebuilding and likely patching the driver.
• The connection spec passes schema through the JDBC subname; ConnSchema is deliberately left unset, so the schema selector behaves differently from the catalog selector.
• No automated test suite. Changes are verified by hand against a live warehouse.
• Uses the legacy Simba-based Databricks JDBC driver (2.6.x) rather than the newer OSS databricks-jdbc releases.

Contributing

Issues and pull requests are welcome. If you are reporting a connection problem, please include your Metabase version, the driver version and the full stack trace from the Metabase logs — with the host and token redacted.

License

Distributed under the Eclipse Public License 2.0. See LICENSE.