quarkus-panache_skill

Overview

This skill detects and refactors common ORM code smells in Quarkus Panache applications that use the Repository pattern. It focuses on issues that degrade performance or correctness such as N+1 queries, data overfetching, missing pagination, unclosed streams, and problematic relationship mappings. The goal is to produce concrete, actionable refactor suggestions you can apply in repository and entity code.

How this skill works

The skill scans repository and entity patterns to identify smells like class-level eager fetching, use of listAll()/streamAll() without pagination, full-entity selects where projections would suffice, and unclosed streams. For each smell it explains the root cause and provides specific Panache-based fixes: add LAZY fetch, use PanacheQuery pagination, JOIN FETCH or @BatchSize for N+1, DTO projections with .project(), try-with-resources for streams, and mapping changes (Set or bidirectional) for collection issues.

When to use it

• Code review of PanacheRepository implementations or service methods that query entities
• Diagnosing slow endpoints or spikes in DB queries (suspected N+1 problems)
• Auditing memory or connection leaks caused by full-table loads or unclosed streams
• Refactoring read-only endpoints to reduce data transfer and improve latency
• Before deploying to production when large tables are queried without pagination

Best practices

• Prefer FetchType.LAZY on @*ToOne relationships and explicitly tune when needed
• Never use listAll()/streamAll() on large tables; use repo.findAll().page(...) or range()
• Use DTO projections (.project(Dto.class)) for read-only queries to avoid overfetching
• Address N+1 with JOIN FETCH, @BatchSize, or explicit repository methods that fetch graphs
• Always close streams with try-with-resources to avoid leaking DB connections
• Make OneToMany associations bidirectional or use Set to avoid delete/insert churn

Example use cases

• Fixing an endpoint that loads thousands of rows with listAll() and OOMs by adding pagination
• Resolving an N+1 bug when serializing related entities by converting to JOIN FETCH in the repository
• Improving API latency by replacing full-entity queries with DTO projections for simple lists
• Stopping connection leaks by wrapping streamAll() consumption in try-with-resources
• Refactoring a unidirectional @OneToMany List to a bidirectional mapping or Set to reduce SQL churn