How do you map a many-to-many association in JPA with @JoinTable, and why do experienced teams often replace @ManyToMany with an explicit link entity?

## The relational shape No relational table can hold a many-to-many directly; it requires an **association (link/junction) table** with one FK to each side: ```sql create table post_tag ( post_id bigint not null references posts(id), tag_id bigint not null references tags(id), primary key (post_id, tag_id) ); ``` `@JoinTable` is how JPA describes that table. ## Mapping it ```java @Entity class Post { @ManyToMany @JoinTable(name = "post_tag", joinColumns = @JoinColumn(name = "post_id"), inverseJoinColumns = @JoinColumn(name = "tag_id")) private Set<Tag> tags = new HashSet<>(); } @Entity class Tag { @ManyToMany(mappedBy = "tags") private Set<Post> posts = new HashSet<>(); } ``` The orientation rule: **`joinColumns` describes the FK back to the entity the annotation is written on; `inverseJoinColumns` describes the FK to the other entity.** Swapping them compiles fine and produces a schema where the columns are reversed — usually caught only when data comes back wrong or a FK constraint fires. Omitting `@JoinTable` entirely lets the provider default the table name to `Post_Tag` and columns to `Post_id`/`tags_id`. Defaults are legal but brittle; name them. ## Set versus List — a real performance rule With `List` and no order column, Hibernate treats the collection as a **bag**: it cannot identify individual rows by position, so any modification triggers `delete from post_tag where post_id = ?` followed by re-inserting the whole collection. Adding one tag to a post with 200 tags becomes 1 delete plus 200 inserts, and it churns indexes and generates spurious write traffic. With `Set`, Hibernate can compute a delta and emits a single-row insert or delete. Always use `Set` for `@ManyToMany`. This also means the entity needs sane `equals`/`hashCode` — conventionally based on a business/natural key, not the generated id (which is null before persist) and not the default identity semantics that break after detach/merge. ## Cascade and removal pitfalls `CascadeType.REMOVE` on a `@ManyToMany` is almost always wrong: deleting a post would delete its tags, which other posts still reference. Only `PERSIST` and `MERGE` are usually appropriate. `orphanRemoval` is not even allowed on `@ManyToMany` — the spec restricts it to one-to-one and one-to-many, because "orphan" is meaningless when other owners may still point at the row. Removing a link is done by mutating the collection on the **owning** side; mutating only the inverse side changes nothing in the database, exactly as with a `mappedBy` one-to-many. ## Why teams replace it with a link entity `@ManyToMany` models a pure set membership. Real domains almost always accrete more: - *when* was the tag added, and by whom - an ordering or weight - a status (pending / approved) - a quantity, price, or role (`user_role` with a `granted_at`) A `@JoinTable` has room for exactly two columns of meaning. The moment you need a third, you must promote the link table to an entity: ```java @Entity class PostTag { @EmbeddedId private PostTagId id; @MapsId("postId") @ManyToOne @JoinColumn(name = "post_id") private Post post; @MapsId("tagId") @ManyToOne @JoinColumn(name = "tag_id") private Tag tag; private Instant addedAt; private String addedBy; } ``` The link entity is two `@ManyToOne` associations plus payload; each side becomes a `@OneToMany(mappedBy = ...)` of link entities. `@MapsId` lets the composite key reuse the FK columns rather than duplicating them. The practical argument for starting with the link entity: promoting later is a schema and code migration touching every call site and every query, whereas the link entity costs a little verbosity up front and never blocks you. Many experienced teams therefore treat `@ManyToMany` as suitable only for genuinely attribute-free, low-churn membership — and reach for the link entity by default otherwise. The counter-argument, worth acknowledging: for a truly pure membership set, `@ManyToMany` is less code, reads better, and lets Hibernate manage link rows without an extra entity in the persistence context. ## Querying With `@ManyToMany` you navigate `select p from Post p join p.tags t where t.name = :n`. With a link entity you query the link directly — `select pt.post from PostTag pt where pt.tag.name = :n and pt.addedAt > :since` — which is strictly more expressive, and is another reason the link entity wins once filtering on link attributes appears.