Feature-rich MongoDB ODM and messaging framework for Java 21+

Available languages: English and Deutsch

• 🗄️ High-performance object mapping with annotation-driven configuration
• 📨 Integrated message queue backed by MongoDB (no extra infrastructure)
• ⚡ Multi-level caching with cluster-wide invalidation
• 🔌 Custom MongoDB wire-protocol driver tuned for Morphium
• 🧪 In-memory driver for fast tests (no MongoDB required)
• 🎯 JMS API (experimental) for standards-based messaging
• 🚀 Java 21 with virtual threads for optimal concurrency

Morphium is the only Java ODM that ships a message queue living inside MongoDB. If you already run MongoDB, you can power persistence, messaging, caching, and change streams with a single component.

* Numbers are indicative and depend heavily on hardware and workload.

• Documentation hub – entry point for all guides
• Overview – core concepts, quick start, compatibility
• Upgrade v6.1→v6.2 – migration checklist for 6.2.0
• Migration v5→v6 – step-by-step upgrade guide
• InMemory Driver Guide – capabilities, caveats, testing tips
• Optimistic Locking (@Version) – prevent lost updates with @Version
• SSL/TLS & MONGODB-X509 – encrypted connections and certificate-based authentication

• Aggregation examples: docs/howtos/aggregation-examples.md
• Messaging implementations: docs/howtos/messaging-implementations.md
• Performance guide: docs/performance-scalability-guide.md
• Production deployment: docs/production-deployment-guide.md
• Monitoring & troubleshooting: docs/monitoring-metrics-guide.md

Morphium is now a multi-module project: morphium-parent (BOM), morphium (core library), and poppydb (server). The core library de.caluga:morphium no longer drags in server dependencies (Netty, etc.) — 90% leaner for users who just need the ODM.

The former MorphiumServer is now an independent module de.caluga:poppydb. It implements the MongoDB Wire Protocol as an in-memory server with Replica Set emulation, Change Streams, Aggregation Pipeline, and snapshot-based persistence.

PoppyDB and Morphium Messaging are optimized for each other — both sides recognize the counterpart and adapt their behavior, resulting in lower latency and less overhead than with a real MongoDB as messaging backend.

<dependency>
    <groupId>de.caluga</groupId>
    <artifactId>poppydb</artifactId>
    <version>6.2.0</version>
    <scope>test</scope> <!-- or remove scope for production use -->
</dependency>

• ✅ Full Wire Protocol: Any MongoDB client can connect (mongosh, Compass, PyMongo, ...)
• ✅ Messaging Backend: Run Morphium messaging without MongoDB — optimized for low-latency
• ✅ CLI Tooling: poppydb-6.2.0-cli.jar for standalone deployment
• ✅ Replica Set Emulation: Test cluster behavior without real MongoDB
• ✅ Snapshot Persistence: --dump-dir / --dump-interval to preserve data across restarts

MorphiumDriverException extends RuntimeException — consistent with the MongoDB Java driver. Eliminates 40+ boilerplate catch-wrap-rethrow blocks.

@Reference now supports cascadeDelete and cascadeStore for automatic lifecycle management of referenced entities.

Annotation-driven auto-increment sequences — no manual counter management needed.

Works correctly with store() and storeList(), supports @CreationTime on Date, long, and String fields.

Morphium detects Azure CosmosDB connections and automatically adjusts behavior for compatibility.

See CHANGELOG for full details.

MorphiumDriverException extends RuntimeException instead of Exception. This eliminates boilerplate catch-wrap-rethrow blocks but requires attention in existing code:

// Multi-catch — simplify (MorphiumDriverException IS a RuntimeException now)
// Before:
catch (RuntimeException | MorphiumDriverException e) { ... }
// After:
catch (RuntimeException e) { ... }

// throws declarations — can be removed (but still compile if left in)
// Before:
public void doStuff() throws MorphiumDriverException { ... }
// After:
public void doStuff() { ... }

// Standalone catch — works unchanged
catch (MorphiumDriverException e) { ... }  // still compiles

