Serialization

Serialization is only available on Pro and Enterprise plans (only on self-hosted plans).

Once you really get rolling with Metabase, it’s often the case that you’ll have more than one Metabase instance spun up. You might have a couple of testing or development instances and a few production ones, or maybe you have a separate Metabase per office or region.

To help you out in situations like this, Metabase has a serialization feature which lets you create an export of the contents of a Metabase that can then be imported into one or more Metabases.

We’re interested in how we can improve serialization to suit your workflow. Upvote an existing issue to let us know it’s important to you. If a relevant issue doesn’t yet exist, please create one and tell us what you need.

Serialization use cases

Staging environments. Enable a staging-to-production workflow for important dashboards by exporting from a staging instance of Metabase and then importing them into your production instance(s).
Version control. Check the exported files into version control and audit changes to them, as the YAML files contained within the export are pretty readable.

What gets exported

Metabase only includes some artifacts in its exports.

Collections (except for personal collections, unless specified by the --collection flag)
Dashboards
Saved questions
Actions
Models
SQL Snippets
Table Metadata settings
Segments and Metrics defined in the Table Metadata
Public sharing settings for questions and dashboards
General Metabase settings
Database connection settings
Events and timelines

Metabase will export its artifacts to a directory of YAML files. The export includes:

A settings.yaml file that includes some basic, Metabase-wide settings
Directories that contain YAML files for various Metabase entities

An example export could include the following directories, depending on what you exported:

actions
collections
databases

In the collections/cards directory, you’ll see that Metabase prefixes individual files with IDs to disambiguate entities that share the same name:

IA96oUzmUbYfNFl0GzhRj_accounts_model.yaml
KUEGiWvoBFEc5oGQCEnPg_converted_customers.yaml
qzNa8ZeFgFXrrIoF2g8m4_accounts_model_detail.yaml

Example question

Questions can be found in the cards directory of a collection directory. Here’s an example card YAML file for a native question (a question written in SQL):

description: The number of plans by referral source.
archived: false
collection_position: null
table_id: null
result_metadata: null
database_id: Sample Database
enable_embedding: false
collection_id: onou5H28Wvy3kWnjxxdKQ
query_type: native
name: Plan counts by source
creator_id: jeff@metabase.com
made_public_by_id: null
embedding_params: null
cache_ttl: null
dataset_query:
  type: native
  native:
    query: |-
      SELECT count(*),
             PLAN,
             SOURCE
      FROM accounts
      WHERE SOURCE IS NOT NULL
      GROUP BY PLAN,
               SOURCE
    template-tags: {}
  database: Sample Database
parameter_mappings: []
serdes/meta:
- model: Card
  id: 17p_H8e2OpHGGJVxqg4sN
  label: plan_counts_by_source
display: table
entity_id: 17p_H8e2OpHGGJVxqg4sN
collection_preview: true
visualization_settings:
  table.pivot_column: PLAN
  table.cell_column: COUNT(*)
  column_settings: null
parameters: []
dataset: false
created_at: '2023-05-22T14:32:28.124325'
public_uuid: null

Before exporting or importing

If your Metabase is:

currently running, and
you’re using the default H2 database

You’ll need to stop Metabase before exporting or importing.

Otherwise, you’re good.

Exporting a Metabase

To export the contents of a Metabase instance, change into the directory where you’re running the Metabase JAR and run:

java -jar metabase.jar export export_name

Export options

To view a list of export options, use the help command:

java -jar metabase.jar help export

Which will run and then print something like:

export path & options
	 Serialize Metabase instance into directory at `path`.
	 Options:
	   -c, --collection ID             Export only specified ID; may occur multiple times.
	   -C, --no-collections            Do not export any content in collections.
	   -S, --no-settings               Do not export settings.yaml
	   -D, --no-data-model             Do not export any data model entities; useful for subsequent exports.
	   -f, --include-field-values      Include field values along with field metadata.
	   -s, --include-database-secrets  Include database connection details (in plain text; use caution).

`--collection`

By default, Metabase will include all collections (except for personal collections) in the export. To include personal collections, you must explicitly add them with the --collection flag.

The --collection flag (alias -c) lets you specify by ID one or more collections to include in the export. You can find the collection ID in the collection’s URL, e.g., for a collection at: your-metabase.com/collection/42-terraforming-progress, the ID would be 42.

