Namastack Outbox v0.2.0

🎉 Major Architectural Improvements

Version 0.2.0 introduces a complete architectural overhaul that transforms how the Outbox pattern scales across multiple instances. We've replaced distributed locking with hash-based partitioning, delivering significant performance improvements and true horizontal scalability.

🚀 Key Features

Hash-based Partitioning

• 🎯 Consistent Hashing: Each aggregate maps to the same partition using MurmurHash3
• ⚡ Lock-Free Design: Eliminates distributed lock overhead and deadlock risks
• 📈 Linear Scaling: Performance scales directly with instance count
• 🔄 Automatic Rebalancing: Partitions redistribute automatically when instances join/leave
• 🛡️ Ordering Guarantee: Maintains strict event ordering per aggregate
• 256 Fixed Partitions: Provides fine-grained load distribution

Instance Coordination

• 💓 Heartbeat System: Automatic detection of healthy/failed instances
• 🔍 Dynamic Discovery: New instances automatically join the cluster
• ⚖️ Load Balancing: Even distribution of partitions across all instances
• 🛑 Graceful Shutdown: Clean partition handover during instance shutdown

Multi-Database Support

• 🗄️ Programmatic Transactions: Replaced @Transactional with TransactionTemplate
• 🔧 Multi-Persistence Units: Support for multiple database configurations
• ⚙️ Configurable Transaction Managers: Custom transaction template support

🔧 Technical Improvements

Performance Enhancements

• ⚡ Eliminated Lock Contention: No more distributed lock overhead
• 🚀 Optimized Queries: New database indexes for partition-based queries
• 📊 Batch Processing: Efficient partition-aware record processing
• 🎯 Reduced Latency: Direct partition assignment without lock acquisition

🔄 Migration from v0.1.0

Simple Migration (Recommended)

-- Stop all instances, then drop and recreate tables
DROP TABLE IF EXISTS outbox_record;
DROP TABLE IF EXISTS outbox_lock;  -- If exists from v0.1.0

-- Tables will be recreated automatically with new schema

Custom Migration

For production environments requiring data preservation, contact the maintainer for migration assistance.

⚠️ Breaking Changes

Removed Features

• Distributed Locking: Completely replaced with hash-based partitioning
• Lock Tables: outbox_lock table no longer needed
• Lock Configuration: All lock-related configuration options removed

Changed Behavior

• Record Structure: OutboxRecord now includes partition information
• Processing Logic: Events processed based on partition assignment
• Scaling Model: Horizontal scaling through partitions instead of locks
• Transaction Management: Switched from declarative to programmatic transactions

Updated Dependencies

• Spring Boot: 3.0+ required
• Java: 21+ required
• Kotlin: 2.2+ required

📈 Performance Improvements

Real-world Impact

• Multiple Instances: Seamless scaling from 1 to N instances
• Load Distribution: Even workload distribution across instances
• Failure Recovery: Sub-second partition reassignment on instance failure
• Resource Usage: Reduced CPU and memory overhead

🙏 Acknowledgments

Special thanks to the community for feedback and testing that made this release possible. The architectural improvements in v0.2.0 lay the foundation for even better performance and scalability in future releases.

@AZapata27 @icepuma @wimdeblauwe

📚 Resources

• 📖 Documentation: outbox.namastack.io
• 🔧 Migration Guide: See README.md for detailed migration instructions
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Download: GitHub Releases
Maven Central: io.namastack:namastack-outbox-starter-jpa:0.2.0