@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/skills/kotlin-exposed-patterns/SKILL.md

@@ -0,0 +1,719 @@
+---
+name: kotlin-exposed-patterns
+description: JetBrains Exposed ORM patterns including DSL queries, DAO pattern, transactions, HikariCP connection pooling, Flyway migrations, and repository pattern.
+origin: ECC
+---
+
+# Kotlin Exposed Patterns
+
+Comprehensive patterns for database access with JetBrains Exposed ORM, including DSL queries, DAO, transactions, and production-ready configuration.
+
+## When to Use
+
+- Setting up database access with Exposed
+- Writing SQL queries using Exposed DSL or DAO
+- Configuring connection pooling with HikariCP
+- Creating database migrations with Flyway
+- Implementing the repository pattern with Exposed
+- Handling JSON columns and complex queries
+
+## How It Works
+
+Exposed provides two query styles: DSL for direct SQL-like expressions and DAO for entity lifecycle management. HikariCP manages a pool of reusable database connections configured via `HikariConfig`. Flyway runs versioned SQL migration scripts at startup to keep the schema in sync. All database operations run inside `newSuspendedTransaction` blocks for coroutine safety and atomicity. The repository pattern wraps Exposed queries behind an interface so business logic stays decoupled from the data layer and tests can use an in-memory H2 database.
+
+## Examples
+
+### DSL Query
+
+```kotlin
+suspend fun findUserById(id: UUID): UserRow? =
+    newSuspendedTransaction {
+        UsersTable.selectAll()
+            .where { UsersTable.id eq id }
+            .map { it.toUser() }
+            .singleOrNull()
+    }
+```
+
+### DAO Entity Usage
+
+```kotlin
+suspend fun createUser(request: CreateUserRequest): User =
+    newSuspendedTransaction {
+        UserEntity.new {
+            name = request.name
+            email = request.email
+            role = request.role
+        }.toModel()
+    }
+```
+
+### HikariCP Configuration
+
+```kotlin
+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()
+}
+```
+
+## Database Setup
+
+### HikariCP Connection Pooling
+
+```kotlin
+// 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 Migrations
+
+```kotlin
+// FlywayMigration.kt
+fun runMigrations(config: DatabaseConfig) {
+    Flyway.configure()
+        .dataSource(config.url, config.username, config.password)
+        .locations("classpath:db/migration")
+        .baselineOnMigrate(true)
+        .load()
+        .migrate()
+}
+
+// Application startup
+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)
+    // ...
+}
+```
+
+### Migration Files
+
+```sql
+-- 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);
+```
+
+## Table Definitions
+
+### DSL Style Tables
+
+```kotlin
+// 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")
+}
+```
+
+### Composite Tables
+
+```kotlin
+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 Queries
+
+### Basic CRUD
+
+```kotlin
+// Insert
+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
+    }
+
+// Select by ID
+suspend fun findUserById(id: UUID): UserRow? =
+    newSuspendedTransaction {
+        UsersTable.selectAll()
+            .where { UsersTable.id eq id }
+            .map { it.toUser() }
+            .singleOrNull()
+    }
+
+// Select with conditions
+suspend fun findActiveAdmins(): List<UserRow> =
+    newSuspendedTransaction {
+        UsersTable.selectAll()
+            .where { (UsersTable.role eq Role.ADMIN) }
+            .orderBy(UsersTable.name)
+            .map { it.toUser() }
+    }
+
+// Update
+suspend fun updateUserEmail(id: UUID, newEmail: String): Boolean =
+    newSuspendedTransaction {
+        UsersTable.update({ UsersTable.id eq id }) {
+            it[email] = newEmail
+            it[updatedAt] = CurrentTimestampWithTimeZone
+        } > 0
+    }
+
+// Delete
+suspend fun deleteUser(id: UUID): Boolean =
+    newSuspendedTransaction {
+        UsersTable.deleteWhere { UsersTable.id eq id } > 0
+    }
+
+// Row mapping
+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],
+)
+```
+
+### Advanced Queries
+
+```kotlin
+// Join queries
+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],
+                )
+            }
+    }
+
+// Aggregation
+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()]
+            }
+    }
+
+// Subqueries
+suspend fun findUsersWithOrders(): List<UserRow> =
+    newSuspendedTransaction {
+        UsersTable.selectAll()
+            .where {
+                UsersTable.id inSubQuery
+                    OrdersTable.select(OrdersTable.userId).withDistinct()
+            }
+            .map { it.toUser() }
+    }
+
+// LIKE and pattern matching — always escape user input to prevent wildcard injection
+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() }
+    }
+```
+
+### Pagination
+
+```kotlin
+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)
+    }
+```
+
+### Batch Operations
+
+```kotlin
+// Batch insert
+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 (insert or update on conflict)
+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 Pattern
+
+### Entity Definitions
+
+```kotlin
+// 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 Operations
+
+```kotlin
+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()
+    }
+```
+
+## Transactions
+
+### Suspend Transaction Support
+
+```kotlin
+// Good: Use newSuspendedTransaction for coroutine support
+suspend fun performDatabaseOperation(): Result<User> =
+    runCatching {
+        newSuspendedTransaction {
+            val user = UserEntity.new {
+                name = "Alice"
+                email = "alice@example.com"
+            }
+            // All operations in this block are atomic
+            user.toModel()
+        }
+    }
+
+// Good: Nested transactions with savepoints
+suspend fun transferFunds(fromId: UUID, toId: UUID, amount: Long) {
+    newSuspendedTransaction {
+        val from = UserEntity.findById(fromId) ?: throw NotFoundException("User $fromId not found")
+        val to = UserEntity.findById(toId) ?: throw NotFoundException("User $toId not found")
+
+        // Debit
+        from.balance -= amount
+        // Credit
+        to.balance += amount
+
+        // Both succeed or both fail
+    }
+}
+```
+
+### Transaction Isolation
+
+```kotlin
+suspend fun readCommittedQuery(): List<User> =
+    newSuspendedTransaction(transactionIsolation = Connection.TRANSACTION_READ_COMMITTED) {
+        UserEntity.all().map { it.toModel() }
+    }
+
+suspend fun serializableOperation() {
+    newSuspendedTransaction(transactionIsolation = Connection.TRANSACTION_SERIALIZABLE) {
+        // Strictest isolation level for critical operations
+    }
+}
+```
+
+## Repository Pattern
+
+### Interface Definition
+
+```kotlin
+interface UserRepository {
+    suspend fun findById(id: UUID): User?
+    suspend fun findByEmail(email: String): User?
+    suspend fun findAll(page: Int, limit: Int): Page<User>
+    suspend fun search(query: String): List<User>
+    suspend fun create(request: CreateUserRequest): User
+    suspend fun update(id: UUID, request: UpdateUserRequest): User?
+    suspend fun delete(id: UUID): Boolean
+    suspend fun count(): Long
+}
+```
+
+### Exposed Implementation
+
+```kotlin
+class ExposedUserRepository(
+    private val database: Database,
+) : UserRepository {
+
+    override suspend fun findById(id: UUID): User? =
+        newSuspendedTransaction(db = database) {
+            UsersTable.selectAll()
+                .where { UsersTable.id eq id }
+                .map { it.toUser() }
+                .singleOrNull()
+        }
+
+    override suspend fun findByEmail(email: String): User? =
+        newSuspendedTransaction(db = database) {
+            UsersTable.selectAll()
+                .where { UsersTable.email eq email }
+                .map { it.toUser() }
+                .singleOrNull()
+        }
+
+    override suspend fun findAll(page: Int, limit: Int): Page<User> =
+        newSuspendedTransaction(db = database) {
+            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)
+        }
+
+    override suspend fun search(query: String): List<User> =
+        newSuspendedTransaction(db = database) {
+            val sanitized = escapeLikePattern(query.lowercase())
+            UsersTable.selectAll()
+                .where {
+                    (UsersTable.name.lowerCase() like "%${sanitized}%") or
+                        (UsersTable.email.lowerCase() like "%${sanitized}%")
+                }
+                .orderBy(UsersTable.name)
+                .map { it.toUser() }
+        }
+
+    override suspend fun create(request: CreateUserRequest): User =
+        newSuspendedTransaction(db = database) {
+            UsersTable.insert {
+                it[name] = request.name
+                it[email] = request.email
+                it[role] = request.role
+            }.resultedValues!!.first().toUser()
+        }
+
+    override suspend fun update(id: UUID, request: UpdateUserRequest): User? =
+        newSuspendedTransaction(db = database) {
+            val updated = UsersTable.update({ UsersTable.id eq id }) {
+                request.name?.let { name -> it[UsersTable.name] = name }
+                request.email?.let { email -> it[UsersTable.email] = email }
+                it[updatedAt] = CurrentTimestampWithTimeZone
+            }
+            if (updated > 0) findById(id) else null
+        }
+
+    override suspend fun delete(id: UUID): Boolean =
+        newSuspendedTransaction(db = database) {
+            UsersTable.deleteWhere { UsersTable.id eq id } > 0
+        }
+
+    override suspend fun count(): Long =
+        newSuspendedTransaction(db = database) {
+            UsersTable.selectAll().count()
+        }
+
+    private fun ResultRow.toUser() = User(
+        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],
+    )
+}
+```
+
+## JSON Columns
+
+### JSONB with kotlinx.serialization
+
+```kotlin
+// Custom column type for JSONB
+inline fun <reified T : Any> Table.jsonb(
+    name: String,
+    json: Json,
+): Column<T> = registerColumn(name, object : ColumnType<T>() {
+    override fun sqlType() = "JSONB"
+
+    override fun valueFromDB(value: Any): T = when (value) {
+        is String -> json.decodeFromString(value)
+        is PGobject -> {
+            val jsonString = value.value
+                ?: throw IllegalArgumentException("PGobject value is null for column '$name'")
+            json.decodeFromString(jsonString)
+        }
+        else -> throw IllegalArgumentException("Unexpected value: $value")
+    }
+
+    override fun notNullValueToDB(value: T): Any =
+        PGobject().apply {
+            type = "jsonb"
+            this.value = json.encodeToString(value)
+        }
+})
+
+// Usage in table
+@Serializable
+data class UserMetadata(
+    val preferences: Map<String, String> = emptyMap(),
+    val tags: List<String> = emptyList(),
+)
+
+object UsersTable : UUIDTable("users") {
+    val metadata = jsonb<UserMetadata>("metadata", Json.Default).nullable()
+}
+```
+
+## Testing with Exposed
+
+### In-Memory Database for Tests
+
+```kotlin
+class UserRepositoryTest : FunSpec({
+    lateinit var database: Database
+    lateinit var repository: UserRepository
+
+    beforeSpec {
+        database = Database.connect(
+            url = "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;MODE=PostgreSQL",
+            driver = "org.h2.Driver",
+        )
+        transaction(database) {
+            SchemaUtils.create(UsersTable)
+        }
+        repository = ExposedUserRepository(database)
+    }
+
+    beforeTest {
+        transaction(database) {
+            UsersTable.deleteAll()
+        }
+    }
+
+    test("create and find user") {
+        val user = repository.create(CreateUserRequest("Alice", "alice@example.com"))
+
+        user.name shouldBe "Alice"
+        user.email shouldBe "alice@example.com"
+
+        val found = repository.findById(user.id)
+        found shouldBe user
+    }
+
+    test("findByEmail returns null for unknown email") {
+        val result = repository.findByEmail("unknown@example.com")
+        result.shouldBeNull()
+    }
+
+    test("pagination works correctly") {
+        repeat(25) { i ->
+            repository.create(CreateUserRequest("User $i", "user$i@example.com"))
+        }
+
+        val page1 = repository.findAll(page = 1, limit = 10)
+        page1.data shouldHaveSize 10
+        page1.total shouldBe 25
+        page1.hasNext shouldBe true
+
+        val page3 = repository.findAll(page = 3, limit = 10)
+        page3.data shouldHaveSize 5
+        page3.hasNext shouldBe false
+    }
+})
+```
+
+## Gradle Dependencies
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    // Exposed
+    implementation("org.jetbrains.exposed:exposed-core:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-dao:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-jdbc:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-kotlin-datetime:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-json:1.0.0")
+
+    // Database driver
+    implementation("org.postgresql:postgresql:42.7.5")
+
+    // Connection pooling
+    implementation("com.zaxxer:HikariCP:6.2.1")
+
+    // Migrations
+    implementation("org.flywaydb:flyway-core:10.22.0")
+    implementation("org.flywaydb:flyway-database-postgresql:10.22.0")
+
+    // Testing
+    testImplementation("com.h2database:h2:2.3.232")
+}
+```
+
+## Quick Reference: Exposed Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `object Table : UUIDTable("name")` | Define table with UUID primary key |
+| `newSuspendedTransaction { }` | Coroutine-safe transaction block |
+| `Table.selectAll().where { }` | Query with conditions |
+| `Table.insertAndGetId { }` | Insert and return generated ID |
+| `Table.update({ condition }) { }` | Update matching rows |
+| `Table.deleteWhere { }` | Delete matching rows |
+| `Table.batchInsert(items) { }` | Efficient bulk insert |
+| `innerJoin` / `leftJoin` | Join tables |
+| `orderBy` / `limit` / `offset` | Sort and paginate |
+| `count()` / `sum()` / `avg()` | Aggregation functions |
+
+**Remember**: Use the DSL style for simple queries and the DAO style when you need entity lifecycle management. Always use `newSuspendedTransaction` for coroutine support, and wrap database operations behind a repository interface for testability.