### Build with Maven

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Build the rxjava2-jdbc project using Maven. This command cleans the project and installs it locally.

```bash
mvn clean install
```

--------------------------------

### Select Query Example

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Execute a select query to retrieve names from the 'person' table and print them to the console. Uses blockingForEach for demonstration.

```java
Database db = Database.test();
db.select("select name from person")
  .getAs(String.class)
  .blockingForEach(System.out::println);
```

--------------------------------

### Insert BLOB with byte array

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Shows how to insert binary data into a BLOB column using a byte array. The example prepares the statement and binds the byte array parameter.

```Java
byte[] bytes = ...
Flowable<Integer> count = db
  .update("insert into person_blob(name,document) values(?,?)")
  .parameters("FRED", Database.blob(bytes))
  .count();
```

--------------------------------

### Transaction Example: Two Selects

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Illustrates using transactions with rxjava2-jdbc. This example performs two select statements within a single transaction, automatically committing or rolling back.

```Java
Database.test()
  .select("select score from person where name=?") 
  .parameters("FRED", "JOSEPH") 
  .transacted() 
  .getAs(Integer.class) 
  .blockingForEach(tx -> 
    System.out.println(tx.isComplete() ? "complete" : tx.value()));
```

--------------------------------

### Configure Non-blocking Connection Pool

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Provides a detailed example of configuring a non-blocking connection pool with various options like idle time, health checks, retry intervals, and maximum pool size.

```java
Database db = Database
  .nonBlocking()
  // the jdbc url of the connections to be placed in the pool
  .url(url)
  // an unused connection will be closed after thirty minutes
  .maxIdleTime(30, TimeUnit.MINUTES)
  // connections are checked for healthiness on checkout if the connection 
  // has been idle for at least 5 seconds
  .healthCheck(DatabaseType.ORACLE)
  .idleTimeBeforeHealthCheck(5, TimeUnit.SECONDS)
  // if a connection fails creation then retry after 30 seconds
  .createRetryInterval(30, TimeUnit.SECONDS)
  // the maximum number of connections in the pool
  .maxPoolSize(3)
  .build();
```

--------------------------------

### Callable Statement API

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Provides a comprehensive overview of the `call` API for executing stored procedures. It details how to define input parameters, output parameters with specific types, and how to handle multiple result sets using methods like `autoMap` and `getAs`. Examples cover different return types and result set processing.

```APIDOC
Database.call(String sql)
  - Initiates the execution of a stored procedure or SQL statement.
  - Parameters:
    - sql: The SQL statement or procedure call string (e.g., "call my_proc(?,?)").

CallableBuilder.in()
  - Marks the start of defining input parameters.

CallableBuilder.out(Type type, Class<T> cls)
  - Defines an output parameter for a stored procedure.
  - Parameters:
    - type: The JDBC type of the output parameter (e.g., Type.INTEGER, Type.VARCHAR).
    - cls: The Java class to which the output parameter should be mapped.
  - Returns: The CallableBuilder instance for chaining.

CallableBuilder.autoMap(Class<T> cls)
  - Maps an output ResultSet to a Java object using automatic mapping.
  - Parameters:
    - cls: The Java class to map the ResultSet rows to.
  - Returns: The CallableBuilder instance for chaining.

CallableBuilder.getAs(Class<T> cls)
  - Maps an output ResultSet to a Java object using automatic mapping, similar to autoMap.
  - Parameters:
    - cls: The Java class to map the ResultSet rows to.
  - Returns: The CallableBuilder instance for chaining.

CallableBuilder.getAs(Class<T1> cls1, Class<T2> cls2, ...)
  - Maps an output ResultSet to a Tuple of specified Java types.
  - Parameters:
    - cls1, cls2, ...: The Java classes for each column in the ResultSet.
  - Returns: The CallableBuilder instance for chaining.

CallableBuilder.input(Object... values)
  - Provides the values for the input parameters defined earlier.
  - Parameters:
    - values: An array of objects corresponding to the input parameters in order.
  - Returns: A Flowable or Single emitting the results of the call.

CallableResult.results1()
  - Accesses the first output ResultSet from a stored procedure call.
  - Returns: A Flowable of mapped objects or tuples.

CallableResult.results2()
  - Accesses the second output ResultSet from a stored procedure call.
  - Returns: A Flowable of mapped objects or tuples.

Example Usage:
// Callable with IN and OUT parameters
Flowable<Tuple2<Integer,Integer>> tuples = 
  db.call("call in1out2(?,?,?)") 
    .in()
    .out(Type.INTEGER, Integer.class)
    .out(Type.INTEGER, Integer.class)
    .input(0, 10, 20);

// Callable with ResultSets and autoMap
Flowable<String> namePairs = 
  db
    .call("call in1out0rs2(?)")
    .in()
    .autoMap(Person2.class)
    .autoMap(Person2.class)
    .input(0, 10, 20)
    .flatMap(x -> 
      x.results1()
       .zipWith(x.results2(), (y, z) -> y.name() + z.name()));

// Callable with ResultSets and getAs
Flowable<String> namePairs = 
  db
    .call("call in1out0rs2(?)")
    .in()
    .getAs(String.class, Integer.class)
    .getAs(String.class, Integer.class)
    .input(0, 10, 20)
    .flatMap(x -> 
      x.results1()
       .zipWith(x.results2(), (y, z) -> y._1() + z._1()));
```

