bmad-method-quarkus 1.0.2 → 1.0.3

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

@@ -1,13 +1,13 @@
 ---
 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, including repository/adapter/row-mapper naming.
+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. Repositories are adapters in `infrastructure/persistence` implementing outbound ports (see quarkus-hexagonal-core skill).
+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).
 
@@ -42,131 +42,149 @@ Rules:
 
 ## 2. Injection and the golden resource pattern
 
-Inject the pool, never raw drivers, never `DriverManager`:
+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 JdbcUserRepository implements UserRepository {
+public class CreatePartyIndividualSql {
 
-    private final AgroalDataSource ds;
-    public JdbcUserRepository(AgroalDataSource ds) { this.ds = ds; }
+    @Inject
+    DataSource dataSource;      // injected for symmetry/health checks; connections come from the Handler
 }
 ```
 
-Every statement uses **try-with-resources on Connection, PreparedStatement AND ResultSet** — this is what returns connections to the pool. A missed close under load exhausts the pool and takes the native pod down:
+**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 FIND_BY_ID = """
-    SELECT id, email, status, created_at
-    FROM app_user
-    WHERE id = ?
+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 = ?
     """;
 
-@Override
-public Optional<User> findById(UserId id) {
-    try (var con = ds.getConnection();
-         var ps  = con.prepareStatement(FIND_BY_ID)) {
-        ps.setObject(1, id.value());
-        try (var rs = ps.executeQuery()) {
-            return rs.next() ? Optional.of(mapRow(rs)) : Optional.empty();
+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;
         }
-    } catch (SQLException e) {
-        throw translate("user.find_by_id", e);
     }
 }
 ```
 
 Absolute rules:
-- SQL as `private static final String` text blocks. Never concatenate user input — `PreparedStatement` placeholders ALWAYS (SQL injection + plan cache).
+- 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.
-- One private `mapRow(ResultSet) -> Entity` per repository (or a `RowMapper<T>` functional interface shared via a tiny helper — see §6). No reflection mappers: they break native and hide cost.
+- 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 |
 |---|---|---|
-| Outbound port | `<Entity>Repository`, in `application/port/out` | `UserRepository` |
-| JDBC adapter | `Jdbc<Port>`, in `infrastructure/persistence` | `JdbcUserRepository` |
-| Shared row mapper | `<Entity>RowMapper` (private `mapRow` when not shared) | `UserRowMapper` |
-| SQL constant | `UPPER_SNAKE_CASE` verb-first `private static final String` | `FIND_BY_ID`, `INSERT_USER` |
-| Table / column | `snake_case`, singular table name | `app_user`, `created_at` |
+| 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 a repository `*Dao`, `*Manager` or `*Service` — `*Service` is reserved for use-case implementations, and a repository that grows business logic is a use case in disguise.
+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: on the use case, not the repository
+## 3. Transactions and connections: one of each, on `Handler.process()`
 
-The unit of work is the business operation. Annotate the **application-layer use case**:
+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 RegisterUserService implements RegisterUserUseCase {   // impl = *Service, port = *UseCase
-
-    @Transactional
-    public UserId register(RegisterUserCommand cmd) {
-        var user = User.register(cmd);       // domain
-        userRepository.save(user);           // same tx
-        eventPublisher.publish(new UserRegistered(user.id())); // same tx (outbox insert)
-        return user.id();
+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
+        }
     }
 }
 ```
 
-With `@Transactional` active, Agroal enlists the connection in the JTA transaction automatically — repositories keep using `ds.getConnection()` and all writes inside the use case share one transaction, committed/rolled back together. This is exactly what the outbox pattern requires (see quarkus-kafka-messaging skill).
+**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.
 
-- Runtime exceptions roll back by default; domain exceptions extend `RuntimeException`, so throwing them rolls back — correct by construction.
-- Programmatic control when annotations don't fit (loops with per-item commit, batch jobs):
+- `@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(() -> { ...repos... });
+QuarkusTransaction.requiringNew().timeout(30).run(() -> { ...sql calls... });
 ```
 
-- Never call `con.commit()`/`setAutoCommit()` manually inside JTA-managed code paths.
-- Read-only single queries need no `@Transactional` (auto-commit read is fine); multi-read consistency or any write → transaction.
+- 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 = """
-    INSERT INTO app_user (id, email, status, created_at)
-    VALUES (?, ?, ?, ?)
-    ON CONFLICT (email) DO NOTHING
+private static final String INSERT_PARTY = """
+    INSERT INTO customer.party (tenant_id, party_type, status, created_by, updated_by)
+         VALUES (?, ?, ?, ?, ?)
+      RETURNING id
     """;
 
-@Override
-public void save(User u) {
-    try (var con = ds.getConnection(); var ps = con.prepareStatement(INSERT)) {
-        ps.setObject(1, u.id().value());
-        ps.setString(2, u.email().value());
-        ps.setString(3, u.status().name());
-        ps.setObject(4, u.createdAt());
-        if (ps.executeUpdate() == 0) throw new DuplicateEmailException(u.email());
-    } catch (SQLException e) {
-        throw translate("user.save", e);
+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);
+        }
     }
 }
 ```
 
