kotlin-exposed-patterns로 Kotlin의 DB 처리를 정리하기
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
원문: kotlin-exposed-patterns로 Kotlin의 DB 처리를 정리하기（cccskills）
스킬 페이지: kotlin-exposed-patterns
이 글의 결론
Kotlin으로 서버 사이드를 작성한다면, kotlin-exposed-patterns를 도입하면 JetBrains Exposed의 쿼리부터 테스트까지 에이전트가 일관된 방식으로 제안해줍니다.
이 글에서 다루는 내용은 스킬이 다루는 범위, Claude Code나 Codex에 도입하는 방법, 실제로 보낼 요청문 예시입니다.
사용 전에 확인해두고 싶은 사항도 순서대로 설명합니다.
kotlin-exposed-patterns를 도입하면 에이전트가 Exposed 코드를 매번 동일한 형태로 구성하게 됩니다.
예를 들어 다음과 같이 요청했다고 가정해봅시다.
Exposed로 사용자 검색과 페이지 분할을 구현해줘
에이전트는 테이블 정의, 검색 함수, 페이지 정보를 담는 데이터 클래스를 함께 반환합니다.
각 함수는 newSuspendedTransaction 블록으로 감싸져 있어 코루틴(Kotlin의 비동기 처리 메커니즘) 안에서도 안전하게 동작합니다.
검색어는 LIKE의 특수문자를 이스케이프한 후 사용하므로, 사용자 입력으로 인한 의도치 않은 일치가 발생하지 않습니다.
페이지 분할 결과는 다음 항목을 가진 Page 클래스로 받습니다.
| 항목 | 내용 |
|---|---|
| data | 해당 페이지의 레코드 목록 |
| total | 전체 건수 |
| page / limit | 현재 페이지 번호와 1페이지당 건수 |
| totalPages | 총 페이지 수 |
| hasNext / hasPrevious | 다음·이전 페이지 존재 여부 |
이 스킬은 GitHub의 affaan-m/ECC에 공개되어 있으며, 리포지토리 스타 수는 288823입니다.
내용은 SKILL.md 파일 하나로 구성되어 있으며, 사용자와 주문을 소재로 한 코드 예시가 중심입니다.
이 스킬은 Exposed에서의 데이터 액세스를 4가지 측면에서 지원합니다.
"쿼리", "연결과 구조 변경", "트랜잭션", "분리와 테스트"입니다.
에이전트는 이러한 예시를 직접 사용하는 테이블에 맞춰 코드를 작성합니다.
Exposed에는 두 가지 작성 방식이 있으며, 스킬은 두 방식 모두 예시를 제공합니다.
사용 구분 기준은 다음과 같습니다.
| 작성 방식 | 특징 | 적합한 상황 |
|---|---|---|
| DSL | SQL에 가까운 표현으로 작성 | 단순한 검색이나 업데이트 |
| DAO | 레코드를 객체로 다룸 | 생성·업데이트 등 엔티티 상태를 관리하고 싶을 때 |
DSL 예시는 등록·조회·업데이트·삭제의 기본 조작부터, 테이블 조인·집계·서브쿼리·페이지 분할까지 갖추고 있습니다.
여러 건을 일괄 삽입하는 batchInsert나, 중복 시 업데이트로 전환하는 upsert도 포함됩니다.
PostgreSQL의 JSONB 컬럼을 kotlinx.serialization으로 읽고 쓰는 컬럼 타입 정의도 포함되어 있습니다.
연결 관련해서는 HikariCP 커넥션 풀(연결을 재사용하는 메커니즘)과 Flyway 마이그레이션을 조합하는 구성입니다.
HikariCP에서는 최대 연결 수, 자동 커밋 비활성화, 격리 수준 READ_COMMITTED를 지정합니다.
Flyway는 앱 시작 시에 번호가 붙은 SQL 파일을 순서대로 적용하여 테이블 구조를 통일합니다.
마이그레이션 SQL은 src/main/resources/db/migration/에 V1__create_users.sql과 같은 이름으로 배치하는 형태입니다.
시작 처리에서는 마이그레이션을 먼저 실행한 후 연결 풀을 생성합니다.
모든 데이터베이스 작업을 newSuspendedTransaction 블록 내에서 실행하는 것이 이 스킬의 원칙입니다.
블록 내의 처리는 함께 성공하거나, 함께 실패합니다.
송금처럼 2건의 업데이트를 동시에 처리하고 싶은 상황의 예시나, SERIALIZABLE 등 격리 수준을 변경하는 예시도 있습니다.
비즈니스 처리와 데이터 액세스를 분리하기 위해 사용하는 것이 리포지토리 패턴(데이터 입출력을 하나의 창구로 모으는 설계)입니다.
UserRepository라는 인터페이스에 검색·생성·업데이트·삭제·건수 조회를 정의하고, Exposed에서의 구현 클래스를 별도로 준비하는 형태입니다.
테스트에서는 H2 인메모리 데이터베이스를 PostgreSQL 호환 모드로 실행하여 구현 클래스를 그대로 검증합니다.
테스트 예시는 3가지입니다.
생성한 사용자를 조회할 수 있는지, 미등록 이메일에서 null이 반환되는지, 25건을 10건씩 나눈 페이지 정보가 올바른지 확인합니다.
각 테스트 전에 테이블을 비우므로, 테스트 간에 서로 영향을 주지 않습니다.
설치는 명령어로 직접 설치하는 방법과 에이전트에게 맡기는 방법, 2가지입니다.
명령어를 실행하면 Claude Code나 Codex 등 설치할 에이전트를 선택할 수 있습니다.
npx skills add https://github.com/affaan-m/ECC --skill kotlin-exposed-patterns
에이전트에게 맡기는 경우, 다음 내용을 그대로 보내주세요.
내용 확인부터 배치까지 일괄로 요청하는 내용입니다.
次の Agent Skill をインストールしてください。
https://github.com/affaan-m/ECC/tree/main/skills/kotlin-exposed-patterns
まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/kotlin-exposed-patterns/、Codex なら ~/.agents/skills/kotlin-exposed-patterns/ に配置してください。
배치 위치는 에이전트 종류와 스킬을 사용할 범위에 따라 결정됩니다.
| 에이전트 | 모든 프로젝트에서 사용 | 특정 프로젝트에서만 사용 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | 프로젝트의 .claude/skills/ |
| Codex | ~/.agents/skills/ | 프로젝트의 .agents/skills/ |
Exposed를 사용하는 프로젝트가 하나뿐이라면, 프로젝트 쪽에 배치하는 방법이 적합합니다.
요청문에는 테이블 내용이나 연결 대상 등 직접 사용하는 조건을 함께 적어주세요.
그렇게 하면 반환되는 코드가 해당 조건에 맞는 내용이 됩니다.
PostgreSQL에 연결하는 접속 설정을 HikariCP와 Flyway로 만들어줘.
풀의 최대 수는 10으로 해줘
반환되는 것은 접속 정보를 담는 데이터 클래스, HikariCP에서 Exposed의 Database를 생성하는 팩토리, Flyway를 실행하는 함수입니다.
첫 번째 마이그레이션 SQL과, 시작 시에 마이그레이션을 실행한 후 연결하는 처리도 포함됩니다.
주문 테이블을 추가하고, 지정한 사용자의 주문을 최신순으로 목록으로 가져오는 처리를 작성해줘
사용자 테이블을 참조하는 주문 테이블 정의와, 두 테이블을 innerJoin으로 결합하는 검색 함수가 반환됩니다.
정렬 순서는 생성일시 내림차순입니다.
스킬 예시에 따르면, 결과는 주문 ID·상태·금액·사용자명을 가진 데이터 클래스에 담깁니다.
데이터 액세스를 인터페이스로 분리하고, H2로 테스트해줘
갖춰지는 것은 리포지토리 인터페이스, Exposed에서의 구현 클래스, H2를 사용하는 테스트 코드 3가지입니다.
테스트는 FunSpec 형식으로, 각 테스트 전에 테이블을 비우는 처리가 포함됩니다.
이 스킬은 패턴 모음이므로, 버전이나 연결 대상은 프로젝트에 맞게 직접 확인할 필요가 있습니다.
문서의 Gradle 설정은 다음 버전을 전제로 합니다.
| 라이브러리 | 문서의 버전 |
|---|---|
| Exposed（core、dao、jdbc、kotlin-datetime、json） | 1.0.0 |
| PostgreSQL 드라이버 | 42.7.5 |
| HikariCP | 6.2.1 |
| Flyway（core、database-postgresql） | 10.22.0 |
| H2（테스트용） | 2.3.232 |
직접 사용하는 버전이 다른 경우, 요청문에 버전을 알려준 후 작성시켜 주세요.
생성된 코드는 빌드와 테스트를 통과한 후 반영하는 것이 안전합니다.
설정 예시와 SQL은 PostgreSQL을 전제로 합니다.
JSONB 컬럼이나 gen_random_uuid()를 이용한 기본 키 생성, PGobject를 사용한 변환은 PostgreSQL 고유의 작성 방식입니다.
다른 데이터베이스 제품용 설정 예시는 스킬에 포함되어 있지 않습니다.
연결 대상 URL·드라이버·사용자명·비밀번호는 직접 환경에 맞게 준비합니다.
스킬 예시에서는 이것들을 앱의 설정 파일에서 읽어오는 형태입니다.
인증 정보를 코드에 직접 작성하지 않도록 주의해주세요.
라이선스는 MIT이며, 포함된 파일은 SKILL.md 하나뿐입니다.
스크립트는 포함되어 있지 않습니다.
그래도 도입 전에 SKILL.md를 열어 내용을 한 번 확인해두는 것이 안심됩니다.
단순한 검색이나 업데이트는 DSL, 레코드를 객체로서 생성·업데이트하면서 다루고 싶을 때는 DAO가 기준입니다.
스킬도 이 사용 구분을 권장합니다.
스킬의 설정 예시와 SQL은 PostgreSQL용이며, 다른 제품의 절차는 포함되어 있지 않습니다.
Exposed의 작성 방식 자체는 참고가 됩니다.
다만, 드라이버나 데이터베이스 고유의 부분은 직접 조사할 필요가 있습니다.
스킬의 테스트 예시는 H2 인메모리 데이터베이스를 PostgreSQL 호환 모드로 동작시키는 형태입니다.
테스트 시작 시에 테이블을 생성하고, 각 테스트 전에 내용을 초기화하는 흐름이므로 외부 데이터베이스 서버는 사용하지 않습니다.
kotlin-exposed-patterns는 JetBrains Exposed를 사용한 Kotlin의 데이터베이스 처리를, 쿼리부터 테스트까지 하나의 형태로 통일하기 위한 스킬입니다.
대상은 DSL과 DAO의 쿼리, HikariCP와 Flyway의 연결 설정, 리포지토리 분리와 H2에서의 테스트입니다.
모두 에이전트가 동일한 패턴으로 제안할 수 있게 됩니다.
PostgreSQL과 Exposed로 서버 사이드를 작성하는 분일수록, 그대로 사용할 수 있는 부분이 많은 스킬입니다.
설치 위치나 소개 내용은 cccskills 페이지에서 확인할 수 있습니다.
이 글은 cccskills의 읽을거리 「kotlin-exposed-patterns로 Kotlin의 DB 처리를 정리하기」의 전재입니다.
스킬 상세와 설치 방법은 cccskills의 kotlin-exposed-patterns 페이지에 있습니다.