Join Columns vs Join Tables

## What a join column is Relational databases express relationships with a **foreign key**: a column in one table holding the primary-key value of a row in another. `@JoinColumn` is how JPA tells the provider which column plays that role for a given association attribute. ```java @Entity class Order { @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "customer_id") private Customer customer; } ``` This says: the `orders` table has a `customer_id` column, and it references `Customer`'s primary key. ## Owning side A bidirectional association is one relationship represented by two Java references. The database has only one FK column, so exactly one side must be designated as the one whose state drives the SQL. That is the **owning side**, and it carries `@JoinColumn`. The other side is the **inverse** side and declares `mappedBy`, naming the field on the owner: ```java @Entity class Customer { @OneToMany(mappedBy = "customer") private List<Order> orders = new ArrayList<>(); } ``` `mappedBy` means "this collection is a read view of the FK maintained by `Order.customer`". Adding an `Order` to `customer.orders` without also setting `order.setCustomer(customer)` writes nothing — the row's FK stays null. This is the single most common JPA bug in a first project, and the standard remedy is a helper method on the parent that sets both directions. For `@ManyToOne` the many side is *necessarily* the owner: the FK can only live in the child table, because one parent row cannot hold many child keys in a single column. ## Useful attributes - **`name`** — the column name. Default is `<fieldName>_<referencedPkColumn>`, e.g. `customer_id`. Rely on the default only if you also control naming strategy; explicit is safer. - **`referencedColumnName`** — which column of the *target* table the FK points at. Defaults to the target's primary key. Set it when you must reference a different unique column, for example a natural key like `country_code`. This works but has real costs: it requires a unique constraint on the target column, it can complicate identity and caching, and it forces Hibernate to key the association on something other than the PK. Prefer PK references unless integrating with a legacy schema. - **`nullable`** — used for DDL generation and, importantly, tells Hibernate whether a to-one association is optional. Combined with `@ManyToOne(optional = false)` it also enables a proxy optimisation and inner rather than outer joins. - **`insertable`/`updatable`** — set both `false` when the same column is also mapped as a plain field (a common pattern for exposing `customerId` alongside `customer`). Without it you get a "repeated column in mapping" error. - **`foreignKey = @ForeignKey(...)`** — controls the generated FK constraint name, or disables it with `ConstraintMode.NO_CONSTRAINT`. Only relevant when the provider generates DDL; in a migration-managed schema the migration tool owns constraints. ## Composite keys When the target has a composite primary key you need one column per key part, using `@JoinColumns`: ```java @ManyToOne @JoinColumns({ @JoinColumn(name = "order_id", referencedColumnName = "order_id"), @JoinColumn(name = "line_no", referencedColumnName = "line_no") }) private OrderLine line; ``` With composite keys `referencedColumnName` becomes mandatory, because ordering alone cannot disambiguate the pairs. ## The @OneToMany + @JoinColumn variant Putting `@JoinColumn` on a `@OneToMany` **without** `mappedBy` is legal and means something specific: a unidirectional one-to-many where the FK still lives in the child table, but the *parent* is responsible for maintaining it. Hibernate implements that by inserting the child with a null FK and then issuing a separate `UPDATE` to set it — an extra statement per child, and it requires the FK column to be nullable. It is better than the join-table default the spec would otherwise apply, but a bidirectional mapping with `mappedBy` is cleaner still. ## How to sanity-check a mapping Read the mapping and answer: which table holds the FK? Whichever entity maps to that table must have `@JoinColumn`; the other must have `mappedBy`. If both sides have `@JoinColumn`, you have accidentally mapped two independent associations onto one relationship and updates will fight each other.