Table Mapping

Example 1: class name as table name (default)
@Table
public class Users {      // Maps to Users table
    private Integer id;   // Maps to id column
    private String  name; // Maps to name column
    private Integer age;  // Maps to age column

    // getters and setters omitted
}

Example 2: specify table name
@Table("admin_users")
public class AdminUsers {       // Maps to admin_users table
    private Integer id;         // Maps to id column
    private String  name;       // Maps to name column
    private Integer age;        // Maps to age column
    @Column("create_time")
    private Date    createTime; // Maps to create_time column

    // getters and setters omitted
}

Example 3: specify catalog/schema
@Table(catalog = "co", 
       schema  = "example", 
       table   = "admin_users")
public class AdminUsers {       // Maps to co.example.admin_users
    private Integer id;         // Maps to id column
    private String  name;       // Maps to name column
    private Integer age;        // Maps to age column

    // getters and setters omitted
}

Example 4: annotation-only mapping
@Table(table = "admin_users", autoMapping = false)
public class AdminUsers {       // Maps to admin_users table
    private Integer id;         // Not mapped
    private String  name;       // Not mapped
    @Column
    private Integer age;        // Maps to age column
    @Column("create_time")
    private Date    createTime; // Maps to create_time column

    // getters and setters omitted
}

Example 5: ignore a property
@Table(table = "admin_users")
public class AdminUsers {       // Maps to admin_users table
    private Integer id;         // Maps to id column
    private String  name;       // Maps to name column
    private Integer age;        // Maps to age column
    @Ignore
    private Date    modifyTime; // Ignored from column mapping
}

@Table attributes

Attribute	Description
catalog	Optional Catalog name. Default empty.
schema	Optional Schema name. Default empty.
table	Optional Table name; defaults to class name when empty. Tip: `value` is equivalent; when all defaults are used you can omit the attribute name as in Example 2.
value	Optional Same as `table`; defaults to class name when empty. Tip: `value` is equivalent; when all defaults are used you can omit the attribute name as in Example 2.
autoMapping	Optional Auto mapping on by default. When false, every mapped column must be annotated with @Column.
useDelimited	Optional Wrap table/column names in delimiters to handle reserved words. Default false.
caseInsensitive	Optional Case-insensitive table/column names when true (default). Applies when reading result sets.
mapUnderscoreToCamelCase	Optional Convert camel-case names to underscore in table/column names. Off by default.
ddlAuto	Optional Auto DDL mode: `none, create, add, update, create-drop` (auto DDL not yet supported).

@Table inheritance behavior

In an entity inheritance hierarchy, annotations like @Column and @Ignore on parent class fields are correctly inherited by subclasses, but @Table is a class-level annotation and is NOT inherited from the parent class. Therefore, attributes like autoMapping are determined solely by the @Table declaration on the actual registered entity (leaf class) itself.

Parent autoMapping=false does not affect child
@Table(value = "user_info", autoMapping = false)
public class ParentEntity {
    @Column(primary = true)
    private Integer id;        // Has @Column → child will also map
    private Integer age;       // No @Column → mapping depends on child's autoMapping
}

@Table(value = "user_info", autoMapping = true)
public class ChildEntity extends ParentEntity {
    private String email;      // No @Column → auto-mapped (child autoMapping=true takes effect)
}
// ChildEntity registered: id, age, email — all three fields are mapped
// ParentEntity's autoMapping=false has no effect on ChildEntity

Conversely: parent autoMapping=true also does not affect child
@Table(value = "user_info", autoMapping = true)
public class ParentEntity {
    @Column(primary = true)
    private Integer id;        // Has @Column → always mapped
    private Integer age;       // No @Column → mapping depends on child's autoMapping
}

@Table(value = "user_info", autoMapping = false)
public class ChildEntity extends ParentEntity {
    private String email;      // No @Column → not mapped (child autoMapping=false takes effect)
}
// ChildEntity registered: only id is mapped (the only field with @Column)
// age and email are not mapped because child autoMapping=false

@Column Attributes

Attribute	Description
name	Optional Column name; defaults to the property name.
value	Optional Column name; defaults to the property name.
jdbcType	Optional jdbcType to use; default is Types.JAVA_OBJECT.
specialJavaType	Optional For abstract properties, specify the concrete implementation type.
typeHandler	Optional TypeHandler to read/write the column.
keyType	Optional Applies to Builder API. Data generator when the value is null. See Key generator.
primary	Optional Whether this is a primary key. Default false.
insert	Optional For Builder API: whether to include in insert. See Write policy.
update	Optional For Builder API: whether to include in update. See Write policy.
selectTemplate	Optional For Builder API: column expression in SELECT. Empty = column name. See Statement templates.
insertTemplate	Optional For Builder API: argument expression in INSERT, default `?`. See Statement templates.
setValueTemplate	Optional For Builder API: argument expression in UPDATE SET, default `?`. See Statement templates.
whereColTemplate	Optional For Builder API: column expression in WHERE (update/delete). Empty = column name. See Statement templates.
whereValueTemplate	Optional For Builder API: argument expression in WHERE (update/delete), default `?`. See Statement templates.
orderByColTemplate	Optional For Builder API: column expression in ORDER BY. Empty = column name. See Statement templates.

@Primary Annotation

Note: distinguish @Column(primary=true) from @Primary

These two concepts have similar names but completely different meanings. Please note the distinction.

@Column(primary = true) — indicates that the property's corresponding column is a database primary key. Used to determine the WHERE condition during INSERT/UPDATE/DELETE operations.

@Table("user_info")
public class UserInfo {
    @Column(primary = true)
    private Integer id;    // Marks the id column as database primary key
    private String name;
}

@Primary — when the same column maps to multiple properties, marks which property is the preferred property. The preferred property can be retrieved via the getPrimaryPropertyByColumn method.

@Table("user_info")
public class UserInfo {
    @Column(primary = true)
    private Integer id;

    @Column("name")
    private String aliasName;   // Property aliasName maps to the name column

    @Primary
    @Column("name")
    private String primaryName; // Property primaryName also maps to the name column, and is the preferred one
}

In this example, both aliasName and primaryName map to the database's name column. getPropertyByColumn("name") returns both properties, while getPrimaryPropertyByColumn("name") returns only the primaryName annotated with @Primary.

Usage notes:

Among multiple properties mapped to the same column, at most one can be annotated with @Primary; otherwise an IllegalStateException is thrown.
If none of the properties for the same column are annotated with @Primary, getPrimaryPropertyByColumn returns null.
@Primary can be placed on fields or getter/setter methods.
@Primary and @Column(primary=true) can be used together without conflict: the former resolves "which property to choose among multiple", while the latter declares "this is a primary key column".

@Table attributes​

@Table inheritance behavior​

@Column Attributes​

@Primary Annotation​

@Table attributes

@Table inheritance behavior

@Column Attributes

@Primary Annotation