Voltdb-client

The voltdb-client resource configures and exposes org.voltdb.Client instance. The resource has to be added do pipeline builder when defining pipeline in java, but can be fully configured in yaml properties, see example.

public void define(VoltStreamBuilder sb) {
    // resources
    sb.configureResource(voltClientReferenceName, VoltDBResourceConfigBuilder.class);
}

Advanced users that need direct access to a VoltDB cluster do not need to configure and instantiate it manually. VoltSP uses built in mechanisms to provide a production quality setup.

User can relay on VoltSP standard configuration options to customise this resource.

As with the VoltDB flavored emitters and sinks this resource works with arrays of Object-s that correspond to stored procedure arguments. E.g. to invoke a stored procedure that has public long run(long id, int anotherId, String someString) method the Object[] should contain Long, Integer and String or compatible types as defined in the VoltDB documentation.

In case of the downstream system error this resource will retry procedure execution with exponential backoff. The details of this behaviour are configurable using retry configuration that is nested within client configuration.

Note that there are guarantees about at-lest-once delivery other than what VoltDB provides natively.

When configuring servers to connect to it is enough to provide just one server and VoltDB client will discover the whole cluster topology, including partition assignment. In yaml configuration the servers field can be provided as a comma separated string or a list of individual host:port entries.

JAVAYAML

.configureResource(VoltDBResourceConfigBuilder.builder()
    .withServers(value)
    .withClient(builder -> builder
        .withRetry(builder -> builder
            .withRetries(value)
            .withBackoffDelay(value)
            .withMaxBackoffDelay(value)
        )
        .withMaxTransactionsPerSecond(value)
        .withMaxOutstandingTransactions(value)
        .withRequestTimeout(value)
        .withAuth(builder -> builder
            .withUsername(value)
            .withPassword(value)
        )
        .withSsl(builder -> builder
            .withTrustStoreFile(value)
            .withTrustStorePassword(value)
            .withKeyStoreFile(value)
            .withKeyStorePassword(value)
            .withKeyPassword(value)
            .withInsecure(value)
            .withHostnameVerifier(value)
        )
    )
)

resource:
  voltdb-client:
    servers: value
    client:
      retry:
        retries: value
        backoffDelay: value
        maxBackoffDelay: value
      maxTransactionsPerSecond: value
      maxOutstandingTransactions: value
      requestTimeout: value
      auth:
        username: value
        password: value
      ssl:
        trustStoreFile: value
        trustStorePassword: value
        keyStoreFile: value
        keyStorePassword: value
        keyPassword: value
        insecure: value
        hostnameVerifier: value

Java dependency management

Add this declaration to your dependency management system to access the configuration DSL for this plugin in Java.

MavenGradle

<dependency>
    <groupId>org.voltdb</groupId>
    <artifactId>volt-stream-plugin-volt-api</artifactId>
    <version>1.0-20250910-124207-release-1.5.3</version>
</dependency>

implementation group: 'org.voltdb', name: 'volt-stream-plugin-volt-api', version: '1.0-20250910-124207-release-1.5.3'

Properties

servers

A set of host and port addresses for connecting to the VoltDB cluster. Only one address is sufficient for cluster topology discovery. Required.

Type: array

client

Configuration settings for the VoltDB client, including retry policies, transaction limits, and authentication credentials. Type: object

Fields of client:

client.retry

Configuration for retrying failed operations, including the number of retries and backoff delays. Type: object

Fields of client.retry:

client.retry.retries

Number of retry attempts after a request failure. Type: number

Default value: 3

client.retry.backoffDelay

Initial delay before the first retry attempt. Type: object

Default value: PT0.2S

client.retry.maxBackoffDelay

Maximum delay between consecutive retry attempts. Type: object

Default value: PT3S

client.maxTransactionsPerSecond

The maximum number of transactions allowed per second to control the rate of operations. Type: number

client.maxOutstandingTransactions

The maximum number of outstanding transactions allowed, limiting concurrent operations. Type: number

client.requestTimeout

The timeout duration for client requests to VoltDB, after which a request is considered failed. Type: object

client.auth

Client credentials for authenticating to the VoltDB cluster. Type: object

Fields of client.auth:

client.auth.username

Username used for authentication. Type: string

client.auth.password

Password used for authentication. Type: string

client.ssl

Client configuration for secure transport to the VoltDB cluster. Type: object

Fields of client.ssl:

client.ssl.trustStoreFile

Truststore file or trusted CA certificate; supported formats include JKS, PKCS#12, or PEM. Type: string

client.ssl.trustStorePassword

Truststore password. Type: string

client.ssl.keyStoreFile

Keystore file; supported formats include JKS, PKCS#12, or PEM Type: string

client.ssl.keyStorePassword

Keystore password. Type: string

client.ssl.keyPassword

Private key password. Optional — if not set, the key store password will be used. Type: string

client.ssl.insecure

If set to true, disables SSL certificate and hostname validation. Intended for debugging purposes only. Doesn't work with mTLS.

Type: boolean

client.ssl.hostnameVerifier

Custom hostname verifier for SSL connections. If not specified and 'insecure' is true, hostname verification will be disabled.

Type: object

Usage Examples

JAVAYAML

// if resource is configured in yaml
 voltStreamBuilder.configureResource("primary-cluster", VoltDBResourceConfigBuilder.class);
 // or
 voltStreamBuilder.configureResource("primary-cluster",
          VoltDBResourceConfigBuilder.class,
          new Consumer<VoltDBResourceConfigBuilder>() {
              @Override
              public void consume(VoltDBResourceConfigBuilder configurator) {
                  configurator
                    .addToServers("localhost", 12122)
                    .withClientBuilder(vcb -> builder -> {
                        builder.withMaxOutstandingTransactions(42000);
                        builder.withMaxTransactionsPerSecond(23);
                        builder.withRequestTimeout(Duration.ofSeconds(5));
                        builder.withAuthBuilder(authBuilder -> authBuilder
                           .withUsername("admin")
                           .withPassword("admin123"));
                        builder.withSslBuilder(sslBuilder -> sslBuilder
                           .withTrustStoreFile("c:/Users32/trust.me")
                           .withTrustStorePassword("got2have"));
                        builder.withRetryBuilder(retryBuilder -> retryBuilder
                           .withRetries(4)
                           .withBackoffDelay(Duration.ofSeconds(2))
                           .withMaxBackoffDelay(Duration.ofSeconds(11)));
                    })
              }
          });

resources:
    - name: primary-cluster
      voltdb-client:
        servers: "localhost:12122"
        client:
          maxTransactionsPerSecond: 3000
          maxOutstandingTransactions: 3000
          requestTimeout: PT10S
          auth:
            user: Admin
            password: 2r2Ffafw3V
          trustStore:
            file: file.pem
            password: got2have

source:
sink: