411-frameworks-quarkus-jdbc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Apply programmatic JDBC patterns in Quarkus with safe SQL and clear transactions.

What is covered in this Skill?

Injected javax.sql.DataSource (Agroal-backed) and try-with-resources for Connection / PreparedStatement
PreparedStatement with bind parameters — never string concatenation
Mapping ResultSet rows to Java records (dedicated mapRow method)
Safe single-row queries with Optional<T>; never assume rs.next() succeeds
SQLException translation to domain exceptions (catch-translate-rethrow)
Streaming large result sets with setFetchSize to avoid OOM
Batch updates with addBatch / executeBatch for bulk inserts
@Transactional service boundaries and propagation types (TxType.REQUIRES_NEW for independent commits)
CDI self-invocation pitfall: always call transactional methods through the injected proxy
Dev Services for databases in dev/test
When to prefer Panache (
```
@412
```
) vs raw JDBC

Scope: Apply recommendations based on the reference rules and good/bad code examples.

在Quarkus中应用程序化JDBC模式，实现安全的SQL操作与清晰的事务管理。

本Skill涵盖哪些内容？

注入javax.sql.DataSource（基于Agroal实现），并结合try-with-resources使用Connection / PreparedStatement
使用带绑定参数的PreparedStatement — 绝对不要使用字符串拼接
将ResultSet行映射为Java record（专用mapRow方法）
结合Optional<T>实现安全的单行查询；永远不要假设rs.next()一定会成功
将SQLException转换为领域异常（捕获-转换-重新抛出）
通过setFetchSize流式处理大型结果集，避免OOM
使用addBatch / executeBatch进行批量更新，实现批量插入
@Transactional服务边界与传播类型（使用TxType.REQUIRES_NEW实现独立提交）
CDI自调用陷阱：始终通过注入的代理调用事务方法
开发/测试环境中的数据库Dev Services
何时优先选择Panache (
```
@412
```
) 而非原生JDBC

范围： 基于参考规则与优劣代码示例应用相关建议。

Compile before JDBC refactors; verify after changes.

MANDATORY: Run
```
./mvnw compile
```
or
```
mvn compile
```
before applying any change
PREREQUISITE: Project must compile before applying JDBC improvements
SAFETY: If compilation fails, stop immediately
BLOCKING CONDITION: Compilation errors must be resolved by the user before proceeding
VERIFY: Run
```
./mvnw clean verify
```
or
```
mvn clean verify
```
after applying improvements
BEFORE APPLYING: Read the reference for detailed rules and examples

在JDBC重构前先编译；修改后进行验证。

For detailed guidance, examples, and constraints, see references/411-frameworks-quarkus-jdbc.md.

如需详细指南、示例与约束条件，请查看references/411-frameworks-quarkus-jdbc.md。