Columns & AttributeConverters

## What @Column is and is not `@Column` describes the single database column behind a basic attribute. It is never required: an entity with no `@Column` anywhere still maps every non-transient attribute. What the annotation buys you is control over the column's name, its generated type and its participation in write statements. It is worth internalising the split between **what is used at runtime** and **what is used only when the provider generates DDL**, because most confusion about `@Column` comes from assuming the second group does something at runtime. ## The attributes **`name`** — the column name. Used in every `SELECT`, `INSERT`, `UPDATE` and `DELETE`. If omitted, the provider derives it from the attribute name via the naming strategy in force. Naming it explicitly protects the schema from a Java rename. **`length`** — the string length, default 255. DDL only: it becomes `varchar(255)` or similar. Nothing truncates or rejects a longer value in Java; an over-length string is sent to the database, which raises an error. **`precision` and `scale`** — for `BigDecimal` and `BigInteger`. `precision` is total significant digits; `scale` is digits after the decimal point. DDL only, but consequential: leaving them at the defaults for a money column often generates something that silently rounds or that stores far more digits than intended. For money, state them explicitly — for example `precision = 19, scale = 4`. **`nullable`** — default `true`. DDL only. `nullable = false` emits `NOT NULL`; it does not make the provider check for null before insert. If you want an application-level check that fails fast with a good message, that is Bean Validation's job; if you want a guarantee, that is the database constraint's job. **`unique`** — DDL only, a shorthand for a single-column unique constraint. Multi-column uniqueness belongs in the `@Table` annotation's `uniqueConstraints` (also DDL only). As with `nullable`, the provider never enforces it in memory. **`columnDefinition`** — a raw SQL fragment used verbatim as the column's type in generated DDL, e.g. `columnDefinition = "jsonb"` or `"text"`. It overrides the provider's type derivation, which makes it the escape hatch for vendor types — and simultaneously ties the entity to one database, since the fragment is not portable. It also affects only DDL; it does not change how the value is bound through JDBC. **`table`** — names a secondary table when the entity spans more than one, declared with `@SecondaryTable`. **`insertable` / `updatable`** — the two genuinely runtime attributes. They remove the column from generated `INSERT` and `UPDATE` statements respectively, while the column is still read on `SELECT`. ## When schema generation is off Most production systems own their schema with a migration tool and run with DDL generation disabled. In that world, everything in the DDL-only group is documentation: accurate or not, it changes nothing. Two consequences follow. First, don't reason about runtime behaviour from `nullable` or `length`. Second, if you keep those attributes as a mirror of the migration, enable **schema validation on startup** so drift is caught at boot rather than by a mystery error months later — validation compares the mapping against the real table and refuses to start on a mismatch. ## Common mistakes - Assuming `length = 50` truncates. It does not; the database rejects the row. - Assuming `nullable = false` throws a friendly Java exception. It produces a constraint violation from the database at flush time, potentially at commit, far from the code that set the null. - Leaving `precision`/`scale` unset on monetary amounts and discovering rounding in production. - Reaching for `columnDefinition` to fix a type problem and quietly making the mapping non-portable and invisible to the naming and type systems. - Putting `@Column` on the getter of a field-access entity, where it is silently ignored — annotation placement must match the entity's access type. - Believing `unique = true` prevents duplicates in an application whose schema was created by migrations that never included the constraint. ## A minimal habit Name the column explicitly, set `nullable` and `length`/`precision` to describe reality accurately even when generation is off, and let migrations create the schema. That gives you readable mappings, a validation check that catches drift, and no illusion that the annotation is enforcing anything.