Quarkus Extension: CDI Integration for Morphium¶

quarkus-morphium is an optional Morphium module that integrates Morphium into Quarkus applications via a CDI producer, type-safe @ConfigMapping configuration, declarative transactions, health checks, Dev Services, Dev UI integration, and GraalVM native-image support. It also pulls in morphium-jakarta-data and generates Jakarta Data @Repository implementations at build time via Gizmo bytecode generation — no runtime reflection, no dynamic proxies.

Optional module — the Morphium core does not depend on it

de.caluga:morphium has zero compile- or runtime dependency on this extension, on Quarkus, or on jakarta.data-api. Building the Morphium reactor without this module (-DskipExtensions) produces an unchanged core. You only need quarkus-morphium if you are building a Quarkus application against MongoDB via Morphium.

What it provides¶

CDI producer — @Inject Morphium morphium; anywhere in a Quarkus bean, backed by a single, application-scoped Morphium instance configured from application.properties.
Type-safe configuration — every setting lives under quarkus.morphium.* as a @ConfigMapping, validated at build time instead of failing at runtime on a typo.
Declarative transactions — @MorphiumTransactional on a CDI bean method wraps the method body in startTransaction()/commitTransaction()/abortTransaction() automatically, with MorphiumTransactionEvent CDI events (BEFORE_COMMIT, AFTER_COMMIT, AFTER_ROLLBACK) for cross-cutting reactions (audit logging, outbox publishing, etc.). Gracefully degrades to non-transactional execution on Azure CosmosDB, which is auto-detected.
Jakarta Data repositories — declare a @Repository interface extending CrudRepository/MorphiumRepository from morphium-jakarta-data; the extension's build-time processor generates the implementation via Gizmo, with no reflection at runtime. See Jakarta Data for the full query-derivation, JDQL, and pagination feature set — everything documented there works identically once generated by this extension.
Health checks — MicroProfile liveness (/q/health/live), readiness (/q/health/ready, with connection-pool metadata), and startup (/q/health/started) probes registered automatically via SmallRye Health.
Dev Services — a MongoDB container (optionally as a single-node replica set, so transactions and change streams work out of the box) starts automatically in dev and test mode when no explicit quarkus.morphium.hosts is configured — no Docker Compose, no manual setup.
Dev UI card — live MongoDB connection info (hosts, database, replica-set mode, container ID) at /q/dev-ui/.
GraalVM native-image support — every @Entity/@Embedded class (and Morphium's own reflection-dependent internals) is registered for reflection at build time; no manual reflect-config.json.
MorphiumId JSON serialization — entities with @Id MorphiumId id serialize to a plain 24-character hex string over REST (both Jackson and JSON-B), and parse back from one — no serializer to write by hand.
Migration runner — a lightweight, MongoDB-backed schema/data migration mechanism (quarkus.morphium.migration.*) with a distributed lock, so multiple application instances don't race to apply the same migration.

Installation¶

<dependency>
  <groupId>de.caluga</groupId>
  <artifactId>quarkus-morphium</artifactId>
  <version>${project.version}</version>
</dependency>

In the Morphium reactor, ${project.version} resolves to whatever version the reactor is currently on (see the root pom.xml). This module follows Morphium's regular release versioning; there is no separate version line to track — building the reactor (mvn -pl quarkus-morphium -am verify) builds this extension against the exact Morphium core version in the same build.

Configuration Reference¶

All properties live under quarkus.morphium.*. This is not the complete list — see the Antora documentation in the module directory (quarkus-morphium/docs/) for every property — but covers the most commonly used ones, each verified directly against the @ConfigMapping source.

Property	Default	Description	Source
`quarkus.morphium.hosts`	`localhost:27017`	Comma-separated `host:port` list	`MorphiumRuntimeConfig.java:52`
`quarkus.morphium.database`	(required)	MongoDB database name	`MorphiumRuntimeConfig.java:55`
`quarkus.morphium.username` / `.password`	--	Optional credentials	`MorphiumRuntimeConfig.java:58,61`
`quarkus.morphium.auth-database`	`admin`	Authentication database	`MorphiumRuntimeConfig.java:65`
`quarkus.morphium.read-preference`	`primary`	Read preference	`MorphiumRuntimeConfig.java:73`
`quarkus.morphium.index-check`	`create-on-startup`	Index management strategy (`create-on-startup`, `warn-on-startup`, `create-on-write-new-col`, `no-check`)	`MorphiumRuntimeConfig.java:92`
`quarkus.morphium.max-connections`	`250`	Connection pool size	`MorphiumRuntimeConfig.java:108`
`quarkus.morphium.max-wait-time`	`2000`	Max wait time (ms) for a pooled connection	`MorphiumRuntimeConfig.java:118`
`quarkus.morphium.default-query-timeout-ms`	`0` (disabled)	Server-side `maxTimeMS` applied to queries without an explicit per-query timeout	`MorphiumRuntimeConfig.java:133`
`quarkus.morphium.atlas-url`	--	MongoDB Atlas SRV connection string (overrides `hosts`)	`MorphiumRuntimeConfig.java:139`
`quarkus.morphium.driver-name`	`PooledDriver`	`PooledDriver` (production) or `InMemDriver` (tests, no MongoDB needed)	`MorphiumRuntimeConfig.java:146`
`quarkus.morphium.replica-set-name`	--	MongoDB replica set name (required for transactions)	`MorphiumRuntimeConfig.java:153`
`quarkus.morphium.connect-retries`	`5`	Connection attempts before giving up	`MorphiumRuntimeConfig.java:162`
`quarkus.morphium.cache.read-cache-enabled`	`true`	Enable query result cache	`CacheConfig.java:31`
`quarkus.morphium.cache.global-valid-time`	`60000`	Cache TTL in milliseconds	`CacheConfig.java:27`
`quarkus.morphium.local-date-time.use-bson-date`	--	Store `LocalDateTime` as BSON `ISODate`	`LocalDateTimeConfig.java`
`quarkus.morphium.ssl.enabled`	`false`	Enable TLS	`SslConfig.java:48`
`quarkus.morphium.ssl.auth-mechanism`	--	`MONGODB-X509` for client-certificate auth	`SslConfig.java:59`
`quarkus.morphium.ssl.keystore-path` / `.keystore-password`	--	Keystore for client-cert auth / mutual TLS	`SslConfig.java:65,68`
`quarkus.morphium.ssl.truststore-path` / `.truststore-password`	--	Truststore for server certificate validation	`SslConfig.java:74,77`
`quarkus.morphium.ssl.invalid-hostname-allowed`	`false`	Allow invalid hostnames (dev only)	`SslConfig.java:84`
`quarkus.morphium.ssl.tls-configuration-name`	--	Use a named Quarkus TLS registry configuration instead of explicit keystore/truststore paths	`SslConfig.java:108`
`quarkus.morphium.devservices.enabled`	`true`	Enable automatic MongoDB container in dev/test mode	`MorphiumDevServicesBuildTimeConfig.java:45`
`quarkus.morphium.devservices.image-name`	`mongo:8`	Docker image for Dev Services	`MorphiumDevServicesBuildTimeConfig.java:52`
`quarkus.morphium.devservices.database-name`	`morphium-dev`	Database name injected by Dev Services	`MorphiumDevServicesBuildTimeConfig.java:59`
`quarkus.morphium.devservices.replica-set`	`true`	Start MongoDB as a single-node replica set (enables transactions)	`MorphiumDevServicesBuildTimeConfig.java:72`
`quarkus.morphium.health.enabled`	`true`	Enable liveness/readiness/startup health checks	`MorphiumHealthBuildTimeConfig.java:41`
`quarkus.morphium.migration.migrate-at-start`	`false`	Run pending migrations automatically on startup	`MorphiumMigrationConfig.java:40`
`quarkus.morphium.migration.change-log-collection`	`morphiumChangeLog`	Collection tracking executed migrations	`MorphiumMigrationConfig.java:44`
`quarkus.morphium.migration.lock-collection`	`morphiumMigrationLock`	Collection used for the distributed migration lock	`MorphiumMigrationConfig.java:48`
`quarkus.morphium.migration.lock-ttl-seconds`	`60`	Migration-lock TTL in seconds	`MorphiumMigrationConfig.java:56`

Quick Example¶

@Entity(collectionName = "products")
public class Product {
    @Id private MorphiumId id;
    private String name;
    private double price;
    private String category;
    @Version private long version;
    // getters/setters omitted
}

@Repository
public interface ProductRepository extends MorphiumRepository<Product, MorphiumId> {
    List<Product> findByCategory(String category);

    @OrderBy("price")
    List<Product> findByPriceGreaterThan(double minPrice);
}

@ApplicationScoped
public class ProductService {
    @Inject ProductRepository products;

    @MorphiumTransactional
    public Product create(String name, double price, String category) {
        var p = new Product();
        p.setName(name);
        p.setPrice(price);
        p.setCategory(category);
        return products.insert(p);
    }
}

quarkus.morphium.database=my-app-db
# Dev Services starts MongoDB automatically — no further config needed in dev/test.

Testing without Docker¶

%test.quarkus.morphium.driver-name=InMemDriver
%test.quarkus.morphium.database=test-db

InMemDriver is Morphium's in-memory MongoDB emulation — @QuarkusTest classes run against it with no container and no external MongoDB, exactly like the core Morphium test suite.

Full Documentation¶

This page is an overview. The complete documentation — getting started, entity mapping, configuration reference, transactions, health checks, Dev Services, Jakarta Data repositories, testing, and advanced topics — lives as an Antora documentation module in the repository, at quarkus-morphium/docs/ (source pages under quarkus-morphium/docs/modules/ROOT/pages/):

quarkus-morphium/docs/modules/ROOT/pages/

Antora docs are not part of this site's build

This MkDocs site (the pages under docs/, including this one) and the Antora documentation under quarkus-morphium/docs/ are two separate, coexisting toolchains — the Antora source is not currently built or published by this repository's deploy-docs.yml workflow. Until a publishing decision is made, browse the Antora pages directly on GitHub via the link above, or render them locally with the Antora CLI from quarkus-morphium/docs/antora.yml.

See also Jakarta Data for the framework-agnostic repository runtime that this extension builds on, and PoppyDB for Morphium's other optional module.