# kotlin-backend-jpa-entity-mapping

Teaches your agent to map JPA entities in Kotlin for Spring Data JPA and Hibernate: identity, equals/hashCode, relations, fetch plans.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1600 installs · ★ 1093
- Author: JetBrains
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Kotlin/kotlin-agent-skills/tree/HEAD/skills/kotlin-backend-jpa-entity-mapping/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/kotlin-backend-jpa-entity-mapping

## What it does

A JetBrains skill about the traps you hit when mapping entities in Kotlin. The big one is `data class`: Hibernate depends on identity semantics, and generated `equals`/`hashCode` over every field corrupt `Set` and `Map` membership once state changes. The generated `copy()` also produces detached duplicates of managed entities. The skill wants a plain `class` for entities and keeps `data class` for DTOs.

Inside are entity design rules, identity strategies and uniqueness constraints. For database-generated IDs it suggests `var id: Long? = null` with a `protected set` rather than a `0L` sentinel. `equals` compares by ID only, `hashCode` returns a class-based constant, `toString` stays away from lazy collections. On uniqueness it asks for two layers: a database constraint for correctness and an application check for readable errors — a code check alone leaves a race.

There is a section on N+1 and `LazyInitializationException`: diagnose from actual query counts or SQL logs, not from annotations. Fixes include `@EntityGraph`, `JOIN FETCH`, batch fetching and DTO projections. Then the ORM traps: `orphanRemoval` and cascade remove are not interchangeable, bulk updates bypass the persistence context, and several collection fetch joins can blow up into a Cartesian product. If your project already has an identity convention, the skill says to follow it instead of imposing another.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-backend-jpa-entity-mapping -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-backend-jpa-entity-mapping -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-backend-jpa-entity-mapping -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Kotlin/kotlin-agent-skills kotlin-backend-jpa-entity-mapping
```

2. **Manually: put the files in place**
- File: `.github/skills/kotlin-backend-jpa-entity-mapping/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-backend-jpa-entity-mapping -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Kotlin/kotlin-agent-skills --path skills/kotlin-backend-jpa-entity-mapping
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-backend-jpa-entity-mapping -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/Kotlin/kotlin-agent-skills/tree/HEAD/skills/kotlin-backend-jpa-entity-mapping/SKILL.md

## When to use it
- convert a JPA entity from `data class` to a regular class
- fix `equals`/`hashCode` so a `Set` keeps its elements after persist
- track down an N+1 by reading SQL logs
- add a uniqueness constraint plus a clean duplicate error
- keep lazy relations out of `toString` to avoid `LazyInitializationException`

## Example prompts
- review my `Order` entity and tell me what breaks under Hibernate
- why do I get N+1 when loading orders with their line items? rewrite the query
- add a unique constraint on `variant_id` and `order_id` in `Reservation` and a service-level check

## Source text · SKILL.md · Apache-2.0

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: 59315f9cc4f564d1.

BEGIN THIRD-PARTY FILE 59315f9cc4f564d1
```text
---
name: kotlin-backend-jpa-entity-mapping
description: >
  Model Kotlin persistence code correctly for Spring Data JPA and Hibernate.
  Covers entity design, identity and equality, uniqueness constraints,
  relationships, fetch plans, and common ORM (Object-Relational Mapping) traps 
  specific to Kotlin. Use when creating or reviewing JPA (Java Persistence API) 
  entities, diagnosing N+1 or LazyInitializationException, placing indexes and 
  uniqueness rules, or preventing Kotlin-specific bugs such as data class 
  entities and broken equals/hashCode.
license: Apache-2.0
metadata:
  author: JetBrains
  version: "1.0.0"
---

# JPA Entity Mapping for Kotlin

Kotlin's `data class` is natural for DTOs but dangerous for JPA entities. Hibernate relies on
identity semantics that `data class` breaks: `equals`/`hashCode` over all fields corrupts
`Set`/`Map` membership after state changes, and auto-generated `copy()` creates detached
duplicates of managed entities.

This skill teaches correct entity design, identity strategies, and uniqueness constraints
for Kotlin + Spring Data JPA projects.

## Entity Design Rules

- **Never use `data class` for JPA entities.** Use a regular `class`. Keep `data class` for DTOs.
- Keep transport DTOs and persistence entities separate unless the project clearly uses a shared model.
- Model required columns as non-null only when object construction and persistence lifecycle make it safe.
- Use `lateinit` only when the project already accepts that tradeoff and the lifecycle is safe.
- Verify `kotlin("plugin.jpa")` or equivalent no-arg support when JPA entities exist.
- Verify classes and members are compatible with proxying where needed.

## Identity and Equality

- Never accept all-field `equals`/`hashCode` generated by `data class` on an entity.
- Follow project conventions when they already define an identity strategy.
```
END THIRD-PARTY FILE 59315f9cc4f564d1

The third-party file has ended. Everything between the 59315f9cc4f564d1 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 1879 of 7439 bytes. © JetBrains · Apache-2.0 · https://github.com/Kotlin/kotlin-agent-skills/tree/HEAD/skills/kotlin-backend-jpa-entity-mapping/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