Skip to main content
This guide shows you how to set up Lemline with RabbitMQ for messaging and MySQL for persistent storage. This combination provides reliable message delivery with a widely-used database.

​
Why RabbitMQ + MySQL?

  • RabbitMQ: Battle-tested message broker with flexible routing and excellent observability
  • MySQL: Popular relational database with broad ecosystem support
  • Use case: Teams familiar with RabbitMQ and MySQL, or requiring specific RabbitMQ features

​
Prerequisites

  • Docker and Docker Compose installed
  • Lemline built locally (see Installation)
  • Basic understanding of RabbitMQ and MySQL

​
Quick Start

1
Start the Infrastructure
2
From the examples directory, start RabbitMQ and MySQL:
3
cd examples
docker compose --profile rabbit-mysql up -d
4
This starts:
5
  • MySQL (port 3306)
  • RabbitMQ (port 5672 for AMQP, port 15672 for management UI)
    • 6
    Wait for Services
    7
    Check that services are healthy:
    8
    docker compose ps
    9
    All services should show status “Up” and health “healthy”.
    10
    Configure Lemline
    11
    The example includes a pre-configured file:
    12
    # Lemline Configuration: RabbitMQ + MySQL

lemline:
  database:
    mysql:
      host: localhost
      port: 3306
      database: lemline
      username: lemline
      password: lemline

  messaging:
    rabbitmq:
      hostname: localhost
      port: 5672
      username: guest
      password: guest
    13
    Start Lemline
    14
    From the project root:
    15
    LEMLINE_CONFIG=./examples/lemline-rabbit-mysql.yaml \
  java -jar lemline-runner/build/quarkus-app/quarkus-run.jar listen
    16
    Lemline will:
    17
  • Connect to MySQL and run migrations
  • Connect to RabbitMQ
  • Declare necessary exchanges and queues
  • Start listening for workflow commands
    • 18
    Deploy a Workflow
    19
    Install the hello world workflow:
    20
    lemline definition post -f examples/workflows/hello.yaml
    21
    Run a Workflow Instance
    22
    lemline instance start -n tutorial.hello-workflow -v 0.1.0
    23
    Watch the Lemline logs to see execution.

    ​
    Configuration Details

    ​
    MySQL Settings

    lemline:
  database:
    mysql:
      host: localhost
      port: 3306
      database: lemline
      username: lemline
      password: lemline
      # Optional advanced settings:
      # maxPoolSize: 20
      # connectionTimeout: 30000
    Environment variable overrides: 
    LEMLINE_DATABASE_MYSQL_HOST=db.example.com
LEMLINE_DATABASE_MYSQL_PORT=3306
LEMLINE_DATABASE_MYSQL_DATABASE=production
LEMLINE_DATABASE_MYSQL_USERNAME=lemline_user
LEMLINE_DATABASE_MYSQL_PASSWORD=secret123

    ​
    RabbitMQ Settings

    lemline:
  messaging:
    rabbitmq:
      hostname: localhost
      port: 5672
      username: guest
      password: guest
      # Optional advanced settings:
      # virtualHost: /
      # ssl: false
      # connectionTimeout: 60000
    Environment variable overrides: 
    LEMLINE_MESSAGING_RABBITMQ_HOSTNAME=rabbitmq.example.com
LEMLINE_MESSAGING_RABBITMQ_PORT=5672
LEMLINE_MESSAGING_RABBITMQ_USERNAME=lemline
LEMLINE_MESSAGING_RABBITMQ_PASSWORD=secret123
LEMLINE_MESSAGING_RABBITMQ_VIRTUALHOST=/production

    ​
    Database Schema

    Lemline automatically creates the necessary tables:
    • workflow_definitions: Workflow DSL definitions
    • workflow_instances: Active and completed workflow instances
    • workflow_waits: Scheduled tasks and timeouts
    • workflow_listeners: Event listeners and subscriptions
    • workflow_retries: Retry state for failed tasks
    • workflow_failures: Terminal failures and errors
    • lifecycle_analytics: Execution metrics and history
    Migrations are managed by Flyway and run automatically on startup.

    ​
    RabbitMQ Topology

    Lemline uses RabbitMQ exchanges and queues:

    ​
    Exchanges

    • lemline.commands: Topic exchange for routing commands
    • lemline.events: Topic exchange for CloudEvents

    ​
    Queues

    • lemline.commands-in: Incoming workflow commands (start, resume, cancel)
    • lemline.commands-out: Outgoing workflow commands for task execution
    • lemline.events-out: CloudEvents produced by workflows

    ​
    Bindings

    • Commands are routed to queues based on routing keys
    • Multiple Lemline instances share the same queues (competing consumers)
    • Events are published to the events exchange

    ​
    RabbitMQ Management UI

    Access the RabbitMQ management UI at http://localhost:15672 Default credentials:
    • Username: guest
    • Password: guest
    Use the UI to:
    • View queues and message counts
    • Monitor consumer activity
    • Inspect message payloads
    • Manage exchanges and bindings
    • View connection and channel statistics

    ​
    Horizontal Scaling

    Run multiple Lemline instances to scale horizontally: 
    # Terminal 1
