@Insert

Marks an interface method to execute an INSERT statement.

info

value supports string arrays. Elements are joined with spaces, convenient for multi-line writing.

Example: insert a user record

@SimpleMapper
public interface UserMapper {
    @Insert({"insert into users (",
             "    id, name, age, create_time",
             ") values (",
             "    #{id}, #{name}, #{age}, #{createTime}",
             ")"})
    int saveUser(UserDTO user);
}

Properties

Property	Description
value	Required The INSERT statement to be executed.
statementType	Optional JDBC execution mode. Default Prepared - Statement → java.sql.Statement - Prepared → java.sql.PreparedStatement - Callable → java.sql.CallableStatement
timeout	Optional Execution timeout in seconds. Default -1
useGeneratedKeys	Optional Whether to use auto-generated keys. If @SelectKeySql is also configured, this is ignored.
keyProperty	Optional When useGeneratedKeys=true, the Bean property name to receive the generated key. Ignored if @SelectKeySql is configured.
keyColumn	Optional When useGeneratedKeys=true, the column name to read from the returned results. Defaults to the first column. Ignored if @SelectKeySql is configured.

Generated Keys

After inserting data, you often need to write the database-generated primary key back into the parameter object. dbVisitor exposes three configuration categories:

• useGeneratedKeys: use JDBC generated keys.
• keyProperty / keyColumn: declare which Bean property to write back to, and which column to read from the returned results.
• selectKey / @SelectKeySql: execute additional SQL before or after INSERT to obtain the primary key.

The most common approach is useGeneratedKeys, which reads the primary key returned by the database or driver via JDBC's Statement#getGeneratedKeys(). Driver support for keyColumn is not fully consistent across databases: some drivers return by business column name, while others only reliably support reading by column index.

When database generated key behavior is unreliable, or when business logic requires generating the primary key before INSERT, use @SelectKeySql. Primary key return mechanisms vary significantly across databases; see Database Features for details.

@SelectKeySql Annotation

Executes additional SQL before or after INSERT to obtain the primary key and write it back to the parameter object. Must be used together with @Insert.

Example: get auto-increment ID via last_insert_id() after INSERT

@Insert({"insert into users (name, age, create_time)",
         "values (#{name}, #{age}, #{createTime})"})
@SelectKeySql(value = "select last_insert_id()", keyProperty = "id", order = Order.After)
int saveUser(UserDTO user);

UserDTO user = ...;
mapper.saveUser(user);
long newId = user.getId(); // Auto-increment ID has been written back

Property	Description
value	Required The SQL query to obtain the primary key.
keyProperty	Required The Bean property name to receive the primary key value.
order	Required Execution timing: Before (before INSERT, suitable for sequences) or After (after INSERT, suitable for auto-increment IDs).
keyColumn	Optional The column name to read from the query result. Defaults to the first column.
statementType	Optional JDBC execution mode. Default Prepared
timeout	Optional Execution timeout in seconds. Default -1
fetchSize	Optional Rows to fetch at a time. Default 256
resultSetType	Optional Result set type: FORWARD_ONLY, SCROLL_INSENSITIVE, SCROLL_SENSITIVE, DEFAULT