Schema Definition Export and Import


Nodes and clusters store information that can be thought of schema, metadata or topology. Users, vhosts, queues, exchanges, bindings, runtime parameters all fall into this category.

Definitions are stored in an internal database and replicated across all cluster nodes. Every node in a cluster has its own replica of all definitions. When a part of definitions changes, the update is performed on all nodes in a single transaction. This means that in practice, definitions can be exported from any cluster node with the same result.

Definitions can be exported to a file and then imported into another cluster or used for schema backup.

A definition file contains definitions of all broker objects (queues, exchanges, bindings, users, virtual hosts, permissions and parameters).

Definition import on node boot is the recommended way of pre-configuring nodes at deployment time.

Definition Export

Definitions are exported as a JSON file in a number of ways.

Definitions can be exported for a specific virtual host or the entire cluster (all virtual host). When definitions are exported for just one virtual host, some information (contents of the other virtual hosts or users without any permissions to the target virtual host) will be excluded from the exported file.

Exported user data contains password hashes as well as password hashing function information. While brute forcing passwords with hashing functions such as SHA-256 or SHA-512 is not a completely trivial task, user records should be considered sensitive information.

To export definitions using rabbitmqctl, use rabbitmqctl export_definitions:

# Does not require management plugin to be enabled, new in RabbitMQ 3.8.2
rabbitmqctl export_definitions /path/to/definitions.file.json

rabbitmqadmin export is very similar but uses the HTTP API and is compatible with older versions:

# Requires management plugin to be enabled
rabbitmqadmin export /path/to/definitions.file.json

Definition Import

To import definitions using rabbitmqctl, use rabbitmqctl import_definitions:

# Does not require management plugin to be enabled, new in RabbitMQ 3.8.2
rabbitmqctl import_definitions /path/to/definitions.file.json

rabbitmqadmin import is its HTTP API equivalent:

# Requires management plugin to be enabled
rabbitmqadmin import /path/to/definitions.file.json

It is also possible to use the HTTP API endpoint directly. Here's an example that contacts a local node at localhost:15672 using curl and default user credentials:

curl -H "Accept:application/json" -u guest:guest "http://localhost:15672/api/definitions"

Definition Import at Node Boot

Most recent releases support definition import directly in the core, without the need to preconfigure the management plugin.

To import definitions from a local file on node boot, set the load_definitionsconfig key to the path of a previously exported JSON file containing the definitions that should be imported on node boot:

# Does not require management plugin to be enabled, new in RabbitMQ 3.8.2
load_definitions = /path/to/definitions/file.json

Older versions only provided a similar feature as part of the management plugin:

# Requires management plugin to be enabled at the time of node boot
management.load_definitions = /path/to/definitions/file.json

The definitions in the file will not overwrite anything already in the broker. However, if a blank (uninitialised) node imports a definition file, it will not create the default virtual host and user.

Getting Help and Providing Feedback

If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.

Help Us Improve the Docs <3

If you'd like to contribute an improvement to the site, its source is available on GitHub. Simply fork the repository and submit a pull request. Thank you!