Kotlin Exposed 패턴

Kotlin Exposed 패턴은(는) 무엇을 하나요?

JetBrains Exposed ORM을 사용한 데이터베이스 액세스를 위한 포괄적인 패턴으로, DSL 쿼리, DAO, 트랜잭션, 프로덕션 준비 구성을 포함합니다.

사용 시기

• Exposed로 데이터베이스 액세스 설정
• Exposed DSL 또는 DAO를 사용한 SQL 쿼리 작성
• HikariCP로 커넥션 풀링 구성
• Flyway로 데이터베이스 마이그레이션 생성
• Exposed로 리포지토리 패턴 구현
• JSON 컬럼 및 복잡한 쿼리 처리

작동 방식

Exposed는 두 가지 쿼리 스타일을 제공합니다. DSL은 직접 SQL과 유사한 표현식을 위한 것이고 DAO는 엔티티 수명 주기 관리를 위한 것입니다. HikariCP는 HikariConfig를 통해 구성된 재사용 가능한 데이터베이스 연결 풀을 관리합니다. Flyway는 시작 시 버전이 지정된 SQL 마이그레이션 스크립트를 실행하여 스키마 동기화를 유지합니다. 모든 데이터베이스 작업은 코루틴 안전성과 원자성을 위해 newSuspendedTransaction 블록 내에서 실행됩니다. 리포지토리 패턴은 Exposed 쿼리를 인터페이스 뒤에 래핑하여 비즈니스 로직이 데이터 레이어와 분리되고 테스트에서 인메모리 H2 데이터베이스를 사용할 수 있도록 합니다.

예제

DSL 쿼리

suspend fun findUserById(id: UUID): UserRow? =
    newSuspendedTransaction {
        UsersTable.selectAll()
            .where { UsersTable.id eq id }
            .map { it.toUser() }
            .singleOrNull()
    }

DAO 엔티티 사용

suspend fun createUser(request: CreateUserRequest): User =
    newSuspendedTransaction {
        UserEntity.new {
            name = request.name
            email = request.email
            role = request.role
        }.toModel()
    }

HikariCP 구성

val hikariConfig = HikariConfig().apply {
    driverClassName = config.driver
    jdbcUrl = config.url
    username = config.username
    password = config.password
    maximumPoolSize = config.maxPoolSize
    isAutoCommit = false
    transactionIsolation = "TRANSACTION_READ_COMMITTED"
    validate()
}

데이터베이스 설정

HikariCP 커넥션 풀링

// DatabaseFactory.kt
object DatabaseFactory {
    fun create(config: DatabaseConfig): Database {
        val hikariConfig = HikariConfig().apply {
            driverClassName = config.driver
            jdbcUrl = config.url
            username = config.username
            password = config.password
            maximumPoolSize = config.maxPoolSize
            isAutoCommit = false
            transactionIsolation = "TRANSACTION_READ_COMMITTED"
            validate()
        }

        return Database.connect(HikariDataSource(hikariConfig))
    }
}

data class DatabaseConfig(
    val url: String,
    val driver: String = "org.postgresql.Driver",
    val username: String = "",
    val password: String = "",
    val maxPoolSize: Int = 10,
)

Flyway 마이그레이션

// FlywayMigration.kt
fun runMigrations(config: DatabaseConfig) {
    Flyway.configure()
        .dataSource(config.url, config.username, config.password)
        .locations("classpath:db/migration")
        .baselineOnMigrate(true)
        .load()
        .migrate()
}

// 애플리케이션 시작
fun Application.module() {
    val config = DatabaseConfig(
        url = environment.config.property("database.url").getString(),
        username = environment.config.property("database.username").getString(),
        password = environment.config.property("database.password").getString(),
    )
    runMigrations(config)
    val database = DatabaseFactory.create(config)
    // ...
}

마이그레이션 파일

-- src/main/resources/db/migration/V1__create_users.sql
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) NOT NULL UNIQUE,
    role VARCHAR(20) NOT NULL DEFAULT 'USER',
    metadata JSONB,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_role ON users(role);

테이블 정의

DSL 스타일 테이블

// tables/UsersTable.kt
object UsersTable : UUIDTable("users") {
    val name = varchar("name", 100)
    val email = varchar("email", 255).uniqueIndex()
    val role = enumerationByName<Role>("role", 20)
    val metadata = jsonb<UserMetadata>("metadata", Json.Default).nullable()
    val createdAt = timestampWithTimeZone("created_at").defaultExpression(CurrentTimestampWithTimeZone)
    val updatedAt = timestampWithTimeZone("updated_at").defaultExpression(CurrentTimestampWithTimeZone)
}

