DOCS: 4.x DB Client/Data Guide

[ljamen]

Problem Description

We need to update docs for 4.x

• update dbclient.adoc for SE
• update guides/dbclient.adoc for SE

Guidelines

• Make sure any fixes from 3.x are forward ported to 4.x DOCS: SE Diffs 3.x to Main *.adoc  #7515
• Make sure any fixes from MP 3.x are forward ported to 4.x
• Initial focus is on correctness
• Record migration impact in this issue

Migration Impact

See #6991 for the initial notes and discussions on the API changes made in 4.x.
The notes below describe the bulk of the changes.

DbExecute

In 3.x the DbExecute interface was like this:

interface DbExecute {
    // factory methods are omitted
    Multi<DbRow> namedQuery(String statementName, Object... parameters);
    Multi<DbRow> query(String statement, Object... parameters);
    Single<Optional<DbRow>> namedGet(String statementName, Object... parameters);
    Single<Optional<DbRow>> get(String statement, Object... parameters);
    Single<Long> namedInsert(String statementName, Object... parameters);
    Single<Long> insert(String statement, Object... parameters);
    Single<Long> namedUpdate(String statementName, Object... parameters);
    Single<Long> update(String statement, Object... parameters);
    Single<Long> namedDelete(String statementName, Object... parameters);
    Single<Long> namedDml(String statementName, Object... parameters);
    Single<Long> dml(String statement, Object... parameters);
    <C> Single<C> unwrap(Class<C> cls);
}

In 4.x the DbExecute interface looks like this:

interface DbExecute;
    // factory methods are omitted
    Stream<DbRow> namedQuery(String statementName, Object... parameters);
    Stream<DbRow> query(String statement, Object... parameters);
    Optional<DbRow> namedGet(String statementName, Object... parameters);
    Optional<DbRow> get(String statement, Object... parameters);
    long namedInsert(String statementName, Object... parameters);
    long insert(String statement, Object... parameters);
    long namedUpdate(String statementName, Object... parameters);
    long update(String statement, Object... parameters);
    long namedDelete(String statementName, Object... parameters);
    long delete(String statement, Object... parameters);
    long namedDml(String statementName, Object... parameters);
    long dml(String statement, Object... parameters);
    <C> C unwrap(Class<C> var1);
}

The API was changed to be blocking instead of reactive:

• Single<DbRow> has been replaced with Optional<DbRow>
• Multi<DbRow> has been replaced with Stream<DbRow>
• Single<Long> has been replaced with long

In 4.x, onComplete is achieved by the next statement.

List<String> names = exec.query("SELECT * FROM names").toList();
System.out.println("done");

onError is achieved by a try-catch block:

try {
    List<String> names = exec.query("SELECT * FROM names").toList();
    System.out.println("done");
} catch (DbClientException dce) {
    // ugh-oh
}

Closing of the underlying ResultSet

Single query statements are closed right away (all methods except the ones that return Stream<DbRow>).

When operating on a Stream<DbRow> the underlying result set is closed on terminal operations, or if the underlying result set is drained.

Stream.close() can be used to manually close the underlying result set. This is not required, and if fact would reflect a mis-usage of the Stream API, E.g. a terminal operation wasn't called.

Transactions

In 3.x transactions were implemented by supplying a Function<DbTransaction, T>, changes made by the function were automatically committed at the end of the execution of the function, or automatically rolled-backed if an error occurred during the execution of the function.

E.g. A transaction In 3.x:

dbClient.inTransaction(tx -> {
    tx.namedDelete("delete-statement");
    tx.namedInsert("insert-statement");
    return 0L;
})
.onError(ex -> System.err.println("tx err: " + ex.getMessage))
.forSingle(count -> System.out.println("tx ok"));

In 4.x, inTransaction has been renamed to transaction. Transactions are not implemented with a user supplied function, instead the user is responsible for invoking commit() and rollback():

E.g. A transaction in 4.x:

DbTransaction tx = dbClient.transaction();
try {
    tx.namedDelete("delete-statement");
    tx.namedInsert("insert-statement");
    tx.commit();
} catch (Throwable t) {
    tx.rollback();
    throw t;
}

Note that both the commit() and rollback() methods are new additions to DbTransaction in 4.x:

interface DbTransaction extends DbExecute {
    void commit();
    void rollback();
}

DbClientService

In 3.x DbClientService looked like this:

interface DbClientService {
    Single<DbClientServiceContext> statement(DbClientServiceContext context);
}

Example of an implementation:

DbClientService service = context -> {
    System.out.println("Statement: " + context.statement());
    context.statementFuture().thenRun(() -> System.out.println("After statement"));
    return Single.just(context);
};

In 4.x DbClientService looks like this:

interface DbClientService {
    DbClientServiceContext statement(DbClientServiceContext context);
}

Example of an implementation:

DbClientService service = context -> {
    System.out.println("Statement: " + context.statement());
    context.statementFuture().thenRun(() -> System.out.println("After statement"));
    return context;
};