Queen MQModern PostgreSQL-backed Message Queue

📚 Documentation ​

Why We Built Queen MQ ​

The Context ​

At Smartness, we use Kafka extensively across our infrastructure and know it well. For Smartchat's message backbone, we initially chose Kafka for its strong reliability guarantees.

However, we encountered a use case mismatch: in Kafka, a single message processing delay affects the entire partition. For most workloads this isn't an issue, but our system involves:

• AI translations - Can take seconds/minutes
• Agent responses - Can take seconds/minutes
• Variable processing times - Inherent to the domain

With potentially 100,000+ concurrent chats, we would need a Kafka partition for each chat conversation - which isn't practical at that scale.

From Custom Tables to Queen ​

We started moving long-running operations to custom PostgreSQL queue tables. As we built out the system, we needed:

• Consumer groups - For different processing pipelines
• Window buffering - To aggregate messages before AI processing
• Retry limits - For better error visibility
• Message tracing - For debugging distributed workflows

We realized we had built a complete message queue system that better fit our specific requirements.

The Result ​

Queen now handles Smartchat's message infrastructure:

• One partition per chat - Slow processing in one chat doesn't affect others
• Unlimited partitions - Scale to any number of concurrent conversations
• Window buffering - Aggregate messages to optimize API calls
• Built-in observability - Retry mechanisms and tracing for debugging
• PostgreSQL-backed - ACID guarantees with automatic failover

Queen processes 100,000+ messages daily in production.

Quick Example ​

import { Queen } from 'queen-mq'

// Connect
const queen = new Queen('http://localhost:6632')

// Create queue with configuration
await queen.queue('orders')
  .config({ leaseTime: 30, retryLimit: 3 })
  .create()

// Push messages with guaranteed order per partition
await queen.queue('orders')
  .partition('customer-123')
  .push([{ data: { orderId: 'ORD-001', amount: 99.99 } }])

// Consume with consumer groups for scalability
await queen.queue('orders')
  .group('order-processor')
  .concurrency(10)
  .batch(20)
  .autoAck(false)
  .each()
  .consume(async (message) => {
    await processOrder(message.data)
  })
  .onSuccess(async (message) => {
    await queen.ack(message, true, { group: 'order-processor' })
  }).onError(async (message, error) => {
    await queen.ack(message, false, { group: 'order-processor' })
  })

Performance Metrics ​

Key Features Comparison ​

Use Cases ​

🏢 Enterprise Workflows ​

Build reliable multi-step workflows with transactions and exactly-once delivery. Perfect for financial systems, order processing, and data pipelines.

📊 Real-time Analytics ​

Stream messages to multiple consumer groups for different analytics purposes. Replay historical data from any timestamp.

🔄 Event-Driven Architecture ​

Decouple microservices with guaranteed message delivery. Built-in tracing helps debug distributed systems.

💼 Task Queues ​

Distribute work across multiple workers with automatic load balancing. Long-running tasks supported with lease renewal.

Architecture ​

Queen uses a high-performance acceptor/worker pattern with fully asynchronous, non-blocking PostgreSQL architecture:

• Network Layer: uWebSockets with configurable workers (default: 10)
• Database Layer: Async connection pool (142 non-blocking connections)
• Failover Layer: Automatic disk buffering when PostgreSQL unavailable
• Distributed Cache: UDP-based state sync between servers (UDPSYNC)
• Background Services: Poll workers, metrics, retention, eviction

Learn more about the architecture →

Built by Developers, for Developers ​

Queen was created by Smartness to power their hospitality platform. It's built with modern C++17, uses PostgreSQL for ACID guarantees, and includes a beautiful Vue.js dashboard.

Get Started in Minutes ​

# Start PostgreSQL and Queen server
docker network create queen
docker run --name postgres --network queen \
  -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres

docker run -p 6632:6632 --network queen \
  -e PG_HOST=postgres -e PG_PASSWORD=postgres \
  smartnessai/queen-mq:0.8.0

# Install JavaScript client
npm install queen-mq

# Or install Python client
pip install queen-mq

# Start building!

Full Quick Start Guide →

Community & Support ​

• GitHub: github.com/smartpricing/queen
• LinkedIn: Smartness Company Page
• Docker Hub: smartnessai/queen-mq

License ​

Queen MQ is released under the Apache 2.0 License.