📌 MyBatis Mapper 완전 정복 ③ - 키 생성 전략 완벽 가이드

📅 날짜

2025-04-25

---

📝 1️⃣ 키 생성 전략이란?

데이터베이스에서는 각 레코드를 식별하기 위해 기본 키(Primary Key) 가 필요합니다.

MyBatis에서는 INSERT 시 자동 또는 수동으로 키를 생성하여 객체에 주입할 수 있도록 다양한 전략을 제공합니다.

🔹 대표적인 키 생성 방식

방식	설명
AUTO_INCREMENT	DB가 자동으로 키 값을 생성
Sequence	Oracle 등에서 시퀀스를 이용한 키 생성
수동 생성	개발자가 직접 로직으로 키 값을 생성

💡 Tip

데이터베이스가 제공하는 자동 생성 기능을 우선 활용하는 것이 가장 안전합니다.

---

📝 2️⃣ useGeneratedKeys 활용법 (DB 자동 생성)

🔹 어노테이션 방식

@Insert("INSERT INTO tbl_memo (text) VALUES (#{text})")
@Options(useGeneratedKeys = true, keyProperty = "id")
int insert(MemoDto dto);

🔹 XML 방식

<insert id="insertXml" useGeneratedKeys="true" keyProperty="id">
    INSERT INTO tbl_memo (text) VALUES (#{text})
</insert>

✅ 설명

• useGeneratedKeys = true : DB의 AUTO_INCREMENT 기능 사용.
• keyProperty : 생성된 키가 주입될 DTO의 필드명.

⚠️ 주의:

useGeneratedKeys는 MySQL, MariaDB 등 AUTO_INCREMENT를 지원하는 DB에서만 동작합니다.

---

📝 3️⃣ @SelectKey 어노테이션 방식 (커스텀 키 생성)

DB가 자동으로 키를 생성하지 않는 경우, 개발자가 직접 키 생성 로직을 정의할 수 있습니다.

@SelectKey(statement = "SELECT MAX(id) + 1 FROM tbl_memo", keyProperty = "id", before = false, resultType = int.class)
@Insert("INSERT INTO tbl_memo (id, text) VALUES (#{id}, #{text})")
int insert(MemoDto dto);

✅ 주요 속성

속성	설명
statement	키 생성 SQL
keyProperty	DTO에 주입할 필드명
before	true: INSERT 이전 실행false: 이후 실행
resultType	반환 타입

💡 설정 가이드

• 시퀀스 사용 시 ➔ before = true
• MAX(id) + 1 방식 ➔ before = false

---

📝 4️⃣ XML 방식

<insert id="insertXml" parameterType="MemoDto">
    <selectKey keyProperty="id" order="AFTER" resultType="int">
        SELECT MAX(id) + 1 FROM tbl_memo
    </selectKey>
    INSERT INTO tbl_memo (id, text) VALUES (#{id}, #{text})
</insert>

🔹 Oracle 시퀀스 예시

<insert id="insertXml" parameterType="MemoDto">
    <selectKey keyProperty="id" order="BEFORE" resultType="int">
        SELECT sequence_name.NEXTVAL FROM DUAL
    </selectKey>
    INSERT INTO tbl_memo (id, text) VALUES (#{id}, #{text})
</insert>

⚠️ Oracle 등 시퀀스를 사용하는 DB는 반드시 order="BEFORE"로 설정해야 합니다.

---

📝 5️⃣ 키 생성 전략 비교

구분	useGeneratedKeys	@SelectKey /
대상 DB	MySQL, MariaDB	Oracle, 커스텀 로직
자동 생성 지원	O	X
복잡한 로직	X	O
동시성 안전성	O	주의 필요
설정 난이도	쉬움	SQL 작성 및 설정 필요

💡 Tip

단순 자동 생성은 useGeneratedKeys,

복잡한 키 생성 로직이나 시퀀스가 필요한 경우 selectKey를 사용합니다.

---

📝 6️⃣ 테스트 코드 예시

@Test
void testInsertWithKey() {
    MemoDto dto = new MemoDto(null, "Key Test", "user@domain.com", LocalDateTime.now(), null);
    int result = memoMapper.insertXml(dto);
    System.out.println("Generated ID: " + dto.getId());
    assertEquals(1, result);
    assertNotNull(dto.getId());
}

✔️ 출력 예시

Generated ID: 1050

---

⚠️ 자주 발생하는 오류

1. 키 값 누락
   • keyProperty 설정이 없으면 DTO에 값이 주입되지 않음.
2. 중복 키 오류
   • SELECT MAX(id) + 1 방식 사용 시 동시성 문제 발생 가능.
3. Generated keys not requested
   • useGeneratedKeys 설정을 빼먹었을 때 발생하는 오류.
4. before/after 설정 오류
   • 시퀀스는 BEFORE, 커스텀 로직은 보통 AFTER 사용.

---

🔥 정리

• useGeneratedKeys: DB 자동 생성 기능 활용 (가장 안전하고 간단)
• selectKey: 커스텀 키 생성, 시퀀스 기반 DB에 적합
• 실무에서는 DB 구조와 환경에 맞는 전략을 선택해야 하며, 동시성 문제에 주의해야 합니다.

---

🔗 참고 자료

• MyBatis 공식 문서
• Key Generation Guide

---