The embedded MongoDB-compatible server was extracted to its own module and renamed:

If you use PoppyDB in tests, add the dependency:

<dependency>
    <groupId>de.caluga</groupId>
    <artifactId>poppydb</artifactId>
    <version>6.2.0</version>
    <scope>test</scope>
</dependency>

Wire-protocol compatibility is preserved — PoppyDB responds to both poppyDB and morphiumServer in the hello handshake.

MorphiumConfig now organizes settings into typed sub-objects. The old setters still work but are @Deprecated:

// 6.1.x style (deprecated but functional)
cfg.setDatabase("mydb");
cfg.addHostToSeed("localhost", 27017);

// 6.2.0 style (preferred)
cfg.connectionSettings().setDatabase("mydb");
cfg.clusterSettings().addHostToSeed("localhost", 27017);
cfg.driverSettings().setDriverName("PooledDriver");

Available sub-objects: connectionSettings(), clusterSettings(), driverSettings(), messagingSettings(), cacheSettings(), authSettings(), threadPoolSettings(), objectMappingSettings(), writerSettings().

The morphium core artifact no longer bundles server dependencies (Netty, etc.). If you only use Morphium as ODM, your dependency tree is ~90% leaner — no changes to your pom needed.

1. Search for catch (RuntimeException | MorphiumDriverException — simplify to catch (RuntimeException
2. Search for import de.caluga.morphium.server — replace with import de.caluga.poppydb
3. Search for MorphiumServer — rename to PoppyDB
4. Search for @Tag("morphiumserver") — rename to @Tag("poppydb")
5. Add poppydb dependency if you use the embedded server in tests
6. Optional: migrate direct config setters to sub-object style
7. Optional: adopt new features (@Reference(cascadeDelete), @AutoSequence, @Version)

• Connect to MongoDB instances that require mutual TLS / x.509 client certificates
• Configure via AuthSettings.setAuthMechanism("MONGODB-X509") together with the existing SslHelper mTLS setup

Prevents lost updates in concurrent environments without requiring pessimistic database locks. See docs/howtos/optimistic-locking.md for the full guide.

• Virtual threads for high-throughput messaging and change streams
• Pattern matching across driver and mapping layers
• Records: Not yet supported as @Entity or @Embedded types (see #116)
• Sealed class support for cleaner domain models

• SSL/TLS Support: Secure connections to MongoDB instances (added in v6.0)
• Virtual threads in the driver for optimal concurrency

• Fewer duplicates thanks to refined message processing
• Virtual-thread integration for smoother concurrency
• Higher throughput confirmed in internal benchmarking
• Distributed locking for coordinated multi-instance deployments

• No MongoDB required for unit tests or CI pipelines
• Significantly faster test cycles in pure in-memory mode
• ~93% MongoDB feature coverage including advanced operations
• Full aggregation pipeline with $lookup, $graphLookup, $bucket, $mergeObjects
• MapReduce support with JavaScript engine integration
• Array operators including $pop, $push, $pull, $addToSet
• Change streams & transactions available for integration testing
• Drop-in replacement for most development and testing scenarios

• Complete rewrite of the guide set
• Practical examples and end-to-end use cases
• Dedicated migration playbook from 5.x to 6.x
• Architecture insights and best practices

• Java 21 or newer
• MongoDB 5.0+ for production deployments
• Maven

Maven dependencies:

<dependency>
  <groupId>de.caluga</groupId>
  <artifactId>morphium</artifactId>
  <version>[6.2.0,)</version>
</dependency>
<dependency>
  <groupId>org.mongodb</groupId>
  <artifactId>bson</artifactId>
  <version>4.7.1</version>
</dependency>

Migrating from v5? → docs/howtos/migration-v5-to-v6.md

<dependency>
  <groupId>de.caluga</groupId>
  <artifactId>morphium</artifactId>
  <version>6.2.0</version>
</dependency>

import de.caluga.morphium.Morphium;
import de.caluga.morphium.MorphiumConfig;
import de.caluga.morphium.annotations.*;
import de.caluga.morphium.driver.MorphiumId;
import java.time.LocalDateTime;
import java.util.List;

// Entity definition
@Entity
public class User {
    @Id
    private MorphiumId id;
    private String name;
    private String email;
    private LocalDateTime createdAt;
    // getters/setters
}

// Configuration
MorphiumConfig cfg = new MorphiumConfig();
cfg.connectionSettings().setDatabase("myapp");
cfg.clusterSettings().addHostToSeed("localhost", 27017);
cfg.driverSettings().setDriverName("PooledDriver");

Morphium morphium = new Morphium(cfg);

// Store entity
User user = new User();
user.setName("John Doe");
user.setEmail("[email protected]");
user.setCreatedAt(LocalDateTime.now());
morphium.store(user);

// Query
List<User> users = morphium.createQueryFor(User.class)
    .f("email").matches(".*@example.com")
    .sort("createdAt")
    .asList();

import de.caluga.morphium.messaging.MorphiumMessaging;
import de.caluga.morphium.messaging.Msg;

// Messaging setup
MorphiumMessaging messaging = morphium.createMessaging();
messaging.setSenderId("my-app");
messaging.start();

// Send a message
Msg message = new Msg("orderQueue", "Process Order", "Order #12345");
message.setPriority(5);
message.setTtl(300000); // 5 minutes
messaging.sendMessage(message);

// Receive messages
messaging.addListenerForTopic("orderQueue", (m, msg) -> {
    // process order ...
    return null; // no reply
});

# Environment variables
export MONGODB_URI='mongodb://user:pass@localhost:27017/app?replicaSet=rs0'
export MORPHIUM_DRIVER=inmem

# System properties
mvn -Dmorphium.uri='mongodb://localhost/mydb' test

# Properties file (morphium.properties)
morphium.hosts=mongo1.example.com:27017,mongo2.example.com:27017
morphium.database=myapp
morphium.replicaSet=myReplicaSet

# All tests
mvn test

# Full build with checks
mvn clean verify

# Tagged test selection
mvn test -Dgroups="core,messaging"

# Run against a real MongoDB instance
mvn test -Dmorphium.driver=pooled -Dmorphium.uri=mongodb://localhost/testdb

# Default: in-memory driver (fast, no MongoDB required)
./runtests.sh

# Run tagged suites
./runtests.sh --tags core,messaging

# Parallel runs
./runtests.sh --parallel 8 --tags core

# Retry only failed methods
./runtests.sh --rerunfailed
./runtests.sh --rerunfailed --retry 3

# Single test class
./runtests.sh CacheTests

# Statistics
./runtests.sh --stats
./getFailedTests.sh  # list failed methods

Run ./runtests.sh --help to see every option.

Tests are parameterized to run against multiple drivers. Use --driver to select:

# InMemory only (fastest, default)
./runtests.sh --driver inmem

# Against external MongoDB with all drivers (pooled + single + inmem)
./runtests.sh --uri mongodb://mongo1,mongo2/testdb --driver all

# Against external MongoDB with pooled driver only
./runtests.sh --uri mongodb://mongo1,mongo2/testdb --driver pooled

# Against PoppyDB (auto-starts local server)
./runtests.sh --poppydb --driver pooled  # --morphium-server is a deprecated alias

Complete test coverage requires running against all backends:

# 1. Fast in-memory tests
./runtests.sh --driver inmem

# 2. Real MongoDB tests
./runtests.sh --uri mongodb://your-mongodb/testdb --driver all

# 3. PoppyDB tests
./runtests.sh --poppydb --driver pooled  # --morphium-server is a deprecated alias

New in v6.1

• ✅ Unified test base: All tests now use MultiDriverTestBase with parameterized drivers
• ✅ Driver selection: Each test declares which drivers it supports via @MethodSource
• ✅ Parallel safe: Tests isolated per parallel slot with unique databases

New in v6.0

• ✅ Method-level reruns: --rerunfailed only re-executes failing methods
• ✅ No more hangs: known deadlocks resolved
• ✅ Faster iteration: noticeably quicker partial retries
• ✅ Better filtering: class-name filters now reliable

Run ./runtests.sh --help to see every option.

TestConfig consolidates all test settings. Priority order:

1. System properties (-Dmorphium.*)
2. Environment variables (MORPHIUM_*, MONGODB_URI)
3. src/test/resources/morphium-test.properties
4. Defaults (localhost:27017)

The in-memory driver provides a largely MongoDB-compatible data store fully in memory:

Features

• ✅ Full CRUD operations
• ✅ Rich query operator coverage
• ✅ Aggregation stages such as $match, $group, $project
• ✅ Single-instance transactions
• ✅ Basic change streams
• ✅ JavaScript $where support

Performance

• Significantly faster than external MongoDB for tests
• No network latency
• No disk I/O
• Ideal for CI/CD pipelines

Usage

# All tests with the in-memory driver
./runtests.sh --driver inmem

# Specific tests
mvn test -Dmorphium.driver=inmem -Dtest="CacheTests"

See docs/howtos/inmemory-driver.md for feature coverage and limitations.

PoppyDB (formerly MorphiumServer) runs the Morphium wire-protocol driver in a separate process, allowing it to act as a lightweight, in-memory MongoDB replacement.

Maven dependency (server module):

<dependency>
  <groupId>de.caluga</groupId>
  <artifactId>poppydb</artifactId>
  <version>6.2.0</version>
</dependency>

Building the Server

mvn clean package -pl poppydb -am -Dmaven.test.skip=true

This creates poppydb/target/poppydb-6.2.0-cli.jar.

Running the Server

# Start the server on the default port (17017)
java -jar poppydb/target/poppydb-6.2.0-cli.jar

# Start on a different port
java -jar poppydb/target/poppydb-6.2.0-cli.jar --port 8080

# Start with persistence (snapshots)
java -jar poppydb/target/poppydb-6.2.0-cli.jar --dump-dir ./data --dump-interval 300

Replica Set Support (Experimental)

PoppyDB supports basic replica set emulation. Start multiple instances with the same replica set name and seed list:

java -jar poppydb/target/poppydb-6.2.0-cli.jar --rs-name my-rs --rs-seed host1:17017,host2:17018

Use cases

• Local development without installing MongoDB
• CI environments
• Embedded database for desktop applications
• Smoke-testing MongoDB tooling (mongosh, Compass, mongodump, ...)

Current limitations

• No sharding support
• Some advanced aggregation operators and joins still missing

See docs/poppydb.md for more details on persistence and replica sets.

Organizations run Morphium in production for:

• E-commerce: order processing with guaranteed delivery
• Financial services: coordinating transactions across microservices
• Healthcare: patient-data workflows with strict compliance
• IoT platforms: device state synchronization and command distribution
• Content management: document workflows and event notifications

• Blog: https://caluga.de
• GitHub: sboesebeck/morphium
• Issues: Report bugs or request features on GitHub

We appreciate pull requests! Areas where help is especially welcome:

• InMemoryDriver: expanding MongoDB feature coverage
• Documentation: tutorials, examples, translations
• Performance: profiling and benchmarks
• Tests: broader scenarios and regression coverage

How to contribute

1. Fork the repository
2. Create a feature branch from develop (git checkout -b feature/AmazingFeature develop)
3. Commit your changes (git commit -m 'Add AmazingFeature')
4. Push the branch (git push origin feature/AmazingFeature)
5. Open a pull request against develop (not master)

Important: master is only updated during releases. All PRs must target develop.

Tips

• Respect test tags (@Tag("inmemory"), @Tag("poppydb"))
• Run ./runtests.sh --tags core before submitting
• Update documentation when you change APIs

Apache License 2.0 – see LICENSE for details.

Thanks to every contributor who helped ship Morphium 6.2.0 and to the MongoDB community for continuous feedback.

Questions? Open an issue on GitHub or browse the documentation.

Planning an upgrade? Follow the migration guide.

Enjoy Morphium 6.2.0! 🚀

Stephan Bösebeck & the Morphium team