If you want to specify multiple collections, separate the IDs with commas. E.g.,

java -jar metabase.jar export export_name --collection 1,2,3

`--no-collections`

The --no-collections flag (alias -C) tells Metabase to exclude all collections from the export.

`--no-settings`

The --no-settings flag (alias -S) tells Metabase to exclude the settings.yaml file that includes site-wide settings, which is exported by default.

`--no-data-model`

The --no-data-model flag (alias -D) tells Metabase to exclude the Table Metadata settings from the export. Admins define the metadata settings in the Table Metadata tab of the Admin settings.

`--include-field-values`

The --include-field-values flag (alias -f) tells Metabase to include the sample values for field values, which Metabase uses to present dropdown menus. By default, Metabase excludes these sample field values.

`--include-database-secrets`

The --include-database-secrets flag (alias -s) tells Metabase to include connection details, including the database user name and password. By default, Metabase excludes these database connection secrets. If you don’t use this flag, you’ll need to manually input the credentials in the target Metabase.

Importing to a Metabase

To import exported artifacts into a Metabase instance, go to the directory where you’re running your target Metabase (the Metabase you want to import into) and use the following command, where path_to_export is the path to the export that you want to import:

java -jar metabase.jar import path_to_export

Currently, you can only import exported artifacts into a Metabase instance that was created from the same version of Metabase.

You’ll need to manually add license tokens

Metabase excludes your license token from exports, so if you’re running multiple environments of Metabase Enterprise Edition, you’ll need to manually add your license token to the target Metabase(s), either via the Metabase user interface, or via an environment variable.

Import options

Most options are defined when exporting data from a Metabase. To view a list of import flags, run:

java -jar metabase help import

Which prints out:

import path & options
         Load serialized Metabase instance as created by the [[export]] command from directory `path`.
         Options:
           -e, --abort-on-error  Stops import on any errors, default is to continue.

`--abort-on-error`

The --abort-on-error flag (alias -e) is an optional flag that allows you to specify how the import process should handle errors. Metabase will ignore errors by default.

Avoid using serialization for backups

Just a note: serialization is not meant to back up your Metabase.

See Backing up Metabase.

If you’re instead looking to do a one-time migration from the default H2 database included with Metabase to a MySQL/Postgres, then use the migration guide instead.

The general settings that Metabase exports

A list of the general settings Metabase exports in the settings.yaml file.

humanization-strategy
native-query-autocomplete-match-style
site-locale
report-timezone-short
report-timezone-long
application-name
enable-xrays
show-homepage-pin-message
source-address-header
enable-nested-queries
custom-geojson-enabled
start-of-week
custom-geojson
available-timezones
max-results-bare-rows
hide-embed-branding?
search-typeahead-enabled
enable-sandboxes?
application-font
available-locales
landing-page
enable-embedding
application-colors
application-logo-url
application-favicon-url
show-homepage-xrays
show-metabot
enable-whitelabeling?
show-homepage-data
site-name
application-font-files
loading-message
report-timezone
show-lighthouse-illustration
persisted-models-enabled
enable-content-management?
subscription-allowed-domains
breakout-bins-num
available-fonts
custom-formatting

For more on Metabase settings, see Configuring Metabase

Migrating from the old serialization commands

If you’re upgrading from Metabase version 46.X or older, here’s what you need to know:

The export command replaces the dump command.
The import command replace the load command.

A few other changes to call out:

The exported YAML files have a slightly different structure:
- Metabase will prefix each file with a 24-character entity ID (like IA96oUzmUbYfNFl0GzhRj_accounts_model.yaml).
- The file tree is slightly different.
To serialize personal collections, you just need to include the personal collection IDs in the list of comma-separated IDs following the -c option (short for --collection).

If you’ve written scripts to automate serialization, you’ll need to:

Reserialize your Metabase using the upgraded Metabase (which uses the new export and import commands). Note that serialization will only work if you export and import your Metabase using the same Metabase version.
Update those scripts with the new commands. See the new export options.
If your scripts do any post-processing of the exported YAML files, you may need to update your scripts to accommodate the slightly different directory and YAML file structures.

Drop entity IDs

Before exporting, you can also run a Metabase command to drop entity IDs.