--------------------------------

### Using Annotated Interface with Direct Getter

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

An alternative way to execute queries defined within annotated interfaces, using a `get` overload that accepts a method reference to directly extract a specific property from the mapped results.

```java
Database
  .test()
  .select(Person.class)
  .get(Person::name)
  .blockingForEach(System.out::println);
```

--------------------------------

### Database Instance Creation for Test

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Create a Database instance using the built-in test database. This provides a fresh database with pre-loaded data for each call.

```java
Database db = Database.test(maxPoolSize);
```

--------------------------------

### Database Instance Creation from URL

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Create a Database instance by providing the JDBC URL and the maximum pool size for database connections.

```java
Database db = Database.from(url, maxPoolSize);
```

--------------------------------

### Create Database with Non-blocking Pool (Simple)

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates the simplest way to create a Database instance using a non-blocking connection pool with a specified JDBC URL and maximum pool size.

```java
Database db = Database.from(url, maxPoolSize);
```

--------------------------------

### SQL with Anonymous Parameter Syntax

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Illustrates the standard JDBC syntax for anonymous parameters in SQL queries, using a question mark placeholder.

```sql
select name from person where name=?
```

--------------------------------

### Create Database with Non-blocking Pool (Test)

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Shows how to create a Database instance using the built-in in-memory test database with a non-blocking connection pool. Requires Apache Derby dependency.

```java
Database db = Database.test(maxPoolSize);
```

--------------------------------

### Insert CLOB with Reader

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates inserting data into a CLOB column using a java.io.Reader. It shows how to prepare the statement, bind parameters, and execute the update.

```Java
Reader reader = ...;
Flowable<Integer> count = db
  .update("insert into person_clob(name,document) values(?,?)")
  .parameters("FRED", reader)
  .count();
```

--------------------------------

### SQL with Named Parameter Syntax

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Shows the syntax for using named parameters in SQL queries, prefixed with a colon, as supported by rxjava2-jdbc.

```sql
select name from person where name=:name
```

--------------------------------

### Update with Named Parameters

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates updating a database record using named parameters and RxJava2. It shows how to bind values to parameters specified with colons in the SQL statement.

```java
Database.test()
  .update("update person set date_of_birth = :dob") 
  .parameter(Parameter.create("dob", null))
  .counts()
  .blockingForEach(System.out::println);
```

--------------------------------

### Automap with Basic Usage

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Uses the `autoMap` method to map result set values to an interface (`Person.class`) and RxJava2 testing methods to assert the retrieved data. It demonstrates fetching and verifying a single value.

```java
Database db = Database.test();
db.select("select name, score from person order by name")
  .autoMap(Person.class)
  .doOnNext(System.out::println)
  .firstOrError()
  .map(Person::score) 
  .test()
  .assertValue(21) 
  .assertComplete();
```

--------------------------------

### Raw JDBC Connection Access with apply

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates how to access the underlying JDBC `Connection` object for custom operations not directly supported by rxjava2-jdbc. The `apply` method allows executing a lambda that receives the connection and returns a result.

```java
Database db = ...;
Single<Integer> count = db.apply(
  con -> {
    // do whatever you want with the connection
    // just don't close it!
    return con.getHoldability();
  });
```