object OrdersTable : UUIDTable("orders") {
    val userId = uuid("user_id").references(UsersTable.id)
    val status = enumerationByName<OrderStatus>("status", 20)
    val totalAmount = long("total_amount")
    val currency = varchar("currency", 3)
    val createdAt = timestampWithTimeZone("created_at").defaultExpression(CurrentTimestampWithTimeZone)
}

object OrderItemsTable : UUIDTable("order_items") {
    val orderId = uuid("order_id").references(OrdersTable.id, onDelete = ReferenceOption.CASCADE)
    val productId = uuid("product_id")
    val quantity = integer("quantity")
    val unitPrice = long("unit_price")
}

복합 테이블

object UserRolesTable : Table("user_roles") {
    val userId = uuid("user_id").references(UsersTable.id, onDelete = ReferenceOption.CASCADE)
    val roleId = uuid("role_id").references(RolesTable.id, onDelete = ReferenceOption.CASCADE)
    override val primaryKey = PrimaryKey(userId, roleId)
}

DSL 쿼리

기본 CRUD

// 삽입
suspend fun insertUser(name: String, email: String, role: Role): UUID =
    newSuspendedTransaction {
        UsersTable.insertAndGetId {
            it[UsersTable.name] = name
            it[UsersTable.email] = email
            it[UsersTable.role] = role
        }.value
    }

// ID로 조회
suspend fun findUserById(id: UUID): UserRow? =
    newSuspendedTransaction {
        UsersTable.selectAll()
            .where { UsersTable.id eq id }
            .map { it.toUser() }
            .singleOrNull()
    }

// 조건부 조회
suspend fun findActiveAdmins(): List<UserRow> =
    newSuspendedTransaction {
        UsersTable.selectAll()
            .where { (UsersTable.role eq Role.ADMIN) }
            .orderBy(UsersTable.name)
            .map { it.toUser() }
    }

// 업데이트
suspend fun updateUserEmail(id: UUID, newEmail: String): Boolean =
    newSuspendedTransaction {
        UsersTable.update({ UsersTable.id eq id }) {
            it[email] = newEmail
            it[updatedAt] = CurrentTimestampWithTimeZone
        } > 0
    }

// 삭제
suspend fun deleteUser(id: UUID): Boolean =
    newSuspendedTransaction {
        UsersTable.deleteWhere { UsersTable.id eq id } > 0
    }

// 행 매핑
private fun ResultRow.toUser() = UserRow(
    id = this[UsersTable.id].value,
    name = this[UsersTable.name],
    email = this[UsersTable.email],
    role = this[UsersTable.role],
    metadata = this[UsersTable.metadata],
    createdAt = this[UsersTable.createdAt],
    updatedAt = this[UsersTable.updatedAt],
)

고급 쿼리

// 조인 쿼리
suspend fun findOrdersWithUser(userId: UUID): List<OrderWithUser> =
    newSuspendedTransaction {
        (OrdersTable innerJoin UsersTable)
            .selectAll()
            .where { OrdersTable.userId eq userId }
            .orderBy(OrdersTable.createdAt, SortOrder.DESC)
            .map { row ->
                OrderWithUser(
                    orderId = row[OrdersTable.id].value,
                    status = row[OrdersTable.status],
                    totalAmount = row[OrdersTable.totalAmount],
                    userName = row[UsersTable.name],
                )
            }
    }

// 집계
suspend fun countUsersByRole(): Map<Role, Long> =
    newSuspendedTransaction {
        UsersTable
            .select(UsersTable.role, UsersTable.id.count())
            .groupBy(UsersTable.role)
            .associate { row ->
                row[UsersTable.role] to row[UsersTable.id.count()]
            }
    }

// 서브쿼리
suspend fun findUsersWithOrders(): List<UserRow> =
    newSuspendedTransaction {
        UsersTable.selectAll()
            .where {
                UsersTable.id inSubQuery
                    OrdersTable.select(OrdersTable.userId).withDistinct()
            }
            .map { it.toUser() }
    }

// LIKE 및 패턴 매칭 — 와일드카드 주입을 방지하기 위해 항상 사용자 입력을 이스케이프 처리합니다
private fun escapeLikePattern(input: String): String =
    input.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")

suspend fun searchUsers(query: String): List<UserRow> =
    newSuspendedTransaction {
        val sanitized = escapeLikePattern(query.lowercase())
        UsersTable.selectAll()
            .where {
                (UsersTable.name.lowerCase() like "%${sanitized}%") or
                    (UsersTable.email.lowerCase() like "%${sanitized}%")
            }
            .map { it.toUser() }
    }

