Skip to main content
Agent skill

Jpa Patterns

JPA/Hibernate patterns for entity design, relationships, query optimization, transactions, auditing, indexing, pagination, and pooling in Spring Boot. Use when designing JPA entities or relationships, or when a Hibernate query, transaction, or N+1 problem needs fixing.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Jpa Patterns when an AI agent needs a reusable SKILL.md workflow for this job: JPA/Hibernate patterns for entity design, relationships, query optimization, transactions, auditing, indexing, pagination, and pooling in Spring Boot. Use when designing JPA entities or relationships, or when a Hibernate query, transaction, or N+1 problem needs fixing.

When not to use it

Skip Jpa Patterns when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/jpa-patterns
# Save SKILL.md to ~/.claude/skills/jpa-patterns/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/jpa-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/jpa-patterns/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Jpa Patterns skill for this task: Use Jpa Patterns when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
70/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# JPA/Hibernate Patterns

Use for data modeling, repositories, and performance tuning in Spring Boot.

## When to Activate

- Designing JPA entities and table mappings - Defining relationships (@OneToMany, @ManyToOne, @ManyToMany) - Optimizing queries (N+1 prevention, fetch strategies, projections) - Configuring transactions, auditing, or soft deletes - Setting up pagination, sorting, or custom repository methods - Tuning connection pooling (HikariCP) or second-level caching

## Entity Design

```java @Entity @Table(name = "markets", indexes = { @Index(name = "idx_markets_slug", columnList = "slug", unique = true) }) @EntityListeners(AuditingEntityListener.class) public class MarketEntity { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id;

@Column(nullable = false, length = 200) private String name;

@Column(nullable = false, unique = true, length = 120) private String slug;

@Enumerated(EnumType.STRING) private MarketStatus status = MarketStatus.ACTIVE;

@CreatedDate private Instant createdAt; @LastModifiedDate private Instant updatedAt; } ```

Enable auditing: ```java @Configuration @EnableJpaAuditing class JpaConfig {} ```

## Relationships and N+1 Prevention

```java @OneToMany(mappedBy = "market", cascade = CascadeType.ALL, orphanRemoval = true) private List<PositionEntity> positions = new ArrayList<>(); ```

- Default to lazy loading; use `JOIN FETCH` in queries when needed - Avoid `EAGER` on collections; use DTO projections for read paths

```java @Query("select m from MarketEntity m left join fetch m.positions where m.id = :id") Optional<MarketEntity> findWithPositions(@Param("id") Long id); ```

## Repository Patterns

```java public interface MarketRepository extends JpaRepository<MarketEntity, Long> { Optional<MarketEntity> findBySlug(String slug);

@Query("select m from MarketEntity m where m.status = :status") Page<MarketEntity> findByStatus(@Param("status") MarketStatus status, Pageable pageable); } ```

- Use projections for lightweight queries: ```java public interface MarketSummary { Long getId(); String getName(); MarketStatus getStatus(); } Page<MarketSummary> findAllBy(Pageable pageable); ```

## Transactions

- Annotate service methods with `@Transactional` - Use `@Transactional(readOnly = true)` for read paths to optimize - Choose propagation carefully; avoid long-running transactions

```java @Transactional public Market updateStatus(Long id, MarketStatus status) { MarketEntity entity = repo.findById(id) .orElseThrow(() -> new EntityNotFoundException("Market")); entity.setStatus(status); return Market.from(entity); } ```

## Pagination

```java PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending()); Page<MarketEntity> markets = repo.findByStatus(MarketStatus.ACTIVE, page); ```

For cursor-like pagination, include `id > :lastId` in JPQL with ordering.

## Indexing and Performance

- Add indexes for common filters (`status`, `slug`, foreign keys) - Use composite indexes matching query patterns (`status, created_at`) - Avoid `select *`; project only needed columns - Batch writes with `saveAll` and `hibernate.jdbc.batch_size`

## Connection Pooling (HikariCP)

Recommended properties: ``` spring.datasource.hikari.maximum-pool-size=20 spring.datasource.hikari.minimum-idle=5 spring.datasource.hikari.connection-timeout=30000 spring.datasource.hikari.validation-timeout=5000 ```

For PostgreSQL LOB handling, add: ``` spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true ```

## Caching

- 1st-level cache is per EntityManager; avoid keeping entities across transactions - For read-heavy entities, consider second-level cache cautiously; validate eviction strategy

## Migrations

- Use Flyway or Liquibase; never rely on Hibernate auto DDL in production - Keep migrations idempotent and additive; avoid dropping columns without plan

## Testing Data Access

- Prefer `@DataJpaTest` with Testcontainers to mirror production - Assert SQL efficiency using logs: set `logging.level.org.hibernate.SQL=DEBUG` and `logging.level.org.hibernate.orm.jdbc.bind=TRACE` for parameter values

**Remember**: Keep entities lean, queries intentional, and transactions short. Prevent N+1 with fetch strategies and projections, and index for your read/write paths.

Intended uses

  • Use Jpa Patterns when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.