-- Check `executeUpdate()` counts — 0 rows on an expected UPDATE is a bug or a concurrency signal, not a success.
-- Prefer DB-generated values via `RETURNING` (Postgres) over `getGeneratedKeys()` when you need them: `INSERT ... RETURNING id` + `executeQuery()`.
-- Optimistic locking: `version` column, `UPDATE ... WHERE id = ? AND version = ?`; 0 rows → `StaleVersionException` (domain) → 409 via the unified handler. 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.
+- **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
-try (var con = ds.getConnection(); var ps = con.prepareStatement(INSERT)) {
-    for (var item : items) {
-        bind(ps, item);
-        ps.addBatch();
+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)
     }
-    ps.executeBatch();          // add ?reWriteBatchedInserts=true to the JDBC URL (Postgres)
 }
 ```
 
-Chunk batches (500–1000) inside long jobs; combine with `QuarkusTransaction` per chunk.
+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:
 
@@ -192,15 +210,17 @@ Read side: `rs.getString("context")` then parse. Index jsonb lookups you actuall
 To kill boilerplate, ONE small internal helper class (~50 lines) per service or shared lib is the sanctioned maximum:
 
 ```java
-public final class Jdbc {
+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(DataSource ds, String sql, RowMapper<T> m, Object... params) { ... }
-    public static <T> List<T> queryList(DataSource ds, String sql, RowMapper<T> m, Object... params) { ... }
-    public static int update(DataSource ds, String sql, Object... params) { ... }
+    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.
@@ -216,30 +236,40 @@ JDBC blocks. Never run it on the event loop:
 
 ## 8. SQLException translation
 
-One translator in `infrastructure/persistence`, mapping SQLState to domain/persistence exceptions so callers never see `SQLException`:
+`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 | Throw |
+| SQLState | Meaning | Resulting exception (all unchecked) |
 |---|---|---|
-| `23505` | unique violation | domain conflict exception (→ 409) |
-| `23503` | FK violation | domain integrity exception |
+| `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
 
-- Repository tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies).
+- `<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 repository method
+## Checklist for a new `Sql` method
 
-0. Names follow the canonical table above (`Jdbc<Port>` adapter, `<Entity>Repository` port, `UPPER_SNAKE` SQL constants).
-1. SQL text block constant, placeholders only; whitelist for any dynamic fragment.
-2. try-with-resources on connection/statement/resultset (or the `Jdbc` helper).
-3. Transaction boundary on the use case, not here.
-4. `executeUpdate()` count checked; SQLState translated, never leaked.
-5. jsonb via `PGobject`; batch + chunking for bulk; keyset pagination if deep.
-6. `@Blocking`/virtual thread if called from a reactive context; Dev Services test written.
+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.