페이지네이션

data class Page<T>(
    val data: List<T>,
    val total: Long,
    val page: Int,
    val limit: Int,
) {
    val totalPages: Int get() = ((total + limit - 1) / limit).toInt()
    val hasNext: Boolean get() = page < totalPages
    val hasPrevious: Boolean get() = page > 1
}

suspend fun findUsersPaginated(page: Int, limit: Int): Page<UserRow> =
    newSuspendedTransaction {
        val total = UsersTable.selectAll().count()
        val data = UsersTable.selectAll()
            .orderBy(UsersTable.createdAt, SortOrder.DESC)
            .limit(limit)
            .offset(((page - 1) * limit).toLong())
            .map { it.toUser() }

        Page(data = data, total = total, page = page, limit = limit)
    }

배치 작업

// 배치 삽입
suspend fun insertUsers(users: List<CreateUserRequest>): List<UUID> =
    newSuspendedTransaction {
        UsersTable.batchInsert(users) { user ->
            this[UsersTable.name] = user.name
            this[UsersTable.email] = user.email
            this[UsersTable.role] = user.role
        }.map { it[UsersTable.id].value }
    }

// Upsert (충돌 시 삽입 또는 업데이트)
suspend fun upsertUser(id: UUID, name: String, email: String) {
    newSuspendedTransaction {
        UsersTable.upsert(UsersTable.email) {
            it[UsersTable.id] = EntityID(id, UsersTable)
            it[UsersTable.name] = name
            it[UsersTable.email] = email
            it[updatedAt] = CurrentTimestampWithTimeZone
        }
    }
}

DAO 패턴

엔티티 정의

// entities/UserEntity.kt
class UserEntity(id: EntityID<UUID>) : UUIDEntity(id) {
    companion object : UUIDEntityClass<UserEntity>(UsersTable)

    var name by UsersTable.name
    var email by UsersTable.email
    var role by UsersTable.role
    var metadata by UsersTable.metadata
    var createdAt by UsersTable.createdAt
    var updatedAt by UsersTable.updatedAt

    val orders by OrderEntity referrersOn OrdersTable.userId

    fun toModel(): User = User(
        id = id.value,
        name = name,
        email = email,
        role = role,
        metadata = metadata,
        createdAt = createdAt,
        updatedAt = updatedAt,
    )
}

class OrderEntity(id: EntityID<UUID>) : UUIDEntity(id) {
    companion object : UUIDEntityClass<OrderEntity>(OrdersTable)

    var user by UserEntity referencedOn OrdersTable.userId
    var status by OrdersTable.status
    var totalAmount by OrdersTable.totalAmount
    var currency by OrdersTable.currency
    var createdAt by OrdersTable.createdAt

    val items by OrderItemEntity referrersOn OrderItemsTable.orderId
}

DAO 작업

suspend fun findUserByEmail(email: String): User? =
    newSuspendedTransaction {
        UserEntity.find { UsersTable.email eq email }
            .firstOrNull()
            ?.toModel()
    }

suspend fun createUser(request: CreateUserRequest): User =
    newSuspendedTransaction {
        UserEntity.new {
            name = request.name
            email = request.email
            role = request.role
        }.toModel()
    }

suspend fun updateUser(id: UUID, request: UpdateUserRequest): User? =
    newSuspendedTransaction {
        UserEntity.findById(id)?.apply {
            request.name?.let { name = it }
            request.email?.let { email = it }
            updatedAt = OffsetDateTime.now(ZoneOffset.UTC)
        }?.toModel()
    }

트랜잭션

Suspend 트랜잭션 지원

// 좋음: 코루틴 지원을 위해 newSuspendedTransaction 사용
suspend fun performDatabaseOperation(): Result<User> =
    runCatching {
        newSuspendedTransaction {
            val user = UserEntity.new {
                name = "Alice"
                email = "[email protected]"
            }
            // 이 블록의 모든 작업은 원자적입니다
            user.toModel()
        }
    }

// 좋음: 저장점이 있는 중첩 트랜잭션
suspend fun transferFunds(fromId: UUID, toId: UUID, amount: Long) {
    newSuspendedTransaction {
        val from = UserEntity.findById(fromId) ?: throw NotFoundException("사용자 $fromId를 찾을 수 없음")
        val to = UserEntity.findById(toId) ?: throw NotFoundException("사용자 $toId를 찾을 수 없음")

        // 출금
        from.balance -= amount
        // 입금
        to.balance += amount

        // 둘 다 성공하거나 둘 다 실패합니다
    }
}

