bmad-method-quarkus 1.0.3 → 1.0.4

package/src/bmm-skills/agents/bmad-quarkus-dev/skills/quarkus-sql-jdbc-agroal/SKILL.md

@@ -1,275 +0,0 @@
----
-name: quarkus-sql-jdbc-agroal
-description: Standard for executing SQL queries, updates, batches, and transactions in Quarkus WITHOUT Panache or any ORM — using the Agroal connection pool with plain JDBC (default) or the reactive Vert.x SQL client (justified cases only). Use this skill whenever the user writes or reviews ANY repository, DAO, SQL statement, SELECT/INSERT/UPDATE/DELETE, batch operation, transaction, pagination query, jsonb access, connection pool configuration, or mentions Agroal, JDBC, PreparedStatement, datasource, or "query the database" — all persistence code must follow these patterns. Data access lives in the slice `<Slice>Sql` class with `Connection` as the first parameter of every method (see quarkus-hexagonal-core skill); there are no repositories, DAOs or row-mapper classes.
----
-
-# SQL Execution Standard: Agroal + Plain JDBC (No ORM)
-
-Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults where they conflict.
-
-Persistence is explicit SQL through the Agroal pool. No Panache, no Hibernate, no reflection-based row mappers. Data access lives in the slice's `<Slice>Sql` class — the driven adapter of the vertical slice (see quarkus-hexagonal-core skill). There are no `*Repository` ports and no `Jdbc*` adapters: one `Sql` class per slice, called only by that slice's `Handler`.
-
-One clarification to keep teams from chasing ghosts: **Agroal is a JDBC (blocking) pool** — there is no "reactive Agroal". The reactive path in Quarkus is the Vert.x SQL client (`quarkus-reactive-pg-client`) with its own pool. Default choice here is **Agroal + JDBC** (simpler, dominant skill base, works perfectly in native); reactive client only for measured hot paths with extreme concurrency (see §7).
-
-## 1. Datasource configuration (Agroal)
-
-```properties
-quarkus.datasource.db-kind=postgresql
-quarkus.datasource.username=${DB_USER}
-quarkus.datasource.password=${DB_PASSWORD}
-quarkus.datasource.jdbc.url=jdbc:postgresql://${DB_HOST}:5432/${DB_NAME}
-
-# Pool sizing: start small; size = concurrent transactions, NOT concurrent users
-quarkus.datasource.jdbc.min-size=2
-quarkus.datasource.jdbc.max-size=16
-quarkus.datasource.jdbc.acquisition-timeout=5S
-
-# Hygiene
-quarkus.datasource.jdbc.validation-query-sql=SELECT 1
-quarkus.datasource.jdbc.leak-detection-interval=60S
-quarkus.datasource.jdbc.idle-removal-interval=5M
-quarkus.datasource.jdbc.max-lifetime=30M
-
-# Observability (pairs with quarkus-observability-otel skill)
-quarkus.datasource.jdbc.telemetry=true
-quarkus.datasource.metrics.enabled=true
-```
-
-Rules:
-- `max-size` per pod must respect the DB's `max_connections` budget across ALL replicas of ALL services. Coordinate with DBAs; 16 is a ceiling, not a target.
-- Leak detection stays on in every environment — a logged leak is a bug, treat it as such.
-- Multiple datasources: named (`quarkus.datasource."audit".jdbc.url=...`) and injected with `@DataSource("audit")`.
-
-## 2. Injection and the golden resource pattern
-
-Inject the pool, never raw drivers, never `DriverManager`. The `Sql` class holds the `DataSource` but **does not open connections** — the `Handler` opens exactly one per business operation and passes it in (see §3):
-
-```java
-@ApplicationScoped
-public class CreatePartyIndividualSql {
-
-    @Inject
-    DataSource dataSource;      // injected for symmetry/health checks; connections come from the Handler
-}
-```
-
-**Every method's first parameter is `Connection conn`.** That signature is the contract the `Handler` must honour exactly — same name, order, arity and types. Statements use **try-with-resources on PreparedStatement AND ResultSet** (the `Connection` is owned and closed by the caller). A missed close under load exhausts the pool and takes the native pod down:
-
-```java
-private static final String SELECT_PARTY_BY_ID = """
-    SELECT id, tenant_id, party_type, status, created_at
-      FROM customer.party
-     WHERE id = ?
-       AND tenant_id = ?
-    """;
-
-public PartyDto findPartyById(Connection conn, UUID id, String tenantId) throws SQLException {
-    try (PreparedStatement ps = conn.prepareStatement(SELECT_PARTY_BY_ID)) {
-        ps.setObject(1, id);
-        ps.setString(2, tenantId);
-        try (ResultSet rs = ps.executeQuery()) {
-            return rs.next() ? mapRow(rs) : null;
-        }
-    }
-}
-```
-
-Absolute rules:
-- SQL as `private static final String` text blocks (comma-first concatenation is equally acceptable), schema-qualified. Never concatenate user input — `PreparedStatement` placeholders ALWAYS (SQL injection + plan cache).
-- Quote reserved-word schemas and tables: `"order".party`. Verify the real schema name before writing the query.
-- Dynamic WHERE clauses: build from a whitelist of column/operator constants, values still as placeholders.
-- Methods declare `throws SQLException` and never catch it — the `Handler` translates it (§8). No `commit`, `rollback` or `setAutoCommit` here, ever.
-- One private `mapRow(ResultSet) -> Dto` per `Sql` class. Rows map to the slice's own DTOs; there is no separate domain entity and no `*RowMapper` class. No reflection mappers: they break native and hide cost.
-
-Naming (canonical rules in the quarkus-hexagonal-core skill):
-
-| Artifact | Convention | Example |
-|---|---|---|
-| Data access class | `${SERVICE_CLASS_PREFIX}Sql`, in the slice folder | `CreatePartyIndividualSql` |
-| Method | imperative verb, matching the query | `insertParty`, `findPartyById`, `listPartiesByTenant` |
-| SQL constant | `UPPER_SNAKE_CASE` matching the method, `private static final String` | `SELECT_PARTY_BY_ID`, `INSERT_PARTY` |
-| Table / column | `snake_case`, singular table name, schema-qualified | `customer.party`, `created_at` |
-| Row target | the slice's `*Dto` | `PartyDto` |
-| Technical exception | `PersistenceException` + specific subtypes (§8) | `TransientPersistenceException` |
-
-Never name this class `*Repository`, `*Dao`, `*Manager` or `*Service` — those suffixes are banned by the core skill's ArchUnit rules. An `Sql` class that grows an `if` encoding a business rule has swallowed logic that belongs in the `Handler`.
-
-## 3. Transactions and connections: one of each, on `Handler.process()`
-
-The unit of work is the business operation, which in a slice is `process()`. The `Handler` opens **one** `Connection` in `execution()` and passes it to every `Sql` call:
-
-```java
-@ApplicationScoped
-public class CreatePartyIndividualHandler {
-
-    @Inject DataSource dataSource;
-    @Inject CreatePartyIndividualSql sql;
-
-    @Transactional                                    // the ONLY @Transactional in the slice
-    public CreatePartyIndividualResponseDto process(CreatePartyIndividualRequestDto request) {
-        validate(request);
-        return getResult(execution(request));
-    }
-
-    private UUID execution(CreatePartyIndividualRequestDto request) {
-        try (Connection conn = dataSource.getConnection()) {          // exactly one, for the whole operation
-            UUID partyId = sql.insertParty(conn, request.getTenantId(), "Individual",
-                "Active", request.getCreatedBy());
-            sql.insertIndividual(conn, partyId, request.getGivenName(), request.getFamilyName());
-            sql.insertOutboxEvent(conn, partyId, "party", EVENT_TYPE, payloadJson(partyId, request), traceparent());
-            return partyId;
-        } catch (SQLException e) {
-            throw SqlStateTranslator.translate("PTY-500-001", e);      // unchecked -> container rolls back
-        }
-    }
-}
-```
-
-**Why the explicit `Connection` parameter (performance):** inside an active JTA transaction Agroal returns the *same* enlisted connection for every `getConnection()` call, so both styles cost one physical connection. The difference shows on **read paths that carry no `@Transactional`** — there, a per-method `ds.getConnection()` takes *N* pool leases for *N* queries, each with its own acquisition and return. Passing `conn` makes every path, transactional or not, cost exactly one lease. It also keeps session state (`statement_timeout`, prepared-statement cache, temp tables) coherent across the operation.
-
-- `@Transactional` goes on `process()` only — never on a private method (CDI interceptors don't fire on self-invocation, so the transaction would silently never open), never on the `Sql` class.
-- **Read-only slices skip `@Transactional` entirely.** A single `SELECT`, or several reads that tolerate a non-repeatable view, are cheaper without a JTA transaction — still one `Connection`, opened and closed in `execution()`. Add the annotation the moment there is a write, or when several reads must see one snapshot.
-- Runtime exceptions roll back by default; `BusinessException` extends `RuntimeException`, so throwing it rolls back — correct by construction. A checked `SQLException` would **not** roll back, which is why §8 translation is mandatory.
-- Programmatic control when annotations don't fit (loops with per-item commit, batch jobs) — from a `common/` bean or a `*Job`, never from inside a slice `Handler`:
-
-```java
-QuarkusTransaction.requiringNew().timeout(30).run(() -> { ...sql calls... });
-```
-
-- Never call `con.commit()`/`rollback()`/`setAutoCommit()` anywhere. The core skill ships a CI `grep` gate for exactly these three tokens.
-
-## 4. Updates, inserts, upserts, generated keys
-
-```java
-private static final String INSERT_PARTY = """
-    INSERT INTO customer.party (tenant_id, party_type, status, created_by, updated_by)
-         VALUES (?, ?, ?, ?, ?)
-      RETURNING id
-    """;
-
-public UUID insertParty(Connection conn, String tenantId, String partyType,
-                        String status, String createdBy) throws SQLException {
-    try (PreparedStatement ps = conn.prepareStatement(INSERT_PARTY)) {
-        ps.setString(1, tenantId);
-        ps.setString(2, partyType);
-        ps.setString(3, status);
-        ps.setString(4, createdBy);
-        ps.setString(5, createdBy);
-        try (ResultSet rs = ps.executeQuery()) {
-            rs.next();
-            return rs.getObject("id", UUID.class);
-        }
-    }
-}
-```
-
-- **Generated ids**: when the PK has a database default (`id uuid DEFAULT customer.uuidv7() NOT NULL`), exclude `id` from the column list and never bind it. Read it back with `RETURNING id` + `executeQuery()` — preferred over `getGeneratedKeys()`.
-- Check `executeUpdate()` counts — 0 rows on an expected UPDATE is a bug or a concurrency signal, not a success. The `Handler` decides what that means; `Sql` just returns the count.
-- Optimistic locking: `version` column, `UPDATE ... WHERE id = ? AND version = ?`; 0 rows → the `Handler` throws `StaleVersionException` (code-carrying, in `common/exception`) with the slice's conflict code → 409 via its dedicated mapper (see quarkus-error-handling-i18n skill). It is not SQLState-derived — no `SQLException` occurs, so `SqlStateTranslator` never sees it; the `Handler` checks the update count. Do NOT name it `ConcurrentModificationException` — it shadows `java.util.ConcurrentModificationException` and an accidental import turns the 409 mapping into a 500.
-- Upserts: `ON CONFLICT ... DO UPDATE` explicitly; never SELECT-then-INSERT races. A unique-violation (`23505`) surfacing as a `SQLException` is translated by the `Handler` (§8), not swallowed here.
-
-## 5. Batches, pagination, jsonb
-
-**Batch** (bulk inserts/updates — outbox relays, imports):
-
-```java
-public int[] insertPartiesBatch(Connection conn, List<PartyDto> items) throws SQLException {
-    try (PreparedStatement ps = conn.prepareStatement(INSERT_PARTY)) {
-        for (PartyDto item : items) {
-            bind(ps, item);
-            ps.addBatch();
-        }
-        return ps.executeBatch();   // add ?reWriteBatchedInserts=true to the JDBC URL (Postgres)
-    }
-}
-```
-
-Chunk batches (500–1000) inside long jobs; combine with `QuarkusTransaction` per chunk, driven from a `*Job` in `common/`, not from a slice `Handler`.
-
-**Pagination**: keyset over OFFSET for anything user-facing/deep:
-
-```sql
-SELECT ... FROM app_user WHERE (created_at, id) < (?, ?) ORDER BY created_at DESC, id DESC LIMIT ?
-```
-
-OFFSET/LIMIT acceptable for TMF `offset/limit` list operations with bounded depth; when aggregations are involved, paginate FIRST in a CTE, then join/aggregate over the page — never aggregate the full set and paginate last.
-
-**jsonb** (audit `context`, outbox `payload` — see observability/kafka skills):
-
-```java
-var pgo = new org.postgresql.util.PGobject();
-pgo.setType("jsonb");
-pgo.setValue(json);          // serialized with Jackson/JsonObject, never string-built
-ps.setObject(5, pgo);
-```
-
-Read side: `rs.getString("context")` then parse. Index jsonb lookups you actually query (`(context->>'trace_id')`).
-
-## 6. A tiny helper is allowed; a framework is not
-
-To kill boilerplate, ONE small internal helper class (~50 lines) per service or shared lib is the sanctioned maximum:
-
-```java
-public final class Jdbc {   // common/util — the one sanctioned exception to the banned-suffix rule
-    @FunctionalInterface public interface RowMapper<T> { T map(ResultSet rs) throws SQLException; }
-
-    public static <T> Optional<T> queryOne(Connection conn, String sql, RowMapper<T> m, Object... params) throws SQLException { ... }
-    public static <T> List<T> queryList(Connection conn, String sql, RowMapper<T> m, Object... params) throws SQLException { ... }
-    public static int update(Connection conn, String sql, Object... params) throws SQLException { ... }
-}
-```
-
-Note the signatures take `Connection`, not `DataSource` — the helper must not open connections either, or it defeats the one-lease-per-operation rule of §3.
-
-- Pure delegation to the try-with-resources pattern above; no reflection, no annotations, no SQL generation. If someone proposes adding criteria builders or entity mapping to it, that's an ORM growing back — reject.
-- The class is named `Jdbc` — a namespace, not `JdbcUtils`/`JdbcHelper`. The banned-suffix ArchUnit rule (see quarkus-hexagonal-core skill) exists precisely to stop this class from becoming a junk drawer.
-- jOOQ (code-gen, type-safe SQL) MAY be evaluated as an alternative via formal ADR; MyBatis/Hibernate remain excluded.
-
-## 7. Blocking model: worker threads or virtual threads (and when reactive)
-
-JDBC blocks. Never run it on the event loop:
-
-- Quarkus REST resources are blocking by default when returning plain types — fine as-is.
-- Reactive signatures (`Uni`), Kafka consumers, gRPC: mark `@Blocking` or hop to a worker pool (see grpc/kafka skills).
-- **Virtual threads**: `@RunOnVirtualThread` on JDBC-heavy endpoints is the modern default for high-concurrency blocking work (Java 25 baseline; synchronized-block pinning is fixed since JDK 24) — cheap threads, same simple code. Caveat: keep pool `max-size` as the real ceiling; virtual threads make it easy to pile up on `acquisition-timeout`.
-- **Reactive SQL client** (`quarkus-reactive-pg-client`, Vert.x pool — NOT Agroal): only for measured hot paths (extreme fan-in, streaming thousands of rows). It's a different programming model and a second pool to size; adopting it in a service requires an ADR. Do not mix both models in the same repository class.
-
-## 8. SQLException translation
-
-`Sql` methods propagate `SQLException`; the `Handler` catches it once, in `execution()`, and translates it through `SqlStateTranslator` (`common/error`) so nothing checked ever escapes `process()` — a checked exception would not trigger the container rollback:
-
-```java
-} catch (SQLException e) {
-    throw SqlStateTranslator.translate("PTY-500-001", e);   // default code if the state is not mapped
-}
-```
-
-| SQLState | Meaning | Resulting exception (all unchecked) |
-|---|---|---|
-| `23505` | unique violation | `BusinessException` with the slice's conflict code (→ 409) |
-| `23503` | FK violation | `BusinessException` with the slice's integrity code (→ 409/422) |
-| `40001` / `40P01` | serialization failure / deadlock | retryable `TransientPersistenceException` |
-| `57014` | statement timeout/cancel | `PersistenceTimeoutException` |
-| other | infrastructure failure | `PersistenceException(code, e)` (→ 500) |
-
-Every resulting code is registered in `ErrorCatalog` and present in all locale bundles (see quarkus-error-handling-i18n skill). The client sees a localized message; the `SQLException` stays in the logs.
-
-Set `statement_timeout` (session or per-datasource via `quarkus.datasource.jdbc.additional-jdbc-properties.options=-c statement_timeout=5000`) so runaway queries fail fast instead of holding pool connections.
-
-## 9. Testing
-
-- `<Slice>Sql` tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies). Obtain a `Connection` in the test and pass it in, exactly as the `Handler` does.
-- `<Slice>Handler` tests are pure Mockito with a mocked `Sql` — no database (see quarkus-hexagonal-core skill).
-- Flyway migrations run at test start (`quarkus.flyway.migrate-at-start=true`) — tests validate DDL and queries together.
-- Native verification: `@QuarkusIntegrationTest` re-runs the same tests against the binary.
-
-## Checklist for a new `Sql` method
-
-0. Names follow the canonical table above (`<Slice>Sql` class, imperative method name, `UPPER_SNAKE` SQL constant).
-1. First parameter is `Connection conn`; the method declares `throws SQLException` and opens no connection of its own.
-2. SQL text block constant, schema-qualified, reserved words quoted, placeholders only; whitelist for any dynamic fragment.
-3. try-with-resources on statement/resultset (the caller owns the connection).
-4. No `commit`/`rollback`/`setAutoCommit`; the transaction boundary is `Handler.process()`.
-5. `executeUpdate()` count returned or checked; `SQLException` propagated for the `Handler` to translate, never swallowed.
-6. Generated ids via `RETURNING`; jsonb via `PGobject`; batch + chunking for bulk; keyset pagination if deep.
-7. Rows mapped by hand into the slice's `*Dto`; Dev Services test written.