Oracle Lock-Free Reservation guide

[radovanradic]

Summary

Adds the micronaut-data-oracle-lockfree-reservation guide (Java, Kotlin, Groovy). It shows how to map Oracle reservable columns with Micronaut Data JDBC 5.2 and update them concurrently without row locks (Oracle Database 23.26.1+ / 26ai).

Example

An account service where balance and credit change concurrently by an amount.

• Entity: @Reservable generates RESERVABLE columns, and @PositiveOrZero generates column CHECK constraints
• Repository: the derived method reserveIncrementBalanceAndDecrementCredit(@Id id, balance, credit) updates both columns atomically with delta assignments
• Controller: create, list and reserve endpoints, with 404 for an unknown account
• ReservationExceptionHandler: maps DataIntegrityViolationException (constraint violation) to 409 Conflict
• Test Resources: uses gvenzl/oracle-free:latest

Guide explains

• How lock-free reservation works, and that pending reservations are not visible in the same transaction until commit
• The generated DDL (RESERVABLE, CK_* constraints) and the delta UPDATE SQL
• Why save/update skip reservable columns, and when to use GenericRepository instead
• The difference between the database DataIntegrityViolationException and a Bean Validation ConstraintViolationException
• How to inspect reservable columns and constraints in the data dictionary

Testing

• ./gradlew micronautDataOracleLockfreeReservationBuild -x micronautDataOracleLockfreeReservationRunNativeTestScript passes
• Gradle Java/Kotlin/Groovy and Maven Java: 3 tests each pass against Oracle Database Free
  • Multi-column reservation
  • CHECK constraint violation mapped to DataIntegrityViolationException, account unchanged
  • 409 Conflict over HTTP
• The DDL, SQL and data dictionary queries in the guide match what the database returned

micronaut-data-oracle-lockfree-reservation-gradle-groovy.pdf
micronaut-data-oracle-lockfree-reservation-gradle-java.pdf
micronaut-data-oracle-lockfree-reservation-gradle-kotlin.pdf
micronaut-data-oracle-lockfree-reservation-maven-groovy.pdf
micronaut-data-oracle-lockfree-reservation-maven-java.pdf
micronaut-data-oracle-lockfree-reservation-pyronaut-python.pdf

[graemerocher]

all new guides need Python examples

[radovanradic]

Added Python guide

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.