Sangeetha-Grantha

Metadata	Value
Status	Active
Version	1.1.0
Last Updated	2026-09-10
Author	Sangeetha Grantha Team
Document Type	Design reference

Exposed 1.0.0 Features Testing

---

[!NOTE] Design/reference material: this page may include proposals or earlier implementation assumptions. Use current feature map for implemented behavior and current operating steps.

---

Summary

This document tracks the testing and implementation of new Exposed 1.0.0 features in the Sangeetha Grantha codebase.

Version Confirmation

✅ Confirmed: Project is using Exposed 1.0.0 via version catalog:

• gradle/libs.versions.toml: exposed = "1.0.0"
• All Exposed modules (core, dao, jdbc, java-time) resolve to 1.0.0

Features Tested

1. insert().resultedValues ✅ IMPLEMENTED

Location: modules/backend/dal/src/main/kotlin/com/sangita/grantha/backend/dal/repositories/UserRepository.kt

Implementation:

suspend fun create(...): UserDto = DatabaseFactory.dbQuery {
    val now = OffsetDateTime.now(ZoneOffset.UTC)
    val newId = UUID.randomUUID()

    UsersTable
        .insert {
            it[id] = newId
            it[UsersTable.email] = email
            it[UsersTable.fullName] = fullName
            // ... other fields
            it[UsersTable.createdAt] = now
            it[UsersTable.updatedAt] = now
        }
        .resultedValues
        ?.single()
        ?.toUserDto()
        ?: error("Failed to insert user")
}

Benefits:

• ✅ Eliminates post-insert SELECT query
• ✅ Returns inserted row data directly from INSERT statement
• ✅ More efficient (one query instead of two)
• ✅ Atomic operation

Status: ✅ Working - Code compiles and follows Exposed 1.0.0 API

2. updateReturning ✅ IMPLEMENTED

Location: All repository update methods across the codebase

Implementation:

suspend fun update(...): UserDto? = DatabaseFactory.dbQuery {
    val now = OffsetDateTime.now(ZoneOffset.UTC)
    val javaId = id.toJavaUuid()

    // Use Exposed 1.0.0 updateReturning to update and fetch the row in one round-trip
    UsersTable
        .updateReturning(
            where = { UsersTable.id eq javaId }
        ) {
            email?.let { value -> it[UsersTable.email] = value }
            fullName?.let { value -> it[UsersTable.fullName] = value }
            // ... other fields
            it[UsersTable.updatedAt] = now
        }
        .singleOrNull()
        ?.toUserDto()
}

API Confirmed:

• ✅ Syntax: Table.updateReturning(where = {...}, body = {...})
• ✅ Returns Query that can be chained with .singleOrNull() or .map { }
• ✅ Works seamlessly with Exposed 1.0.0

Benefits:

• ✅ Eliminates post-update SELECT query
• ✅ Returns updated row data directly from UPDATE statement
• ✅ More efficient (one query instead of two)
• ✅ Atomic operation

Status: ✅ Fully Implemented - All repository update methods now use updateReturning

Repositories Updated:

1. ✅ UserRepository.update()
2. ✅ KrithiRepository.update(), updateLyricVariant()
3. ✅ ImportRepository.reviewImport()
4. ✅ ComposerRepository.update()
5. ✅ RagaRepository.update()
6. ✅ TalaRepository.update()
7. ✅ TempleRepository.update()
8. ✅ TagRepository.update()
9. ✅ KrithiNotationRepository.updateVariant(), updateRow()

Test Suite

Test File

modules/backend/dal/src/test/kotlin/com/sangita/grantha/backend/dal/repositories/UserRepositoryTest.kt

Test Coverage

1. ✅ create should return UserDto from resultedValues
   • Verifies that resultedValues correctly populates all DTO fields
   • Tests that createdAt and updatedAt are set correctly
2. ✅ create with minimal fields should work
   • Tests nullable field handling
   • Verifies default values
3. ✅ update should return updated UserDto using updateReturning
   • Tests update functionality
   • Verifies all fields are updated correctly
   • Checks that updatedAt changes while createdAt remains unchanged
4. ✅ update with partial fields should only update specified fields
   • Tests selective field updates
   • Verifies unchanged fields remain unchanged
5. ✅ update non-existent user should return null
   • Tests error handling for non-existent records
6. ✅ findById should return created user
   • Integration test for create + findById flow
7. ✅ findById should return null for non-existent user
   • Tests null handling

Test Infrastructure

Database: H2 in-memory (PostgreSQL compatibility mode)

• Allows testing without requiring PostgreSQL instance
• Fast test execution
• Isolated test runs

Dependencies Added:

testImplementation("com.h2database:h2:2.2.224")
testImplementation(libs.kotlinx.coroutines.test)

Compilation Status

✅ Main Code: Compiles successfully ✅ Test Code: Compiles successfully (with minor deprecation warnings for kotlinx.datetime.Instant)

Next Steps

Immediate

1. ✅ Verify Exposed version is 1.0.0
2. ✅ Implement resultedValues in UserRepository.create
3. ✅ Create test suite for resultedValues
4. ✅ Verify updateReturning API- ✅ Exposed 1.0.0 fully supports RETURNING clause via updateReturning and resultedValues
5. ✅ Implement updateReturning in UserRepository.update

Completed Enhancements

1. ✅ Applied resultedValues pattern to all repositories:
   • ✅ KrithiRepository.create, createLyricVariant
   • ✅ ComposerRepository.create
   • ✅ RagaRepository.create
   • ✅ TalaRepository.create
   • ✅ TempleRepository.create
   • ✅ TagRepository.create
   • ✅ ImportRepository.createImport
   • ✅ KrithiNotationRepository.createVariant, createRow
   • ✅ All other create operations
2. ✅ Applied updateReturning pattern to all repositories:
   • ✅ KrithiRepository.update, updateLyricVariant
   • ✅ ComposerRepository.update
   • ✅ RagaRepository.update
   • ✅ TalaRepository.update
   • ✅ TempleRepository.update
   • ✅ TagRepository.update
   • ✅ ImportRepository.reviewImport
   • ✅ KrithiNotationRepository.updateVariant, updateRow
   • ✅ All other update operations
3. Performance benchmarking:
   • ✅ Query count reduction: ~40-50% per create/update operation
   • ✅ Execution time improvement: Eliminated one round-trip per operation
   • ✅ Performance gains documented in database-layer-optimization.md

References

• Exposed GitHub
• Exposed Documentation
• Project ADR: application_documentation/02-architecture/decisions/exposed-dsl-optimization-implementation.md
• Query Optimization Evaluation: application_documentation/06-backend/query-optimization-evaluation.md

Notes

• ✅ The resultedValues feature works as expected and provides immediate performance benefits
• ✅ updateReturning API verified and fully implemented across all repositories
• ✅ Test infrastructure uses H2 for simplicity, but production uses PostgreSQL
• ✅ All changes maintain backward compatibility with existing code
• ✅ All optimizations follow consistent patterns for maintainability
• ✅ Smart collection updates (delta updates) implemented for sections, tags, and ragas

---

Section index · Documentation home · Feature status