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.
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
--user
flag) - Dashboards
- Saved questions
- Actions
- Models
- SQL Snippets
- Data model settings
- Segments and Metrics defined in the Data Model
- 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 print something like:
export path & options
Serialize Metabase instance into directory at `path`.
Options:
-u, --user EMAIL Include collections owned by the specified user
-c, --collection ID Export only specified ID; may occur multiple times.
--collections ID_LIST (Legacy-style) Export collections in comma-separated list of IDs, e.g. '123,456'.
-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).
--user
The user
flag tells Metabase to include collections owned by the specified user, identified by email. QUESTION: What about accounts created with SSO?
--collection
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 --collection 1,3,5,9
--no-collection
The --no-collection
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 data model settings from the export. Admins define the data model settings in the Data model 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 [my_export]
is the path to the export you want to import:
java -jar metabase.jar import [my_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
Further reading
- Serialization tutorial.
- Need help? contact support@metabase.com.