R2DBC.io initial example should properly manage resources

[lukaseder]

Feature Request

Is your feature request related to a problem? Please describe

It is not immediately obvious to new users how to best manage resources with R2DBC, see e.g. my previous message:
https://groups.google.com/g/r2dbc/c/a7CQAU_u_m0

The example on the website is no help either, as it produces a resources leak:
https://r2dbc.io

The Connection is never closed:

ConnectionFactory connectionFactory = ConnectionFactories
  .get("r2dbc:h2:mem:///testdb");

Mono.from(connectionFactory.create())
  .flatMapMany(connection -> connection
    .createStatement("SELECT firstname FROM PERSON WHERE age > $1")
    .bind("$1", 42)
    .execute())
  .flatMap(result -> result
    .map((row, rowMetadata) -> row.get("firstname", String.class)))
  .doOnNext(System.out::println)
  .subscribe();

The same problem in https://github.com/r2dbc/r2dbc-pool/blob/main/README.md, where the resource is closed, but it is left as an exercise to the reader how to actually do that in a reactive stream:

// later

Connection connection = …;
Mono<Void> release = connection.close(); // released the connection back to the pool

Given the trouble discussed in the mailing list, e.g. when intercepting cancel events, too, I think this is quite the pitfall for new users evaluating R2DBC.

Describe the solution you'd like

I'd love to see resource management examples on at least:

• https://r2dbc.io
• https://github.com/r2dbc/r2dbc-pool/blob/main/README.md

I'd love to provide a PR, but I don't feel I'll produce the correct solution yet, using reactor or Rx or other APIs. The groups discussion above hinted at using usingWhen, perhaps similar to this change here in the oracle driver?
r2dbc/r2dbc-spi@e8de1bc

Alternatively, the r2dbc.io homepage example could avoid using a pool, in case of which resource management is out of scope for the example. But I still think that this very important question should be answered very early on when someone looks at R2DBC for the first time.

[mp911de]

The example code leaves the resources open. Right now, only Project Reactor provides a somewhat simple approach to mitigate that issue with usingWhen. RxJava requires additional code that would deprive the sample of its brevity and I'm not sure whether Mutiny provides something in that regard.

[lukaseder]

The usingWhen syntax is certainly acceptable.

I understand that brevity is desirable. One could argue that users of reactive streams are used to the excessive clutter their streaming infrastructure causes in their code-bases, and the existing examples aren't really that brief to begin with, so I think there's something of a tradeoff to be made here.

Granted, on the r2dbc.io homepage, the tradeoff is in favour of less noise. But the r2dbc-pool should really show an example of how to do it right, IMO

[mp911de]

Fixed the pool documentation via r2dbc/r2dbc-pool#161.