LavinMQ LavinMQ logo Latest stable version: v2.9.1
LavinMQ logo
Home Documentation Blog Community Resources
Get started
GitHub Repository
High Availability

Import/Export Definitions

Definitions are the complete declarative state of a LavinMQ server: vhosts, users, permissions, exchanges, queues, bindings, policies, and parameters.

Export

Export all definitions as JSON:

# Via API
GET /api/definitions

# Via CLI
lavinmqctl export_definitions

# Via CLI (offline, from data directory)
lavinmqctl definitions /var/lib/lavinmq

Per-vhost export: GET /api/definitions/<vhost>

Import

Import definitions from a JSON file:

# Via API
POST /api/definitions
Content-Type: application/json
<json body>

# Via CLI
lavinmqctl import_definitions definitions.json

Import is additive: new resources are created and bindings/policies/parameters/users with the same name are replaced. Re-declaring an existing queue or exchange with mismatching properties (durable, auto-delete, arguments) returns a precondition_failed error rather than overwriting.

Load on startup

Set load_definitions in the [main] section of the config file to import a JSON definitions file every time the broker boots:

[main]
load_definitions = /etc/lavinmq/definitions.json

Behavior:

  • The file is imported before listeners start accepting connections.
  • Existing users, permissions, vhosts, policies, and parameters are preserved. The file only adds to or updates state, never deletes. Queues and exchanges with mismatching properties return precondition_failed and skip without overwriting.
  • On a fresh data directory, the default vhost (/) and default user are not seeded if load_definitions is set; the file is expected to declare the desired bootstrap state.
  • If the file is missing, unreadable, or contains invalid JSON, the broker logs an error and exits with a non-zero status instead of starting.

JSON Format

{
  "lavinmq_version": "2.x.x",
  "vhosts": [
    { "name": "/" }
  ],
  "users": [
    {
      "name": "guest",
      "password_hash": "...",
      "hashing_algorithm": "SHA256",
      "tags": "administrator"
    }
  ],
  "permissions": [
    {
      "user": "guest",
      "vhost": "/",
      "configure": ".*",
      "read": ".*",
      "write": ".*"
    }
  ],
  "exchanges": [...],
  "queues": [...],
  "bindings": [...],
  "policies": [...],
  "parameters": [...]
}

Ready to take the next steps?

Managed LavinMQ instance via CloudAMQP

LavinMQ has been built with performance and ease of use in mind - we've benchmarked a throughput of about 1,000,000 messages/sec . You can try LavinMQ without any installation hassle by creating a free instance on CloudAMQP. Signing up is a breeze.

Get started with CloudAMQP ->

Help and feedback

We welcome your feedback and are eager to address any questions you may have about this piece or using LavinMQ. Join our Slack channel to connect with us directly. You can also find LavinMQ on GitHub.

Can’t find what you’re looking for? Let us know
Was this helpful?

Search