Metabase-exporter

Tools for managing Metabase .

Used to export/import the current state of Metabase (questions/dashboards/collections) to/from a JSON file. This file can then be stored on git for versioning.

Supported Metabase versions

This project supports Metabase v0.50 to v0.57.

The Metabase API is not versioned and subject to changes with every version, so don't expect this tool to work on versions other than those listed above. Backward compatibility is a goal, though: every supported version is exercised in CI, and a state file exported from one supported version can be imported into any other.

The test suite runs against one version at a time, selected by the METABASE_VERSION environment variable (a Metabase Docker image tag):

METABASE_VERSION=v0.50.36 dotnet test
./run-tests.sh v0.50.36   # equivalent, via the Nix wrapper

It defaults to the newest supported version. The CI workflow runs a matrix job per supported version; add a version there when adding support for a new one.

To use this install Nix and then run it with e.g. nix run github:elevate/elevate.metabase.tools -- Command=Import ...

It's recommended that you pin a specific commit for reliability e.g. nix run github:elevate/elevate.metabase.tools/09bc3ea332f82f8b5b32d730e4de262a0dd2c3fe -- Command=Import ...

If you're on Windows or want to develop, install the .NET 10 SDK and run it from the metabase-exporter with e.g. dotnet run -- Command=Import ...

See usage flags below.

Limitations

This tool currently exports/imports collections, dashboards and SQL-defined questions only. Other kinds of questions are not supported because they are hard to make portable across Metabase instances. Other features (e.g. pulses) are not supported simply because I don't need them :)

Usage

Parameters can be given via command-line, appsettings.json or environment variables.

For all operations the Metabase API settings must be configured. E.g. in appsettings.json:

{
  "MetabaseApi": {
    "Url": "https://localhost:32443",
    "Username": "mauricio@elevatedirect.com",
    "Password":  "123456789"
  }
}

Export

This exports the state to a file. Sample usage:

metabase-exporter.exe Command=export OutputFilename=metabase-state.json

You can optionally exclude personal collections by setting ExcludePersonalCollections=1

Import

This imports a state file into a Metabase instance. Sample usage:

metabase-exporter.exe Command=import InputFilename=metabase-state.json DatabaseMapping:1=2 DatabaseMapping:2=3

The DatabaseMapping settings map Metabase database IDs in the state file to database IDs in the target Metabase instance. In the example above, it maps:

• the database ID 1 in the file to the database ID 2 in the target Metabase instance
• the database ID 2 in the file to the database ID 3 in the target Metabase instance

By default, import deletes every dashboard and question in the target Metabase instance before it creates the ones in the file. To keep them instead, set Merge=true. A merge updates the dashboards and questions whose names match one in the file, creates the rest, and leaves everything else in the target instance alone.

To skip the questions that use a database, list its ID in the file under IgnoreDatabases, for example IgnoreDatabases=3,4. An ignored database needs no DatabaseMapping.

Boolean settings such as Merge and ExcludePersonalCollections accept true, false, 1, or 0. Any other value is an error.

Test questions

This runs the queries in all Metabase Questions/Cards. Use it to test that the queries (i.e. SQL) are valid.

metabase-exporter.exe Command=test-questions