# Quarkus Extension: CDI Integration for Morphium

`quarkus-morphium` is an **optional Morphium module** that integrates Morphium into
[Quarkus](https://quarkus.io) 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`](jakarta-data.md) and generates Jakarta Data `@Repository`
implementations at **build time** via Gizmo bytecode generation — no runtime
reflection, no dynamic proxies.

!!! note "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](jakarta-data.md) 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

```xml
<dependency>
  <groupId>de.caluga</groupId>
  <artifactId>quarkus-morphium</artifactId>
  <version>6.3.9</version>
</dependency>
```

This module follows Morphium's regular release versioning and is released in lockstep
with Morphium core; 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.use-bson-date-for-java-time` | -- | Store `Instant`, `LocalDate`, `LocalTime` and `LocalDateTime` as BSON `ISODate`. Unset leaves the previous per-type behaviour untouched. Mapper path only: maps you build yourself (raw driver commands, the update map of `findOneAndUpdate`) need `java.util.Date`, see [configuration reference](configuration-reference.md#usebsondateforjavatime-where-it-applies) | `MorphiumRuntimeConfig.java` |
| `quarkus.morphium.local-date-time.use-bson-date` | `true` | *Deprecated* (removal: 7.0), use `use-bson-date-for-java-time`; reaches `LocalDateTime` only | `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

```java
@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);
    }
}
```

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

## Testing without Docker

```properties
%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](https://antora.org)
documentation module in the repository, at `quarkus-morphium/docs/` (source pages under
`quarkus-morphium/docs/modules/ROOT/pages/`):

[`quarkus-morphium/docs/modules/ROOT/pages/`](https://github.com/sboesebeck/morphium/tree/develop/quarkus-morphium/docs/modules/ROOT/pages)

!!! note "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](https://docs.antora.org/antora/latest/) from
    `quarkus-morphium/docs/antora.yml`.

See also [Jakarta Data](jakarta-data.md) for the framework-agnostic repository runtime
that this extension builds on, and [PoppyDB](poppydb.md) for Morphium's other optional
module.