```java
Database db = ...;
Completable c = db.apply(con -> {
  // do whatever you want with the connection
});
```

--------------------------------

### Maven Dependency Apache Derby

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Add the Apache Derby dependency, which is required if you intend to use the built-in test database functionality provided by rxjava2-jdbc.

```xml
<dependency>
  <groupId>org.apache.derby</groupId>
  <artifactId>derby</artifactId>
  <version>10.14.2.0</version>
</dependency>
```

--------------------------------

### Transactional Database Operations with RxJava 2

Source: https://github.com/davidmoten/rxjava2-jdbc/wiki/Home

Demonstrates how to use transactions across asynchronous boundaries by passing a `Tx` object. It shows chaining database operations within the same transaction, handling results, and managing transaction termination.

```java
    // use a new transaction for the select/update
    db.transacted()
      .select("select name from person where score > 1")
      // filter out valueless terminal Tx<String> emissions
      .valuesOnly()
      // return the query results as Flowable<Tx<String>>
      .getAs(String.class)
      // for each value
      .flatMap(tx -> 
          tx.select("select name, score from person where name=:name")
            .parameter("name", tx.value())
            .getAs(String.class, Number.class)
            // not going to pass the transaction on further
            // so let's make life simple by dealing only with 
            // the values from the select query
            .flatMap(Tx.TO_VALUE)
            .doOnNext(System.out::println)
            // on termination will decrement Tx counter
            // cross an asynchronous boundary at subscribe time!
            .subscribeOn(Schedulers.io())
       )
      // note that on termination will decrement Tx counter
      // and if 0 will commit/rollback as appropriate 
      .subscribe();
```

--------------------------------

### Automap with Column Indexing

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Shows how to map interface methods to columns based on their 1-based position in the result set using the `@Index` annotation, allowing mapping without relying on column names.

```java
interface Person {
  @Index(1)
  String fullName();

  @Index(2)
  int examScore();
}
```

--------------------------------

### Return Generated Keys

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates how to retrieve auto-generated keys after an insert operation. The `returnGeneratedKeys()` method is used to enable this feature.

```Java
Flowable<Integer> keys = 
    db.update("insert into note(text) values(?)")
      .parameters("hello", "there")
      .returnGeneratedKeys()
      .getAs(Integer.class);
```

--------------------------------

### Kotlin Interface Annotation for SQL Queries

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates how to annotate a Kotlin interface with `@Query` and `@Column` to map SQL results to interface methods, enabling type-safe data retrieval.

```kotlin
@Query("select name from person order by name")
interface Person {
    @Column("name")
    fun nm() : String
}
```

--------------------------------

### Read BLOB as InputStream

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Shows how to fetch BLOB data and receive it as an InputStream. This allows for efficient streaming of binary data.

```Java
Flowable<InputStream> document = 
  db.select("select document from person_clob")
    .getAs(InputStream.class);
```

--------------------------------

### Automap with Column Renaming

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Illustrates how to map interface method names to column names that differ using the `@Column` annotation with a specified column name, handling case and underscore differences.

```java
interface Person {
  @Column("name")
  String fullName();

  @Column("score")
  int examScore();
}
```

--------------------------------

### Using Annotated Interface for Queries

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Shows how to execute a query defined within an annotated interface (`Person.class`) using RxJava2. It retrieves and prints the `name` property from the mapped results.

```java
Database
  .test()
  .select(Person.class)
  .get()
  .map(Person::name)
  .blockingForEach(System.out::println);
```

--------------------------------

### Update with Parameter Stream

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Shows how to update a database record using a stream of parameters, handling nulls carefully with RxJava2. This method is suitable when dealing with sequences of updates or dynamic parameter sets.

```java
Database.test()
  .update("update person set date_of_birth = ?") 
  .parameterStream(Flowable.just(Parameter.NULL))
  .counts()
  .blockingForEach(System.out::println);
```

--------------------------------

### Demonstrate Non-blocking Pool Behavior

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Illustrates the non-blocking nature of the connection pool by running two queries concurrently on a pool of size 1. The second query waits for the first to release a connection.

