home / skills / hoangnguyen0403 / agent-skills-standard / data-access

data-access skill

safe

This skill helps you implement Spring Boot data access best practices for JPA and Hibernate, improving performance and reliability.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill data-access

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.2 KB

---
name: Spring Boot Data Access
description: Best practices for JPA, Hibernate, and Database interactions in Spring Boot
metadata:
  labels: [spring-boot, jpa, hibernate, database]
  triggers:
    files: ['**/*Repository.java', '**/*Entity.java']
    keywords: [jpa-repository, entity-graph, transactional, n-plus-1]
---

# Spring Boot Data Access

## **Priority: P0**

## Implementation Guidelines

### JPA & Hibernate

- **Read-Only**: Default to `@Transactional(readOnly = true)` on Services. Override only on write methods.
- **Projections**: Use Java Records for read-only queries. Avoid fetching full Entities.
- **Pagination**: ALWAYS use `Pageable` for collections.
- **Open-In-View**: Set `spring.jpa.open-in-view=false` to detect lazy loading issues early.

### Query Optimization

- **N+1 Problem**: Use `JOIN FETCH` (JPQL) or `@EntityGraph` for relationships.
- **Bulk Operations**: Use `@Modifying` for batch updates/deletes to bypass Entity overhead.

## Anti-Patterns

- **N+1 Selects**: `**No loops in loops**: Fetch eagerly or use graphs.`
- **Logic in Queries**: `**No complex JPQL**: Use Service logic.`
- **Returning Streams**: `**No raw Streams**: Use Lists or Page.`

## References

- [Implementation Examples](references/implementation.md)

Overview

This skill captures best practices for JPA, Hibernate, and database interactions in Spring Boot. It focuses on safe defaults, query optimization, and avoiding common performance anti-patterns. The goal is to help agents generate code that is maintainable, performant, and predictable in production.

How this skill works

The skill inspects service and repository patterns and recommends transactional defaults, projection strategies, and pagination usage. It highlights query-level fixes for N+1 select issues and suggests bulk operation techniques that avoid entity-management overhead. It also enforces configuration recommendations to reveal lazy-loading problems early.

When to use it

When designing new Spring Boot services that access a relational database
When reviewing or refactoring JPA/Hibernate repository and service code
When diagnosing performance issues like N+1 selects or slow collection loads
When implementing bulk updates/deletes or pagination for large datasets
When setting application defaults to surface lazy-loading errors early

Best practices

Default services to @Transactional(readOnly = true); mark only write methods as read-write
Use Java Records or DTO projections for read-only queries instead of fetching full entities
Always use Pageable for collection queries to avoid loading large result sets
Disable spring.jpa.open-in-view to detect lazy-loading issues during development
Solve N+1 problems with JOIN FETCH or @EntityGraph instead of per-entity loops
Use @Modifying queries for bulk updates/deletes to bypass entity lifecycle overhead

Example use cases

Implementing a read-heavy API endpoint that returns paginated DTOs using a repository projection
Refactoring a service suffering from N+1 queries by adding an @EntityGraph to the repository method
Applying a bulk status update across millions of rows using a @Modifying JPQL update
Auditing a codebase to replace raw Streams returned from repositories with Lists or Page objects
Configuring application properties to disable open-in-view and fixing surfaced lazy-load errors

FAQ

Why set @Transactional(readOnly = true) by default?

Read-only transactions signal intent, can enable optimizations, and reduce accidental writes. Mark specific methods as write transactions when needed.

When should I use JOIN FETCH vs @EntityGraph?

JOIN FETCH is explicit in JPQL and good for single custom queries; @EntityGraph is reusable and declarative for repository methods and avoids query string duplication.