Database driver basics

A Metabase driver:

  • Provides Metabase with basic information for the database such as the database’s capabilities, connection properties, and so on.
  • Provides Metabase with information about the schema of the database – the tables (or equivalent), the fields in those tables, the foreign key relationships (for databases that support foreign keys).
    • This functionality is used by the Metabase sync process and stored in the application database.
    • The stored information is used in the visual Query Builder and other places to show users what tables/columns/etc. are available
  • Compiles our in-house query language, MBQL, into native queries.
    • MBQL queries are generated by the visual query builder.
    • The Metabase query processor* converts MBQL queries to native queries
  • Executes native queries and returns results.

Write your driver as a module and package it as a plugin

Metabase drivers are organized into modules and packaged as plugins. Modules are the source code; plugins are the JARs built from that source code.

A Metabase plugin is a JAR file that contains the compiled class files and a Metabase plugin manifest that lists details about the driver. In most cases, plugins are lazily loaded, which means that Metabase won’t initialize the drivers until it connects to a database that would use the driver.

For Metabase to use your driver, all you need to do is put the driver JAR you built into the /plugin directory, which you’ll find in the same directory where you run your metabase.jar. Something like this:

/Users/cam/metabase/metabase.jar
/Users/cam/metabase/plugins/my-plugin.jar

You can change the plugin directory by setting the environment variable MB_PLUGINS_DIR.

Example module directory

Let’s take a high-level look at the SQLite driver:

|-- deps.edn
|-- resources
|   `-- metabase-plugin.yaml
|-- src
|   `-- metabase
|       `-- driver
|           `-- sqlite.clj
`-- test
    `-- metabase
        |-- driver
        |   `-- sqlite_test.clj
        `-- test
            `-- data
                `-- sqlite.clj

There are three files to call out here:

deps.edn

The deps.edn file specifies the driver’s dependencies.

resources/metabase-plugin.yaml

Your driver’s manifest includes details about your driver.

src/metabase/driver/sqlite.clj

This is the core file for your driver. We’ll talk more about it in Implementing multimethods.

Next Up

We’ll learn more about plugin manifests.

Read docs for other versions of Metabase.