guicedee-persistence
Reactive JPA persistence with Hibernate Reactive 7, Vert.x 5 SQL clients, and Mutiny sessions inside GuicedEE: DatabaseModule setup, persistence.xml configuration, multi-database support, @EntityManager scoping, and environment variable resolution. Use when adding database persistence, configuring Hibernate Reactive, creating DatabaseModule subclasses, wiring Mutiny.SessionFactory, or managing multiple persistence units.
Best use case
guicedee-persistence is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Reactive JPA persistence with Hibernate Reactive 7, Vert.x 5 SQL clients, and Mutiny sessions inside GuicedEE: DatabaseModule setup, persistence.xml configuration, multi-database support, @EntityManager scoping, and environment variable resolution. Use when adding database persistence, configuring Hibernate Reactive, creating DatabaseModule subclasses, wiring Mutiny.SessionFactory, or managing multiple persistence units.
Teams using guicedee-persistence should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/guicedee-persistence/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How guicedee-persistence Compares
| Feature / Agent | guicedee-persistence | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Reactive JPA persistence with Hibernate Reactive 7, Vert.x 5 SQL clients, and Mutiny sessions inside GuicedEE: DatabaseModule setup, persistence.xml configuration, multi-database support, @EntityManager scoping, and environment variable resolution. Use when adding database persistence, configuring Hibernate Reactive, creating DatabaseModule subclasses, wiring Mutiny.SessionFactory, or managing multiple persistence units.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# GuicedEE Persistence
Reactive JPA persistence using Hibernate Reactive 7 and Vert.x 5 SQL clients, fully managed by the GuicedEE lifecycle.
## Core Concept
Extend `DatabaseModule`, point it at a `persistence.xml` unit, and the module wires a `Mutiny.SessionFactory` into Guice — fully reactive, annotation-driven, with built-in support for PostgreSQL, MySQL, SQL Server, Oracle, and DB2.
## Required Flow
1. Add `com.guicedee:persistence` dependency.
2. Create a `persistence.xml` with `ReactivePersistenceProvider`:
```xml
<persistence xmlns="https://jakarta.ee/xml/ns/persistence" version="3.0">
<persistence-unit name="mydb">
<provider>org.hibernate.reactive.provider.ReactivePersistenceProvider</provider>
<class>com.example.entities.User</class>
<properties>
<property name="jakarta.persistence.jdbc.url"
value="${DB_URL:jdbc:postgresql://localhost:5432/mydb}"/>
<property name="jakarta.persistence.jdbc.user" value="${DB_USER:postgres}"/>
<property name="jakarta.persistence.jdbc.password" value="${DB_PASSWORD:secret}"/>
<property name="hibernate.hbm2ddl.auto" value="update"/>
</properties>
</persistence-unit>
</persistence>
```
3. Create a `DatabaseModule` subclass:
```java
public class MyDatabaseModule extends DatabaseModule<MyDatabaseModule> {
@Override
protected String getPersistenceUnitName() { return "mydb"; }
@Override
protected ConnectionBaseInfo getConnectionBaseInfo(
PersistenceUnitDescriptor unit, Properties properties) {
return ConnectionBaseInfoFactory.createConnectionBaseInfo("postgresql");
}
}
```
4. Register via JPMS:
```java
module my.app {
requires com.guicedee.persistence;
provides com.guicedee.client.services.lifecycle.IGuiceModule
with my.app.MyDatabaseModule;
}
```
5. Inject `Mutiny.SessionFactory` and use reactive sessions:
```java
@Inject
private Mutiny.SessionFactory sessionFactory;
public Uni<User> createUser(String name) {
User user = new User();
user.setName(name);
return sessionFactory.withTransaction(session ->
session.persist(user).replaceWith(user));
}
```
## Startup Flow
```
IGuiceContext.instance().inject()
└─ IGuiceModule hooks
└─ MyDatabaseModule (extends DatabaseModule)
├─ Parse persistence.xml
├─ IPropertiesEntityManagerReader SPIs (env var resolution, DB-specific props)
├─ IPropertiesConnectionInfoReader SPIs
├─ ConnectionBaseInfo.toPooledDatasource() (Vert.x SQL pool init)
└─ JtaPersistModule
├─ bind PersistService @Named("mydb")
└─ bind Mutiny.SessionFactory @Named("mydb") + default
└─ IGuicePostStartup hooks
└─ DatabaseModule.postLoad()
└─ PersistService.start() (creates EntityManagerFactory on Vert.x context)
└─ IGuicePreDestroy hooks
└─ DatabaseModule.onDestroy()
└─ PersistService.stop()
```
## @EntityManager Annotation
| Attribute | Default | Purpose |
|---|---|---|
| `value` | `""` | Persistence unit name (maps to `persistence.xml`) |
| `allClasses` | `true` | Include all entity classes or only the annotated package |
| `defaultEm` | `true` | Mark as the default `SessionFactory` binding |
Apply at class level (on `DatabaseModule` subclasses) or package level (`package-info.java`) to scope entities to specific persistence units.
## Multiple Persistence Units
Bind multiple `DatabaseModule` subclasses with distinct `@Named` qualifiers. One should be marked as the default with `defaultEm = true`:
```java
@Inject @Named("orders")
private Mutiny.SessionFactory ordersFactory;
@Inject @Named("users")
private Mutiny.SessionFactory usersFactory;
```
## Supported Databases
Built-in `ConnectionBaseInfo` implementations:
- `postgresql` — PostgreSQL via Vert.x PG Client
- `mysql` — MySQL via Vert.x MySQL Client
- `sqlserver` — SQL Server via Vert.x MSSQL Client
- `oracle` — Oracle via Vert.x Oracle Client
- `db2` — DB2 via Vert.x DB2 Client
## Environment Variable Resolution
`${VAR_NAME}` placeholders in `persistence.xml` properties are resolved from system properties or environment variables. Default values supported with `${VAR_NAME:default}` syntax.
## Non-Negotiable Constraints
- Always use `ReactivePersistenceProvider` — standard JPA providers are not supported.
- `persistence.xml` must exist in `META-INF/`.
- DatabaseModule subclass must be registered as an `IGuiceModule` SPI.
- Entity packages must `opens` to `com.fasterxml.jackson.databind` and `org.hibernate.orm.core`.
- Module must `requires com.guicedee.persistence;`.
- SPI implementations must be dual-registered for tests to find services (`module-info.java` + `META-INF/services/`).Related Skills
guicedee-websockets
RFC 6455 WebSocket support for GuicedEE using Vert.x 5: call-scoped connections, action-based message routing via IWebSocketMessageReceiver SPI, group management and broadcasting, WebSocketServerOptions, and lifecycle hooks. Use when adding WebSocket messaging, implementing real-time communication, managing WebSocket groups, or creating message receivers.
guicedee-webservices
SOAP web services for GuicedEE using Apache CXF conventions: JAX-WS annotations (@WebService, @WebMethod, @WebParam, @WebResult), code-first and WSDL-first approaches, endpoint publishing, CXF interceptors and logging, MTOM, WS-Security (WSS4J), SOAP 1.1/1.2 bindings, and Guice DI integration. Use when creating SOAP services, publishing JAX-WS endpoints, configuring CXF bindings, or adding WS-Security.
guicedee-web
Bootstrap reactive HTTP/HTTPS servers with Vert.x 5 inside GuicedEE: Router setup, BodyHandler configuration, TLS/HTTPS, SPI extension points (VertxRouterConfigurator, VertxHttpServerOptionsConfigurator, VertxHttpServerConfigurator), per-verticle sub-routers, and environment-driven configuration. Use when setting up the Vert.x web server, configuring HTTP/HTTPS, adding custom routes or middleware, or managing server options.
guicedee-vertx
Build reactive services using Vert.x 5 inside the GuicedEE DI lifecycle: event-bus consumers, publishers, verticle deployment, codecs, throttling, clustering, SPI hooks, and JPMS module setup. Use when adding Vert.x event-bus messaging, deploying verticles, wiring reactive endpoints with Guice injection, configuring Vert.x runtime options, or implementing custom codecs and cluster managers.
guicedee-service-registry
Named service registry with health-aware resolution for GuicedEE. Register services by simple name, auto-construct URLs from cloud DNS suffix, monitor health status, resolve services via registry:name prefix or bare name in rest-client @Endpoint. Supports aliases, multiple external URLs, Kubernetes internal URLs, and per-service health paths. Use when registering named services, checking service health, resolving service URLs by name, or integrating with rest-client for service-to-service calls.
guicedee-rest
Build Jakarta REST (JAX-RS) services on Vert.x 5 inside GuicedEE: @Path/@GET/@POST route registration, parameter binding (@PathParam, @QueryParam, @HeaderParam, etc.), Guice-managed resource classes, response handling, content negotiation, and JPMS module setup. Use when creating REST endpoints, configuring Jakarta REST resources, or wiring JAX-RS services with Guice injection.
guicedee-rest-client
Annotation-driven REST client for GuicedEE using Vert.x 5 WebClient: @Endpoint declarations, RestClient<Send, Receive> injection, authentication strategies (Bearer, Basic, API Key, OAuth2, mTLS), path parameters, environment variable overrides, package-level endpoints, service registry integration (bare name or registry: prefix), and RestClientConfigurator SPI. Use when making outbound REST calls, configuring REST client endpoints, or wiring reactive HTTP clients with Guice injection.
guicedee-rabbitmq
Annotation-driven RabbitMQ integration for GuicedEE with Vert.x 5: @RabbitConnectionOptions, @QueueExchange, @QueueDefinition, QueueConsumer/QueuePublisher injection, exchange management, queue options (priority, TTL, prefetch), publisher confirms, environment variable overrides, and verticle-scoped connections. Use when adding RabbitMQ messaging, declaring exchanges and queues, creating consumers and publishers, or configuring AMQP topology.
guicedee-openapi
Automatic OpenAPI 3.1 spec generation and serving for GuicedEE with Vert.x 5: scans Jakarta REST resources at startup, serves /openapi.json and /openapi.yaml endpoints, Swagger annotations support, @OpenAPIDefinition configuration, and companion Swagger UI module. Use when generating API documentation, serving OpenAPI specs, or configuring Swagger annotations on REST resources.
guicedee-metrics
Application metrics for GuicedEE using Vert.x 5 Dropwizard Metrics and MicroProfile Metrics 5.1: @Counted, @Timed, @MetricMethod annotations, Guice AOP interceptors, Prometheus scrape endpoint, Graphite reporting, JMX exposure, @MetricsOptions configuration, environment variable overrides, and Vert.x built-in metrics (event bus, HTTP, pools). Use when adding application metrics, configuring Prometheus endpoints, creating custom counters/timers, or monitoring Vert.x internals.
guicedee-mail-client
Annotation-driven SMTP mail client for GuicedEE with Vert.x 5: @MailConnectionOptions for SMTP server configuration, MailService injection for sending text/HTML/multipart emails with attachments, connection pooling, StartTLS/SSL support, DKIM signing, environment variable overrides, and graceful shutdown. Use when sending emails via SMTP, configuring mail connections, or injecting mail services.
guicedee-kafka
Annotation-driven Kafka integration for GuicedEE with Vert.x 5: @KafkaConnectionOptions, @KafkaTopicDefinition, @KafkaTopicCreate, KafkaTopicConsumer/KafkaTopicPublisher injection, KafkaAdminClient binding, per-topic consumers, manual offset commit, worker thread support, partition assignment and revocation handlers, environment variable overrides, call-scoped message handling, and graceful shutdown. Use when adding Kafka messaging, declaring topic consumers and publishers, creating topics via admin client, or configuring Kafka connections.