```java
// create database with non-blocking connection pool 
// of size 1
Database db = Database.test(1); 

// start a slow query
db.select("select score from person where name=?") 
  .parameter("FRED") 
  .getAs(Integer.class) 
   // slow things down by sleeping
  .doOnNext(x -> Thread.sleep(1000)) 
   // run in background thread
  .subscribeOn(Schedulers.io()) 
  .subscribe();

// ensure that query starts
Thread.sleep(100);

// query again while first query running
db.select("select score from person where name=?") 
  .parameter("FRED") 
  .getAs(Integer.class) 
  .doOnNext(x -> System.out.println("emitted on " + Thread.currentThread().getName())) 
  .subscribe();

System.out.println("second query submitted");

// wait for stuff to happen asynchronously
Thread.sleep(5000);
```

--------------------------------

### Read CLOB as String

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Illustrates how to retrieve data from a CLOB column and map it directly to a String. This is useful for text-based CLOB content.

```Java
Flowable<String> document = 
  db.select("select document from person_clob")
    .getAs(String.class);
```

--------------------------------

### Read CLOB as Reader

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates retrieving CLOB data and receiving it as a java.io.Reader. This is suitable for processing large text data streams.

```Java
Flowable<Reader> document = 
  db.select("select document from person_clob")
    .getAs(Reader.class);
```

--------------------------------

### Raw JDBC Connection Access with member()

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Provides lower-level access to the JDBC `Connection` via `db.member()`. This method returns a `Member` object that wraps the connection and requires manual check-in after use. It's suitable for operations where you need to manage the connection lifecycle explicitly.

```java
Database db = ...;
Single<Integer> count = db.member()
  .map(member -> {
    Connection con = member.value();
    try {
      // do whatever you want with the connection
      return count;
    } finally {
      // don't close the connection, just hand it back to the pool
      // and don't use this member again!
      member.checkin();
    }
  });
```

```java
Database db = ...;
Completable completable = db.member()
  .doOnSuccess(member -> {
    Connection con = member.value();
    try {
      // do whatever you want with the connection
    } finally {
      // don't close the connection, just hand it back to the pool
      // and don't use this member again!
      member.checkin();
    }
  }).ignoreElements();
```

--------------------------------

### Select with Tuple Support

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Retrieves data and maps it into a `Tuple2` object, combining multiple column types from the result set using RxJava2. This is useful when you need to group related columns into a single object without defining a full POJO.

```java
Database db = Database.test();
db.select("select name, score from person")
  .getAs(String.class, Integer.class)
  .blockingForEach(System.out::println);
```

--------------------------------

### Maven Dependency rxjava2-jdbc

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Add the rxjava2-jdbc library as a Maven dependency to your project.

```xml
<dependency>
  <groupId>com.github.davidmoten</groupId>
  <artifactId>rxjava2-jdbc</artifactId>
  <version>VERSION_HERE</version>
</dependency>
```

--------------------------------

### Handle Nullable CLOB Data

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates how to handle nullable CLOB data by using the Database.clob() method when inserting a potentially null String value into a CLOB column.

```java
String document = ...;
Flowable<Integer> count = db
  .update("insert into person_clob(name,document) values(?,?)")
  .parameters("FRED", Database.clob(document))
  .count();
```

--------------------------------

### Manual Row Mapping

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Maps each JDBC ResultSet row to a custom `Person` object using a lambda expression with RxJava2. This provides fine-grained control over object creation from raw result set data.

```java
Database db = Database.test();
db.select("select name, score from person order by name")
  .get(rs -> new Person(rs.getString("name"), rs.getInt("score")))
  .doOnNext(System.out::println) //
  .subscribe();
```

--------------------------------

### Automap with Annotated Query

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates defining the select query directly within the automapped interface using the `@Query` annotation. This allows the query to be associated with the mapping interface itself.

```java
@Query("select name, score from person order by name")
interface Person {
   @Column
   String name();

   @Column
   int score();
}
```

--------------------------------

### Read Null CLOB as Optional

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Explains how to safely retrieve CLOB data that might be NULL using `getAsOptional`. This prevents NullPointerExceptions when the CLOB value is absent.

```Java
db.select("select document from person_clob where name='FRED'")
  .getAsOptional(String.class)
```

--------------------------------

### Passing Null Parameters

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates how to pass an explicit null value as a parameter in an update statement.

```java
Database.test()
  .update("update person set date_of_birth = ?") 
  .parameter(null)
  .counts()
  .blockingForEach(System.out::println);
```

