Driver Compatibility

• Java 8+ JDK

• SingleStore version 9.0+

Install the SingleStore R2DBC Connector

To install the connector using Maven, include the following dependency in the pom.xml file of your project. Replace x.x.x with the connector version you want to use.

<dependency>
	<groupId>com.singlestore</groupId>
	<artifactId>r2dbc-singlestore</artifactId>
	<version>x.x.x</version>
</dependency>

Use the SingleStore R2DBC Connector

Create a ConnectionFactory to configure the connection to your SingleStore deployment. Use either of the following methods:

• Builder API: Use SingleStoreConnectionConfiguration and SingleStoreConnectionFactory for an explicit, type-safe configuration. For example:

  Java

  Copy

  import com.singlestore.r2dbc.SingleStoreConnectionConfiguration;
  import com.singlestore.r2dbc.SingleStoreConnectionFactory;
  import io.r2dbc.spi.ConnectionFactory;
  
  SingleStoreConnectionConfiguration conf =
      SingleStoreConnectionConfiguration.builder()
          .host("<host>")
          .port(<port>)
          .username("<username>")
          .password("<password>")
          .database("<database>")
          .build();
  
  // Implementation of io.r2dbc.spi.ConnectionFactory
  ConnectionFactory factory = new SingleStoreConnectionFactory(conf);

• Connection URL: Use the standard SPI (Service Provider Interface) factory lookup and a R2DBC URL. The connection string must have the following format:

  r2dbc:singlestore:[sequential:|loadbalancing:]//<username>:<password>@<host>:<port>/[database][?connection_options=value] 

  For example:

  Java

  Copy

  import io.r2dbc.spi.ConnectionFactories;
  import io.r2dbc.spi.ConnectionFactory;
  
  ConnectionFactory factory = ConnectionFactories.get("r2dbc:singlestore://s2user:p455w04d@svchost:3306/dbTest");

Refer to Connection Options for the options supported in the connection configuration.

Failover and Load-Balancing Modes

Failover occurs when the connection to the primary host becomes unavailable and the connector tries reconnecting to another host. During failover, the failed host is blacklisted for 60 seconds. The connector always attempts to connect to the non-blacklisted hosts first. However, if all the hosts are blacklisted, the connector can retry connecting to a blacklisted host before the 60-second cooldown.

Upon failover, the connector attempts the following:

1. Connection recovery: The connector tries reconnecting to another host in the host list.

2. Re-run the command (transaction): After a connection is re-established successfully, the connector attempts to re-run the affected query. After a successful reconnection:

   • If the connector can replay the query successfully, the query is run without returning any connectivity-related errors.

   • If the connector is unable to transparently handle the failure scenario, it returns an error.

The connector supports the following load-balancing modes:

• sequential 

• loadbalancing 

Load balancing enables the connector to distribute the load across multiple hosts. While initializing a connection or after a connection failure, the connector randomly selects a host and attempts to establish a connection. Once the connection is established, all the subsequent queries are run on this host until the connection is closed or fails.

Refer to the SingleStore R2DBC Connector GitHub repository for more information.

Connection Options

Example

The following example connects to a SingleStore deployment, inserts data into a table, and then queries the data.

1. Create a Maven project.

   Shell

   Copy

   mvn archetype:generate \
     -DgroupId=com.example \
     -DartifactId=singlestore-r2dbc-demo \
     -DarchetypeArtifactId=maven-archetype-quickstart \
     -DinteractiveMode=false