트랜잭션 격리

suspend fun readCommittedQuery(): List<User> =
    newSuspendedTransaction(transactionIsolation = Connection.TRANSACTION_READ_COMMITTED) {
        UserEntity.all().map { it.toModel() }
    }

suspend fun serializableOperation() {
    newSuspendedTransaction(transactionIsolation = Connection.TRANSACTION_SERIALIZABLE) {
        // 중요한 작업을 위한 가장 엄격한 격리 수준
    }
}

리포지토리 패턴

인터페이스 정의

interface UserRepository {
    suspend fun findById(id: UUID): User?
    suspend fun findByEmail(email: String): User?
    suspend fun findAll(page: Int, limit: Int): List<User>
    suspend fun create(request: CreateUserRequest): User
    suspend fun update(id: UUID, request: UpdateUserRequest): User?
    suspend fun delete(id: UUID): Boolean
}

구현

class ExposedUserRepository : UserRepository {
    override suspend fun findById(id: UUID): User? =
        newSuspendedTransaction {
            UserEntity.findById(id)?.toModel()
        }

    override suspend fun findByEmail(email: String): User? =
        newSuspendedTransaction {
            UserEntity.find { UsersTable.email eq email }
                .firstOrNull()
                ?.toModel()
        }

    override suspend fun findAll(page: Int, limit: Int): List<User> =
        newSuspendedTransaction {
            UserEntity.all()
                .orderBy(UserEntity::createdAt, SortOrder.DESC)
                .limit(limit)
                .offset(((page - 1) * limit).toLong())
                .toList()
                .map { it.toModel() }
        }

    override suspend fun create(request: CreateUserRequest): User =
        newSuspendedTransaction {
            UserEntity.new {
                name = request.name
                email = request.email
                role = request.role
            }.toModel()
        }

    override suspend fun update(id: UUID, request: UpdateUserRequest): User? =
        newSuspendedTransaction {
            UserEntity.findById(id)?.apply {
                request.name?.let { name = it }
                request.email?.let { email = it }
                request.role?.let { role = it }
                updatedAt = OffsetDateTime.now(ZoneOffset.UTC)
            }?.toModel()
        }

    override suspend fun delete(id: UUID): Boolean =
        newSuspendedTransaction {
            UserEntity.findById(id)?.delete() != null
        }
}

JSON 컬럼

JSONB 직렬화

import org.jetbrains.exposed.sql.json.jsonb

@Serializable
data class UserMetadata(
    val department: String = "",
    val title: String = "",
    val phoneNumber: String? = null,
    val preferences: Map<String, Any> = emptyMap(),
)

// 테이블 정의
object UsersTable : UUIDTable("users") {
    // ...
    val metadata = jsonb<UserMetadata>("metadata", Json.Default).nullable()
}

// 사용 예
suspend fun updateUserMetadata(id: UUID, metadata: UserMetadata) {
    newSuspendedTransaction {
        UsersTable.update({ UsersTable.id eq id }) {
            it[UsersTable.metadata] = metadata
            it[updatedAt] = CurrentTimestampWithTimeZone
        }
    }
}

suspend fun findUsersByDepartment(department: String): List<UserRow> =
    newSuspendedTransaction {
        UsersTable.selectAll()
            .where {
                UsersTable.metadata.isNotNull()
            }
            .map { it.toUser() }
            .filter { user ->
                user.metadata?.department == department
            }
    }

JSON 변환

// 사용자 정의 직렬화를 위한 JSON 변환
@Serializable
data class UserMetadata(
    val department: String = "",
    val title: String = "",
    val phoneNumber: String? = null,
    val preferences: Map<String, Any> = emptyMap(),
)

// ktor 클라이언트로 JSONB 컬럼 업데이트
suspend fun updateUserMetadata(id: UUID, metadata: UserMetadata) {
    newSuspendedTransaction {
        UsersTable.update({ UsersTable.id eq id }) {
            it[UsersTable.metadata] = metadata
            it[updatedAt] = CurrentTimestampWithTimeZone
        }
    }
}

테스트

인메모리 H2 데이터베이스

// TestDatabase.kt
testImplementation("com.h2database:h2:2.2.224")

// 테스트용 데이터베이스 팩토리
object TestDatabaseFactory {
    fun create(): Database {
        val config = HikariConfig().apply {
            driverClassName = "org.h2.Driver"
            jdbcUrl = "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1"
            username = "sa"
            password = ""
            maximumPoolSize = 2
            isAutoCommit = false
        }

        return Database.connect(HikariDataSource(config))
    }
}