LEMLINE_CONFIG=./examples/lemline-rabbit-mysql.yaml \
  java -jar lemline-runner.jar listen

# Terminal 2
LEMLINE_CONFIG=./examples/lemline-rabbit-mysql.yaml \
  java -jar lemline-runner.jar listen

# Terminal 3
LEMLINE_CONFIG=./examples/lemline-rabbit-mysql.yaml \
  java -jar lemline-runner.jar listen
    RabbitMQ automatically load-balances messages across consumers.

    ​
    Monitoring

    ​
    MySQL Monitoring

    Connect to MySQL to query workflow state: 
    docker exec -it lemline-mysql mysql -u lemline -plemline lemline
    Useful queries: 
    -- Active workflow instances
SELECT namespace, name, version, status, created_at
FROM workflow_instances
WHERE status = 'running';

-- Recent failures
SELECT wi.namespace, wi.name, wf.error_type, wf.error_message, wf.failed_at
FROM workflow_failures wf
JOIN workflow_instances wi ON wf.instance_id = wi.id
ORDER BY wf.failed_at DESC
LIMIT 10;

-- Listener subscriptions
SELECT event_type, COUNT(*) as listener_count
FROM workflow_listeners
GROUP BY event_type;

    ​
    RabbitMQ Metrics

    Use the management UI or CLI to monitor: 
    # List queues with message counts
docker exec lemline-rabbitmq rabbitmqctl list_queues name messages consumers

# List connections
docker exec lemline-rabbitmq rabbitmqctl list_connections name user

# List consumers
docker exec lemline-rabbitmq rabbitmqctl list_consumers

    ​
    Production Considerations

    Configure appropriate pool sizes based on your workload:
    lemline:
  database:
    mysql:
      maxPoolSize: 50
      minPoolSize: 10
      connectionTimeout: 30000
    For production, use a RabbitMQ cluster:
    • At least 3 nodes for high availability
    • Configure mirrored queues for fault tolerance
    • Use a load balancer for connection distribution
    Optimize MySQL for your workload:
    • Increase max_connections for concurrent workflows
    • Tune innodb_buffer_pool_size
    • Configure appropriate backup and replication
    • Consider using ProxySQL for connection pooling
    • Enable SSL/TLS for RabbitMQ connections
    • Use SSL for MySQL connections
    • Create dedicated users with minimal privileges
    • Rotate credentials regularly
    • Use RabbitMQ virtual hosts to isolate environments
    • Restrict network access with firewalls

    ​
    Message Durability

    RabbitMQ can persist messages to disk for durability: 
    lemline:
  messaging:
    rabbitmq:
      durable: true
      autoDelete: false
    Durable queues and persistent messages improve reliability but may impact throughput.

    ​
    Troubleshooting

    ​
    RabbitMQ Connection Refused

    Error: java.net.ConnectException: Connection refused Solution: Ensure RabbitMQ is running and accessible: 
    docker compose ps rabbitmq
docker compose logs rabbitmq

    ​
    MySQL Connection Errors

    Error: Access denied for user 'lemline'@'localhost' Solution: Check MySQL status and credentials: 
    docker compose ps mysql
docker compose logs mysql

    ​
    Queue Not Found

    Error: Queue 'lemline.commands-in' not found Solution: Lemline declares queues automatically. If the error persists, check RabbitMQ logs for permission issues.

    ​
    Message Buildup

    Symptom: Messages accumulating in queues Solution:
    1. Check Lemline logs for errors
    2. Verify consumers are connected (RabbitMQ UI)
    3. Scale horizontally by adding more Lemline instances
    4. Check for slow downstream services

    ​
    Stopping the Infrastructure

    # Stop services but keep data
docker compose --profile rabbit-mysql down

# Stop services and remove volumes (clean slate)
docker compose --profile rabbit-mysql down -v

    ​
    Next Steps

    Kafka + PostgreSQL

    Try Kafka for higher throughput

    PGMQ Setup

    Use PostgreSQL for both messaging and storage

    Production Deployment

    Deploy Lemline to production

    Monitoring

    Set up metrics and monitoring

    Build docs developers (and LLMs) love

    Get started for freeTalk to us