org.springframework.r2dbc.core

## Interface DatabaseClient

- All Superinterfaces:
    ConnectionAccessor

      public interface DatabaseClient
      extends ConnectionAccessor

  A non-blocking, reactive client for performing database calls with Reactive Streams back pressure. Provides a higher level, common API over R2DBC client libraries. Propagates `DataAccessException` variants for errors.

  Use one of the static factory methods `create(ConnectionFactory)` or obtain a `builder()` to create an instance. Usage example:

       ConnectionFactory factory = …

       DatabaseClient client = DatabaseClient.create(factory);
       Mono<Actor> actor = client.sql("select first_name, last_name from t_actor")
           .map(row -> new Actor(row.get("first_name", String.class),
                row.get("last_name", String.class)))
           .first();

  Since:
    5.3
  Author:
    Mark Paluch

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `DatabaseClient.Builder` A mutable builder for creating a `DatabaseClient`.
    `static interface` | `DatabaseClient.GenericExecuteSpec` Contract for specifying an SQL call along with options leading to the execution.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `static DatabaseClient.Builder` | `builder()` Obtain a `DatabaseClient` builder.
    `static DatabaseClient` | `create(io.r2dbc.spi.ConnectionFactory factory)` Create a `DatabaseClient` that will use the provided `ConnectionFactory`.
    `io.r2dbc.spi.ConnectionFactory` | `getConnectionFactory()` Return the `ConnectionFactory` that this client uses.
    `DatabaseClient.GenericExecuteSpec` | `sql(String sql)` Specify a static `sql` statement to run.
    `DatabaseClient.GenericExecuteSpec` | `sql(Supplier<String> sqlSupplier)` Specify a `SQL supplier` that provides SQL to run.

    - ### Methods inherited from interface org.springframework.r2dbc.core.ConnectionAccessor

      `inConnection, inConnectionMany`

- - ### Method Detail

    - #### getConnectionFactory

          io.r2dbc.spi.ConnectionFactory getConnectionFactory()

      Return the `ConnectionFactory` that this client uses.
      Returns:
        the connection factory

    - #### sql

          DatabaseClient.GenericExecuteSpec sql(String sql)

      Specify a static `sql` statement to run. Contract for specifying a SQL call along with options leading to the execution. The SQL string can contain either native parameter bind markers or named parameters (e.g. :foo, :bar) when `NamedParameterExpander` is enabled.
      Parameters:
        `sql` - the SQL statement
      Returns:
        a new `DatabaseClient.GenericExecuteSpec`
      See Also:
        `NamedParameterExpander`, `DatabaseClient.Builder.namedParameters(boolean)`

    - #### sql

          DatabaseClient.GenericExecuteSpec sql(Supplier<String> sqlSupplier)

      Specify a `SQL supplier` that provides SQL to run. Contract for specifying an SQL call along with options leading to the execution. The SQL string can contain either native parameter bind markers or named parameters (e.g. :foo, :bar) when `NamedParameterExpander` is enabled.

      Accepts `PreparedOperation` as SQL and binding `Supplier`.

      `DatabaseClient` implementations should defer the resolution of the SQL string as much as possible, ideally up to the point where a `Subscription` happens. This is the case for the default implementation.

      Parameters:
        `sqlSupplier` - a supplier for the SQL statement
      Returns:
        a new `DatabaseClient.GenericExecuteSpec`
      See Also:
        `NamedParameterExpander`, `DatabaseClient.Builder.namedParameters(boolean)`, `PreparedOperation`

    - #### create

          static DatabaseClient create(io.r2dbc.spi.ConnectionFactory factory)

      Create a `DatabaseClient` that will use the provided `ConnectionFactory`.
      Parameters:
        `factory` - the `ConnectionFactory` to use for obtaining connections
      Returns:
        a new `DatabaseClient`. Guaranteed to be not `null`.

    - #### builder

          static DatabaseClient.Builder builder()

      Obtain a `DatabaseClient` builder.