// 테스트에서 사용
class UserRepositoryTest {
    private val database = TestDatabaseFactory.create()
    private val repository = ExposedUserRepository()

    @BeforeTest
    fun setup() {
        transaction(database) {
            SchemaUtils.create(UsersTable)
            SchemaUtils.create(OrdersTable)
        }
    }

    @AfterTest
    fun cleanup() {
        transaction(database) {
            SchemaUtils.drop(UsersTable)
            SchemaUtils.drop(OrdersTable)
        }
    }

    @Test
    fun `should create and find user by email`() = runTest {
        val user = repository.create(
            name = "Alice",
            email = "[email protected]",
            role = Role.USER
        )

        val found = repository.findByEmail("[email protected]")
        assertEquals(user.id, found?.id)
        assertEquals(user.name, found?.name)
    }
}

모범 사례

스키마 제약 조건

// 좋음: 명시적인 제약 조건 정의
object UsersTable : UUIDTable("users") {
    val name = varchar("name", 100)
    val email = varchar("email", 255).uniqueIndex()
    val role = enumerationByName<Role>("role", 20)
    val metadata = jsonb<UserMetadata>("metadata", Json.Default).nullable()
    val createdAt = timestampWithTimeZone("created_at").defaultExpression(CurrentTimestampWithTimeZone)
    val updatedAt = timestampWithTimeZone("updated_at").defaultExpression(CurrentTimestampWithTimeZone)
}

// 피해야 함: 암시적 제약 조건
object UsersTable : UUIDTable("users") {
    val name = varchar("name", 100)
    val email = varchar("email", 255)
    val role = enumerationByName<Role>("role", 20)
}

인덱스 전략

// 좋음: 자주 쿼리되는 컬럼에 인덱스 사용
object UsersTable : UUIDTable("users") {
    val email = varchar("email", 255).uniqueIndex()
    val role = varchar("role", 20).index()
    val createdAt = timestampWithTimeZone("created_at").index()
}

// 피해야 함: 불필요한 인덱스는 쓰기 성능을 저하시킴
object UsersTable : UUIDTable("users") {
    val name = varchar("name", 100).index()
    val email = varchar("email", 255).index()
    val role = varchar("role", 20).index()
    val createdAt = timestampWithTimeZone("created_at").index()
    val updatedAt = timestampWithTimeZone("updated_at").index()
    // 모든 컬럼에 인덱스가 있으면 유지보수 부담이 증가하고 쓰기 성능이 저하됩니다
}

연결 풀 크기 조정

// 좋음: 동시 사용자 및 지연 시간을 기준으로 풀 크기 계산
// 풀 크기 = (코어 수 * 2) + 효율적인 I/O 처리
val hikariConfig = HikariConfig().apply {
    maximumPoolSize = Runtime.getRuntime().availableProcessors() * 2
    minimumIdle = (maximumPoolSize / 2).coerceAtLeast(1)
    connectionTimeout = 30000L // 30초
    idleTimeout = 600000L // 10분
    maxLifetime = 1800000L // 30분
}

// 피해야 함: 너무 많거나 적은 풀 크기
val badConfig = HikariConfig().apply {
    maximumPoolSize = 200 // 연결 오버헤드로 인한 성능 저하 가능
    connectionTimeout = 1000L // 너무 짧은 타임아웃
}

안티 패턴

피해야 할 사항

// 피해야 함: 모든 작업에 새 트랜잭션 생성
// 각각 별도의 트랜잭션이 있는 여러 데이터베이스 호출
suspend fun badPattern() {
    val user1 = newSuspendedTransaction {
        findUserById(id1)
    }
    val user2 = newSuspendedTransaction {
        findUserById(id2)
    }
    // 각 호출은 자체 트랜잭션에 있음
}

// 좋음: 작업을 단일 트랜잭션으로 그룹화
suspend fun goodPattern() {
    newSuspendedTransaction {
        val user1 = findUserById(id1)
        val user2 = findUserById(id2)
        // 두 조회는 동일한 트랜잭션에 있음
    }
}

// 피해야 함: 예외 누출
suspend fun badExceptionHandling() {
    newSuspendedTransaction {
        throw RuntimeException("오류")
        // 처리되지 않은 예외는 트랜잭션을 롤백함
    }
}

// 좋음: try-catch로 예외 처리
suspend fun goodExceptionHandling() {
    newSuspendedTransaction {
        try {
            riskyOperation()
        } catch (e: Exception) {
            // 예외 처리 및 트랜잭션 상태 관리
            rollback()
            throw e
        }
    }
}