docs: Add docs for R2DBC DAO by vnikolova · Pull Request #2949 · JetBrains/Exposed

Vik Nikolova (vnikolova) · 2026-10-02T15:46:22Z

Description

Worked on top of the existing/generated docs from the obabichev/r2dbc-dao-docs branch

Edited and restructured the migration guide.
Add 2 new snippets projects for R2DBC DAO.
Introduce tabs for JDBC/R2DBC examples in relevant topics.
Convert the DAO topic files to MD.
Add link summaries on updated topics (shows on link hover).
Add a "What's new in Exposed 1.6.0" topic.
Use a tldr element for API links, and labels for JDBC-only/R2DBC-only features.

Note: There's a current inconsistency with how the tldr element is formatted in the DSL topics - this will be addressed post-review.

Preview on staging

Type of Change

Documentation update

Related Issues

EXPOSED-1086 Documentation for Enable usage of DAO approach with R2DBC

Documentation split out of the exposed-dao-r2dbc implementation PR (#2831) so that it can be reviewed in parallel: - Migration-Guide-DAO-JDBC-to-R2DBC.md: new guide, from swapping the dependency to the per-API differences (newSuspend, reference accessors, Flow-based referrers, attach()) - DAO-CRUD-Operations, DAO-Entity-definition, DAO-Relationships, DAO-Table-Types: R2DBC variants alongside the JDBC snippets - lib.topic: reusable experimental-preview warning with the @ExperimentalR2dbcDaoApi opt-in - hi.tree: the new guide in the migration section - Adding-dependencies.md: "Database access modules" now lists both DAO modules and warns against mixing them in one source set - README.md, exposed-version-catalog/README.md: exposed-dao-r2dbc rows, and the exposed-dao row now points at it - CLAUDE.md, .junie/guidelines.md, .claude/skills/fix-bug: the new module and its test module in the module lists and test commands The module it documents landed in main with #2831, so this no longer has to wait on that PR and can be merged on its own. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…DBC DAO snippets

…xamples

…de file name

Chantal Loncle (bog-walk) · 2026-10-07T18:25:17Z

+        <toc-element topic="dao-entity-definition.md" accepts-web-file-names="dao-field-transformations.html"/>
+        <toc-element topic="dao-crud-operations.md"/>
+        <toc-element topic="dao-relationships.md"/>
+        <toc-element topic="migrating-from-jdbc-to-r2dbc-dao.md"/>


Minor (or just opinion): I was a bit surprised to see this page in this location. Thought it would be under Releases, like the other migration guide, since it's technically attached to a release. But I can understand it being here, if that was what was requested.

That depends if the intention is to deprecate the JDBC DAO, then it would fit better under Releases. If the JDBC DAO API will remain alongside R2DBC DAO, then I believe this is the correct placement for the migration guide.

Chantal Loncle (bog-walk) · 2026-10-07T23:16:52Z

+[references](dao-relationships.md), [queries](dao-crud-operations.md), and [transactions](Transactions.md),
+with APIs adapted for suspending database operations.
+
+To use R2DBC DAO, replace the JDBC DAO dependency with `exposed-dao-r2dbc` and use the `suspendTransaction()` function 


Not sure if it's implicit/obvious that this means switching driver dependencies too.

Still don't think this is clear, especially since exposed-jdbc does actually provide suspendTransaction(). Users could easily argue that they should be able to use exposed-dao-r2dbc + exposed-jdbc/suspendTransaction.

Oleg Babichev (obabichevjb) · 2026-10-08T13:03:41Z

+
+        // returns all UserRatingWithOptionalUserEntity objects with this movie as film
+        val filmRatings = starWarsFilm.ratings
+        println(filmRatings)


It prints Flow object. Also toList() could be added on the line above

Oleg Babichev (obabichevjb) · 2026-10-08T13:29:42Z

+{style="tip"}
+
+When an update occurs, the `modified` column is populated with the current UTC time using the `nowUTC()` method. However,
+the update only happens if the `modified` field has not already been set. This is checked by using `Entity.writeValues`,


writeValues is not available in r2dbc.

the values are stored in EntityCache:

/** Uncommitted column values, kept off the entity so a rollback drops exactly what this scope staged. */ private val staged = IdentityHashMap<Entity<*>, StagedValues>()

Oleg Babichev (obabichevjb) · 2026-10-08T13:31:10Z

@@ -0,0 +1,30 @@
+package org.example.examples


Is this snipped dead code? I don't see any usages of it. Probably I'm wrong, but right now I can't find it in the docs.

Hm it indeed seems like it's no referenced anywhere..

Oleg Babichev (obabichevjb) · 2026-10-08T13:31:48Z

+in the same way you would get any other field:
+
+```kotlin
+movie.director // returns a Director object


should be movie.director(), because it's invocable now

Oleg Babichev (obabichevjb) · 2026-10-08T13:32:09Z

+You can then access this field on a `DirectorCompositeIDEntity` object, `director`:
+
+```kotlin
+director.films // returns all StarWarsFilm objects that reference this director


also should be director.films()

Vik Nikolova (vnikolova) · 2026-10-12T08:36:25Z

Thank you for the thorough reviews Chantal Loncle (@bog-walk) and Oleg Babichev (@obabichevjb) 🙏
I've applied the suggested modifications and included the remaining "what's new" entries.

Chantal Loncle (bog-walk) · 2026-10-13T18:40:23Z

+[references](dao-relationships.md), [queries](dao-crud-operations.md), and [transactions](Transactions.md),
+with APIs adapted for suspending database operations.
+
+To use R2DBC DAO, replace the JDBC DAO dependency with `exposed-dao-r2dbc` and use the `suspendTransaction()` function 


Still don't think this is clear, especially since exposed-jdbc does actually provide suspendTransaction(). Users could easily argue that they should be able to use exposed-dao-r2dbc + exposed-jdbc/suspendTransaction.

Chantal Loncle (bog-walk) · 2026-10-13T19:02:50Z

+The `.new()` function schedules the entity for insert in the transaction's cache. The insert is flushed when you 
+explicitly call the `flushCache()` function, when another statement is executed in the same transaction, or when the transaction is committed.
+
+* With JDBC, the entity's ID and any database-generated columns are available when the function returns.


Technically no, depending on how "available when the function returns" reads.

It may seem this way to a naive user, because when they access these fields, the values will be successfully returned from the entity with no issues.
But technically (and it will be obvious if the user has a logger or statement interceptor enabled) what will happen is that the insert will be (quietly-ish) flushed in order to access the returned statement's generated values.

I think this should be made clear, but we can always fix/clarify later.

Chantal Loncle (bog-walk) · 2026-10-13T19:27:24Z

+The pending inserts are flushed when required by subsequent database operations or when the transaction commits. Call
+`flushCache()` when you need to explicitly control when the pending inserts are sent to the database.
+
+> The `new()` function exists in both JDBC and R2DBC DAO but its behavior differs. During migration, review every `new{}`


Still don't agree with this. The behavior of the 2 .new() methods doesn't actually differ. It's the behavior of the property getters that truly differs. So continuing to use old new() with r2dbc would cause no issue & would act the same if the user never attempts to access id or generated values immediate after.

I'd suggest something like:

Even though the new() function exists in both JDBC and R2DBC DAO and both result in scheduled inserts, the behavior of the new entity's property getters differs. During migration, review every new() call that expects the row or its generated ID to exist immediately. Continuing to use new() in these cases will throw an exception and they should be replaced with newSuspend().

Oleg Babichev (obabichevjb) and others added 8 commits September 23, 2026 15:24

docs: EXPOSED-1086 edit the migration guide for r2dbc dao

81e867d

docs: add a new exposed-dao-r2dbc snippets project

ebd7644

docs: update the CRUD DAO topic and fix detekt issues

594da49

docs: update the DAO relationships topic and add a new project for R2…

5f94fb0

…DBC DAO snippets

docs: update entity definition, fix formatting and issues with code e…

bfb8b8b

…xamples

docs: add a what's new entry, link summaries and update migration gui…

fc0954f

…de file name

docs: fix: fix detekt issues

632b00d

Vik Nikolova (vnikolova) marked this pull request as ready for review October 7, 2026 16:27

Vik Nikolova (vnikolova) changed the title ~~docs: WIP Add docs for R2DBC DAO~~ docs: Add docs for R2DBC DAO Oct 7, 2026

Vik Nikolova (vnikolova) requested review from Chantal Loncle (bog-walk) and Oleg Babichev (obabichevjb) October 7, 2026 16:30

Chantal Loncle (bog-walk) reviewed Oct 7, 2026

View reviewed changes

Oleg Babichev (obabichevjb) requested changes Oct 8, 2026

View reviewed changes

Vik Nikolova (vnikolova) added 4 commits October 8, 2026 16:20

docs: fix: comments

344a09f

docs: fix: comments

3a2796d

Merge remote-tracking branch 'origin/main' into vnikolova/r2dbc-dao-docs

7dc08b7

docs: chore: add remaining entries into the what's new

42a308b

Chantal Loncle (bog-walk) reviewed Oct 13, 2026

View reviewed changes

Conversation

Vik Nikolova (vnikolova) commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of Change

Related Issues

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Vik Nikolova (vnikolova) commented Oct 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Vik Nikolova (vnikolova) commented Oct 2, 2026 •

edited

Loading