2. Add the required dependencies and plugins to the pom.xml file of the project. This example includes the following:

   XML

   Copy

   <dependencies>
   	<dependency>
   		<groupId>com.singlestore</groupId>
   		<artifactId>r2dbc-singlestore</artifactId>
   		<version>1.0.0</version>
   	</dependency>
   	<!-- Reactor, used by R2DBC APIs -->
   	<dependency>
   		<groupId>io.projectreactor</groupId>
   		<artifactId>reactor-core</artifactId>
   		<version>3.6.5</version>
   	</dependency>
   	<!-- Simple logging (optional but helpful) -->
   	<dependency>
   		<groupId>org.slf4j</groupId>
   		<artifactId>slf4j-simple</artifactId>
   		<version>2.0.9</version>
   	</dependency>
   	<dependency>
   		<groupId>junit</groupId>
   		<artifactId>junit</artifactId>
   		<version>3.8.1</version>
   		<scope>test</scope>
   	</dependency>
   </dependencies>
   	
   <build>
   	<plugins>
   		<!-- Compiler plugin (already controlled by properties) -->
   		<plugin>
   			<groupId>org.apache.maven.plugins</groupId>
   			<artifactId>maven-compiler-plugin</artifactId>
   			<version>3.11.0</version>
   		</plugin>
   		<!-- To run the app via `mvn exec:java` -->
   		<plugin>
   			<groupId>org.codehaus.mojo</groupId>
   			<artifactId>exec-maven-plugin</artifactId>
   			<version>3.1.0</version>
   			<configuration>
   				<mainClass>com.example.R2dbcExample</mainClass>
   			</configuration>
   		</plugin>
   	</plugins>
   </build>

3. Create a main class. This example builds a SingleStoreConnectionConfiguration and SingleStoreConnectionFactory using the connector’s builder API.

   Java

   Copy

   package com.example;
   
   import com.singlestore.r2dbc.SingleStoreConnectionConfiguration;
   import com.singlestore.r2dbc.SingleStoreConnectionFactory;
   import io.r2dbc.spi.Connection;
   import io.r2dbc.spi.ConnectionFactory;
   import reactor.core.publisher.Flux;
   import reactor.core.publisher.Mono;
   
   public class R2dbcExample {
   
       public static void main(String[] args) {
           // 1) Configure connection (update these with your actual values)
           SingleStoreConnectionConfiguration conf =
                   SingleStoreConnectionConfiguration.builder()
                           .host("svchost")
                           .port(3306)
                           .username("s2user")
                           .password("passkey")
                           .database("dbTest")
                           .build(); // builder style
   
           // 2) Create a ConnectionFactory
           ConnectionFactory factory = new SingleStoreConnectionFactory(conf);
   
           // 3) Use R2DBC reactively: create table, insert, and query
           Mono.from(factory.create())
               .flatMapMany(connection ->
   
                   // use a helper that ensures the connection is closed
                   runExampleQueries(connection)
                       .doFinally(signal -> Mono.from(connection.close()).subscribe())
               )
               .doOnNext(rowString -> System.out.println("Row: " + rowString))
               .blockLast(); // block to keep the JVM alive for this simple demo
       }
   
       private static Flux<String> runExampleQueries(Connection connection) {
           // Simple schema + data
           String createTableSql =
                   "CREATE TABLE IF NOT EXISTS demo_r2dbc (" +
                   " id INT PRIMARY KEY, " +
                   " name VARCHAR(64)" +
                   ")";
   
           String insertSql =
                   "INSERT INTO demo_r2dbc (id, name) VALUES (1, 'Alice'), (2, 'John'), (3, 'Jane') " +
                   "ON DUPLICATE KEY UPDATE name = VALUES(name)";
   
           String selectSql = "SELECT id, name FROM demo_r2dbc";
   
           // Execute steps in sequence:
           return Mono.from(
                       connection.createStatement(createTableSql)
                                 .execute()
                   )
                   .flatMapMany(result -> result.getRowsUpdated())
                   .thenMany(
                       Mono.from(
                           connection.createStatement(insertSql)
                                     .execute()
                       ).flatMapMany(r -> r.getRowsUpdated())
                   )
                   .thenMany(
                       Mono.from(
                           connection.createStatement(selectSql)
                                     .execute()
                       )
                       .flatMapMany(result ->
                           result.map((row, meta) -> {
                               Integer id = row.get("id", Integer.class);
                               String name = row.get("name", String.class);
                               return "id=" + id + ", name=" + name;
                           })
                       )
                   );
       }
   }

   Alternatively, you can construct the ConnectionFactory with a R2DBC URL instead of the builder. For example:

   Java

   Copy

   ConnectionFactory factory =
       ConnectionFactories.get(
           "r2dbc:singlestore://s2user:password@svchost:3306/dbtest"
       );

4. Build and run the application. Run the following command from the project root directory.

   Shell

   Copy

   mvn -q clean compile exec:java

   Row: id=1, name=Alice
   Row: id=2, name=John
   Row: id=3, name=Jane

   A similar output indicates that the application ran as expected.