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.