Ktor Exposed Workshop
Latest stable Based on AWS release 0.4.0
A runnable workshop grounded in the 0.4.0 release source.
Learning goal
Section titled “Learning goal”Connect Ktor routes to Exposed JDBC without leaking blocking transactions or pool lifecycle into the HTTP layer. The workshop separates route semantics, repository queries, schema startup, and plugin-owned database resources.
When to use this workshop
Section titled “When to use this workshop”Use it when a Ktor application needs PostgreSQL through Exposed and database settings may later come from Secrets Manager, Parameter Store, or RDS IAM.
Project coordinates
Section titled “Project coordinates”This example is not published. Run ./gradlew :aws-ktor-exposed-examples:test. Applications use the central BOM with bluetape4k-aws-ktor, bluetape4k-aws-exposed, Exposed JDBC, HikariCP, and a JDBC driver.
Concepts to learn
Section titled “Concepts to learn”AwsExposedPlugin creates and closes the registry. call.awsExposedTransaction dispatches blocking JDBC work to the configured transaction context. OrderRepository assumes an active transaction and owns queries only.
Staged walkthrough
Section titled “Staged walkthrough”- Read
OrdersTable,OrderRepository, and their mapping functions. - Follow
ExposedExampleApplication.ktthrough plugin configuration and schema creation. - Trace create/read/list routes into
call.awsExposedTransaction. - Run the PostgreSQL Testcontainers test and inspect the not-found case.
Entry points and expected behavior
Section titled “Entry points and expected behavior”POST /exposed/orders creates an order and returns 201. GET /exposed/orders/{id} returns one row or 404. GET /exposed/orders lists rows and accepts an optional customerId filter.
Recommended exercise order
Section titled “Recommended exercise order”Keep HTTP status decisions in routes, transaction ownership in the plugin boundary, and SQL in the repository. Add a second query only after the first path proves rollback and dispatcher behavior.
Integration boundary
Section titled “Integration boundary”The example joins bluetape4k-aws-exposed, the Ktor plugin, Exposed JDBC, HikariCP, and PostgreSQL. AWS credentials are not required locally because test settings come directly from the container.
Configuration checkpoints
Section titled “Configuration checkpoints”Configure JDBC URL, driver, username, password, and pool size in defaultDatabase. Production code can resolve the same fields before plugin installation, but must not fetch secrets inside every transaction.
Failure modes
Section titled “Failure modes”Wrong driver or URL, an exhausted pool, schema initialization failure, blocking work on the wrong dispatcher, and repository calls outside a transaction are the primary failures. Closing the registry while requests are active can interrupt work.
Operations
Section titled “Operations”Monitor pool saturation, acquisition time, transaction failures, and query latency. Stop new requests before closing the plugin-owned registry. Rotate credentials through a planned pool refresh rather than mutating active connections.
Testing the boundary
Section titled “Testing the boundary”ExposedExampleApplicationTest starts PostgreSQL, supplies container JDBC settings, and verifies create, read, list, filter, and not-found behavior through Ktor test application routes.
Next learning path
Section titled “Next learning path”Continue with the Spring Boot Exposed workshop to compare bean-managed lifecycle, then use the bluetape4k-exposed manual for repository patterns and transaction design.
Limitations
Section titled “Limitations”The local test does not exercise Secrets Manager, Parameter Store, RDS IAM, TLS, credential rotation, migrations, or production pool sizing.
Release diagrams
Section titled “Release diagrams”These diagrams are loaded directly from README assets published with the 0.4.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.
aws ktor exposed examples Architecture diagram
Section titled “aws ktor exposed examples Architecture diagram”
Release README: examples/aws-ktor-exposed-examples/README.md