MongoDB Schema

When using the MongoDB persistence module, collections and indexes can be created automatically by Spring Data MongoDB (spring.data.mongodb.auto-index-creation=true). However, for production environments it is recommended to manage indexes explicitly using a setup script.

Collections & Indexes

The MongoDB module uses three collections:

Collection	Purpose
outbox_records	Stores outbox records (events/messages)
outbox_instances	Tracks application instances
outbox_partition_assignments	Maps partitions to instances

When using a custom collection prefix (e.g. myapp_), all collection names are prefixed accordingly (e.g. myapp_outbox_records).

outbox_records Indexes

Index Name	Fields	Purpose
status_idx	{ status: 1 }	Filter records by status
record_key_created_idx	{ recordKey: 1, createdAt: 1 }	Ordered lookup by record key
partition_status_retry_idx	{ partitionNo: 1, status: 1, nextRetryAt: 1 }	Partition-scoped polling query
status_retry_idx	{ status: 1, nextRetryAt: 1 }	Global retry scheduling
record_key_completed_created_idx	{ recordKey: 1, completedAt: 1, createdAt: 1 }	Completed record cleanup
fifo_pipeline_idx	{ partitionNo: 1, recordKey: 1, createdAt: 1 }	FIFO aggregation pipeline for ordered processing

outbox_instances Indexes

Index Name	Fields	Purpose
status_idx	{ status: 1 }	Filter instances by status
lastHeartbeat_idx	{ lastHeartbeat: 1 }	Stale instance detection
status_heartbeat_idx	{ status: 1, lastHeartbeat: 1 }	Combined status + heartbeat query

outbox_partition_assignments Indexes

Index Name	Fields	Purpose
instanceId_idx	{ instanceId: 1 }	Lookup partitions by instance

---

Manual Setup Script

A ready-to-use mongosh script is provided in the repository:

👉 mongodb-setup.js on GitHub

Running the Script

Default collection names:

mongosh mongodb://localhost:27017/mydb schema/mongodb-setup.js

With a custom collection prefix:

mongosh --eval 'var OUTBOX_PREFIX="myapp_"' mongodb://localhost:27017/mydb schema/mongodb-setup.js

This creates myapp_outbox_records, myapp_outbox_instances, and myapp_outbox_partition_assignments.

Disabling Auto-Index Creation

When using the manual setup script, disable Spring Data MongoDB's automatic index creation:

spring:
  data:
    mongodb:
      auto-index-creation: false

Production Recommendation

For production environments, it is recommended to disable auto-index-creation and manage indexes via the setup script (or your own migration tooling). This gives you full control over when and how indexes are created, avoiding potential performance impacts during application startup.