jdbc-persistence

Add JDBC persistence using $ARGUMENTS. Apply all rules below strictly; /bce, /java-conventions, and the stack skill hold wherever this skill is silent.

Principle

Data-Oriented Programming applied to the relational store: the record is the row shape, the sealed interface is the closed set of variants, and the control is a set of functions that move data between the two representations. Nothing is hidden — no proxies, no lazy loading, no dirty checking, no generated SQL. What the code reads is what the database executes.

• model the data, the whole data, nothing but the data — one record per row shape, one record per projection; no record carries columns a query does not return
• data is immutable and transparent — a change is a new record (with-style copy through the canonical constructor), then an UPDATE
• make illegal states unrepresentable — closed sets as sealed interfaces or enums; the compiler, not a default branch, proves the column mapping complete
• separate operations from data — SQL and binding live in the control; records carry components, invariants, domain behavior, and their own creation from a row (fromResultSet), the read-side twin of toJSON(); java.sql enters a record only through that factory

Placement (BCE)

• entity — the records and sealed interfaces; free of annotations and SQL strings; the only java.sql types a record sees are the ResultSet and SQLException of its fromResultSet factory
• control — classes named after their responsibilities (Customers, OrderReports), never *Repository, *Dao, *Mapper, *Store; a control holds the SQL, binding, and row collection for the queries it answers and may read or write several tables of its BC in one method; one table is written by exactly one control
• boundary — owns the unit of work: one connection, one transaction, several control calls; never contains SQL
  • /microprofile-server: @Transactional on the boundary class, never on single methods, and @Inject of the control; the boundary never sees a DataSource or Connection — the container opens the transaction, the control's connections enlist in it, the container commits. When the project defines a @Boundary stereotype (a CDI @Stereotype carrying @ApplicationScoped and @Transactional), use it instead of an explicit @Transactional, likewise on the class; introduce the stereotype only when the project already has one or asks for it
  • /java-cli-app: the boundary opens the connection (DriverManager.getConnection(url, user, password) or a driver DataSource), sets setAutoCommit(false), passes the connection to the controls, commits; a thrown exception rolls back in a catch and rethrows. A read-only query may run with auto-commit; a boundary method that writes never does
• connection coordinates come from configuration, never from literals: quarkus.datasource.* / MicroProfile Config on the server, /zcfg keys (db.url, db.user, db.password) in a CLI; the password never lands in a source file
• the schema belongs to the BC: each BC ships its own DDL; a table is owned by exactly one BC
• a reference to another BC is an id component in the referencing record, backed by a real FOREIGN KEY (see Schema); never a nested record of the other BC's entity; a join across BC boundaries is confined to read-only projections and is a coupling signal