# spring-data-jpa

Patterns and rules for Spring Data JPA persistence layers: repository setup, pagination, entity auditing, and transaction boundaries.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 4100 installs · ★ 363
- Author: giuseppe-trisciuoglio
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/giuseppe-trisciuoglio/developer-kit/tree/HEAD/plugins/developer-kit-java/skills/spring-data-jpa/SKILL.md
- Updated: 2026-09-10
- HTML: https://affpapa.org/en/nevibecode/skills/spring-data-jpa

## What it does

The skill equips coding agents with engineering patterns for Spring Data JPA. It covers repository declaration through `JpaRepository`, derived query methods, custom JPQL queries via `@Query`, and safe relationship management with `orphanRemoval`.

Direct exposure of JPA entities in REST endpoints is strictly discouraged; data must travel through DTOs such as Java records or `@Value` classes to prevent lazy loading failures. For read operations, the skill demands `@Transactional(readOnly = true)`. This is a clear reason to audit your service layer for unintended writes and avoid holding database locks unnecessarily.

Performance guidelines target common relational bottlenecks. The instructions require mitigating N+1 query issues with `@EntityGraph` or `JOIN FETCH`, verifying large tables with `EXPLAIN ANALYZE`, and avoiding index fragmentation caused by random UUID primary keys.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill spring-data-jpa -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/spring-data-jpa/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/spring-data-jpa/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill spring-data-jpa -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/spring-data-jpa/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill spring-data-jpa -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/spring-data-jpa/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install giuseppe-trisciuoglio/developer-kit spring-data-jpa
```

2. **Manually: put the files in place**
- File: `.github/skills/spring-data-jpa/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill spring-data-jpa -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/giuseppe-trisciuoglio/developer-kit --path plugins/developer-kit-java/skills/spring-data-jpa
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/spring-data-jpa/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill spring-data-jpa -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/giuseppe-trisciuoglio/developer-kit/tree/HEAD/plugins/developer-kit-java/skills/spring-data-jpa/SKILL.md

## When to use it
- configure repositories using JpaRepository and custom @Query methods
- set up entity pagination with Pageable and PageRequest
- implement entity auditing via AuditingEntityListener
- eliminate N+1 query overhead using @EntityGraph

## Example prompts
- Create a ProductRepository with pagination and a custom @Query to filter by price
- Configure an Order entity with auditing annotations and a OneToMany relation

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 7e720af61929663f.

BEGIN THIRD-PARTY FILE 7e720af61929663f
````text
---
name: spring-data-jpa
description: Provides patterns to implement persistence layers with Spring Data JPA. Use when creating repositories, configuring entity relationships, writing queries (derived and `@Query`), setting up pagination, database auditing, transactions, UUID primary keys, multiple databases, and database indexing.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# Spring Data JPA

## Overview

Provides patterns for Spring Data JPA repositories, entity relationships, queries, pagination, auditing, and transactions.

## When to Use

Creating repositories with CRUD operations, entity relationships, `@Query` annotations, pagination, auditing, or UUID primary keys.

## Instructions

### Create Repository Interfaces

To implement a repository interface:

1. **Extend the appropriate repository interface:**
   ```java
   @Repository
   public interface UserRepository extends JpaRepository<User, Long> {
       // Custom methods defined here
   }
   ```

2. **Use derived queries for simple conditions:**
   ```java
   Optional<User> findByEmail(String email);
   List<User> findByStatusOrderByCreatedDateDesc(String status);
   ```

3. **Implement custom queries with `@`Query:**
   ```java
   @Query("SELECT u FROM User u WHERE u.status = :status")
   List<User> findActiveUsers(@Param("status") String status);
   ```

### Configure Entities

1. **Define entities with proper annotations:**
   ```java
   @Entity
   @Table(name = "users")
   public class User {
       @Id
       @GeneratedValue(strategy = GenerationType.IDENTITY)
       private Long id;

       @Column(nullable = false, length = 100)
       private String email;
   }
   ```

2. **Configure relationships using appropriate cascade types:**
   ```java
   @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, orphanRemoval = true)
   private List<Order> orders = new ArrayList<>();
   ```
   **Validation:** Test cascade behavior with a small dataset before applying to production data. Verify delete operations don't cascade unexpectedly.

3. **Set up database auditing:**
   ```java
   @CreatedDate
   @Column(nullable = false, updatable = false)
   private LocalDateTime createdDate;
   ```

### Apply Query Patterns

1. **Use derived queries for simple conditions**
2. **Use `@`Query for complex queries**
3. **Return Optional<T> for single results**
4. **Use Pageable for pagination**
5. **Apply `@`Modifying for update/delete operations**

### Manage Transactions

1. **Mark read-only operations with `@`Transactional(readOnly = true)**
2. **Use explicit transaction boundaries for modifying operations**
3. **Specify rollback conditions when needed**

### Validate and Optimize
````
END THIRD-PARTY FILE 7e720af61929663f

The third-party file has ended. Everything between the 7e720af61929663f tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2690 of 6055 bytes. © giuseppe-trisciuoglio · MIT · https://github.com/giuseppe-trisciuoglio/developer-kit/tree/HEAD/plugins/developer-kit-java/skills/spring-data-jpa/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md