--------------------------------

### Handling Nullable Columns with Optional

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Retrieve a nullable column ('date_of_birth') and map it to a Java Optional. This is the recommended way to handle single nullable columns.

```java
Database.test() 
  .select("select date_of_birth from person where name='FRED'")
  .getAsOptional(Instant.class)
  .blockingForEach(System.out::println);
```

--------------------------------

### Insert Null CLOB

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Shows two methods for inserting a NULL value into a CLOB column: using Database.NULL_CLOB or Database.clob(null). Both achieve the same result of storing a null CLOB.

```Java
Flowable<Integer> count = db
  .update("insert into person_clob(name,document) values(?,?)")
  .parameters("FRED", Database.NULL_CLOB)
  .count();
```

```Java
Flowable<Integer> count = db
  .update("insert into person_clob(name,document) values(?,?)")
  .parameters("FRED", Database.clob(null))
  .count();
```

--------------------------------

### Insert Null BLOB

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates inserting a NULL value into a BLOB column. It shows two methods: using Database.NULL_BLOB or Database.blob(null) for this purpose.

```Java
Flowable<Integer> count = db
  .update("insert into person_blob(name,document) values(?,?)")
  .parameters("FRED", Database.NULL_BLOB)
  .count();
```

```Java
Flowable<Integer> count = db
  .update("insert into person_clob(name,document) values(?,?)")
  .parameters("FRED", Database.blob(null))
  .count();
```

--------------------------------

### Tx Interface and Transaction API

Source: https://github.com/davidmoten/rxjava2-jdbc/wiki/Home

Defines the Transaction object (`Tx`) for managing database transactions across asynchronous boundaries in rxjava2-jdbc. It provides methods to access the underlying connection, execute SQL statements within the transaction, and manage transaction lifecycle (commit/rollback).

```APIDOC
Tx Interface:
  Represents a transaction context that can be passed across asynchronous boundaries.

  Methods:
    isValue(): boolean
      - Returns true if the Tx contains a value.
    isComplete(): boolean
      - Returns true if the Tx has completed (either with a value or error).
    isError(): boolean
      - Returns true if the Tx encountered an error.
    value(): T
      - Returns the value contained within the Tx.
    throwable(): Throwable
      - Returns the Throwable if an error occurred.
    connection(): Connection
      - Returns the underlying database Connection associated with this transaction.
    select(String sql): SelectBuilder
      - Creates a SelectBuilder for executing a SQL query within this transaction.
    commit(): void
      - Commits the transaction.
    rollback(): void
      - Rolls back the transaction.

  Example Usage (within a stream):
    tx.select("sql query").parameter("name", "value").getAs(String.class)
      .flatMap(Tx.TO_VALUE) // Helper to extract value from Tx<String>
      .subscribe();
```

--------------------------------

### Automap Interface Definition

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Defines an interface `Person` with `@Column` annotations for automatic mapping of result set columns to object properties using RxJava2. This simplifies data mapping by convention.

```java
interface Person {
  @Column
  String name();

  @Column
  int score();
}
```

--------------------------------

### Read BLOB as byte array

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Illustrates retrieving BLOB data and mapping it to a byte array. This is suitable for handling binary content like images or files.

```Java
Flowable<byte[]> document = 
  db.select("select document from person_clob")
    .getAs(byte[].class);
```

--------------------------------

### Insert CLOB Data

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Shows how to insert a String value into a CLOB column using an update statement with parameters. Assumes the 'document' column is of type CLOB.

```java
String document = ...;
Flowable<Integer> count = db
  .update("insert into person_clob(name,document) values(?,?)")
  .parameters("FRED", document)
  .count();
```

--------------------------------

### Transactional Update with Values Only

Source: https://github.com/davidmoten/rxjava2-jdbc/blob/master/README.adoc

Demonstrates updating a record within a transaction, retrieving only the count of affected rows, and processing the result. It uses `valuesOnly()` to skip returning the updated row data.

```java
db.transactedValuesOnly()
  .getAs(String.class)
  .flatMap(tx -> tx
    .update("update person set score=-1 where name=:name")
    .parameter("name", tx.value())
    .valuesOnly()
    .counts())
  .toList()
  .blockingForEach(System.out::println);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.