Batch: Transaction and Pipelining (GLIDE 2.0)

Valkey GLIDE 2.0 introduces the concept of Batch and ClusterBatch. This feature provides flexible support for both atomic batches (Transactions) and non-atomic batches (Pipelining), while ensuring easy configuration and clear, detailed examples for each scenario.

GLIDE 2.0 introduces a robust Batch API with two primary modes:

• Atomic Batch: Guarantees that all commands in a batch execute as a single, atomic unit. No other commands can interleave (similar to MULTI/EXEC).
• Non-Atomic Batch (Pipeline): Sends multiple commands in one request without atomic guarantees. Commands can span multiple slots/nodes in a cluster and do not block other operations from being processed between them.

Both modes leverage the same classes — StandaloneBatch for standalone mode and ClusterBatch for cluster mode — distinguished by an isAtomic flag. Extra configuration is provided via StandaloneBatchOptions or ClusterBatchOptions, allowing control over timeouts, routings, and retry strategies.

Key Concepts

Atomic Batch (Transaction)

• Definition: A set of commands executed together as a single, indivisible operation.
• Guarantees: Sequential execution without interruption. Other clients cannot interleave commands between the batched operations.
• Slot Constraint (Cluster Mode): When running against a cluster, all keys in an atomic batch must map to the same hash slot. Mixing keys from different slots will cause the transaction to fail.
• Underlying Valkey: Equivalent to MULTI/EXEC Valkey commands.
• Use Case: When you need consistency and isolation.
• See: Valkey Transactions.

Non-Atomic Batch (Pipeline)

• Definition: A group of commands sent in a single request, but executed without atomicity or isolation.
• Behavior: Commands may be processed on different slots/nodes (in cluster mode), and other operations from different clients may interleave during execution.
• Underlying Valkey: Similar to pipelining, minimizing round-trip latencies by sending all commands at once.
• Use Case: Bulk reads or writes where each command is independent.
• See: Valkey Pipelines.

Classes and API

StandaloneBatch

For standalone (non-cluster, cluster mode disabled) clients.

import "github.com/valkey-io/valkey-glide/go/v2/pipeline";

// Create an atomic batch (transaction)
transaction := pipeline.NewStandaloneBatch(true)
// Create a non-atomic batch (pipeline)
pipeline := pipeline.NewStandaloneBatch(false)

Note

Standalone Batches are executed on primary node.

ClusterBatch

For cluster (cluster mode enabled) clients (Mirrors StandaloneBatch but routes commands based on slot ownership, splitting into sub-pipelines if needed, Read more in Multi-Node support).

import "github.com/valkey-io/valkey-glide/go/v2/pipeline";

// Create an atomic cluster batch (must use keys mapping to same slot)
transaction := pipeline.NewClusterBatch(true)
// Create a non-atomic cluster batch (pipeline may span multiple slots)
pipeline := pipeline.NewClusterBatch(false)

Note

When isAtomic = true, all keys in the ClusterBatch must map to the same slot. Attempting to include keys from different slots will result in an exception. Read more in Multi-Node support. If the client is configured to read from replicas (PreferReplica, AzAffinity, AzAffinityReplicaAndPrimary) read commands may be routed to the replicas, in a round robin manner, if this behavior impacts your application, consider creating a dedicated client, with the desired ReadFrom configuration.

Error handling - Return an Error

Determines how errors are surfaced when calling Exec(...) and ExecWithOptions(...). It is passed directly:

// Standalone Mode
Exec(ctx context.Context, batch pipeline.StandaloneBatch, raiseOnError bool) ([]any, error)
ExecWithOptions(ctx context.Context, batch pipeline.StandaloneBatch, raiseOnError bool, options pipeline.StandaloneBatchOptions) ([]any, error)

// Cluster Mode
Exec(ctx context.Context, batch pipeline.ClusterBatch, raiseOnError bool) ([]any, error)
ExecWithOptions(ctx context.Context, batch pipeline.ClusterBatch, raiseOnError bool, options pipeline.ClusterBatchOptions) ([]any, error)

Behavior:

• raiseOnError = true: When set to true, the first encountered error within the batch (after all configured retries and redirections have been executed) is raised as a RequestException.

• raiseOnError = false:

  • When set to false, errors are returned as part of the response array rather than thrown.
  • Each failed command’s error details appear as a RequestException instance in the corresponding position of the returned []any.
  • Allows processing of both successful and failed commands together.

Example:

// Cluster pipeline with raiseOnError = false
pipeline := pipeline.NewClusterBatch(false).
  Set("key", "value").                                   // OK
  LPop("key").                                           // WRONGTYPE error (not a list)
    Rename("{non-existing-key}", "{non-existing-key}:1")   // NO SUCH KEY error
res, err := clusterClient.Exec(ctx, *pipeline, false)
fmt.Printf("Result is: %+v\n", res)
// Output: Result is: [OK WRONGTYPE: Operation against a key holding the wrong kind of value An error was signalled by the server: - ResponseError: no such key]

// Transaction with raiseOnError = true
transaction := pipeline.NewStandaloneBatch(true).
  Set("key", "value").                   // OK
  LPop("key").                           // WRONGTYPE error (not a list)
    Get("key")                             // Would be executed, but no response would be returned due to the error
res, err := client.Exec(ctx, *transaction, true)
fmt.Printf("Batch execution aborted: %+v\n", res)
// Output: Batch execution aborted: WRONGTYPE: Operation against a key holding the wrong kind of value

BatchOptions

Configuration for standalone batches.

Option	Type	Default	Description
timeout	time.Duration	Client-level request timeout (e.g., 5000 ms)	Maximum time to wait for the batch response. If exceeded, a timeout error is returned for the batch.

import "github.com/valkey-io/valkey-glide/go/v2/pipeline"

options := pipeline.NewStandaloneBatchOptions().
  WithTimeout(2 * time.Second)  // 2-second timeout

ClusterBatchOptions

Configuration for cluster batches.

Option	Type	Default	Description
timeout	time.Duration	Client’s requestTimeout	Maximum time to wait for entire cluster batch response.
retryStrategy	ClusterBatchRetryStrategy	nil (defaults to no retries)	Configures retry settings for server and connection errors. Not supported ifisAtomic = true — retry strategies only apply to non-atomic (pipeline) batches.
route	config.SingleNodeRoute	nil	Configures single-node routing for the batch request.

ClusterBatchRetryStrategy

Defines retry behavior (only for non-atomic cluster batches).

Option	Type	Default	Description
retryServerError	bool	false	Retry commands that fail with retriable server errors (e.g.TRYAGAIN). May cause out-of-order results.
retryConnectionError	bool	false	Retry entire batch on connection failures. May cause duplicate executions since server might have processed the request before failure.

import "github.com/valkey-io/valkey-glide/go/v2/pipeline"

retryStrategy := pipeline.NewClusterBatchRetryStrategy().
  WithRetryConnectionError(true).
  WithRetryServerError(true)

Note

The ClusterBatchRetryStrategy configuration is only for non-atomic cluster batches, If provided for an atomic cluster batch (a cluster transaction), an error will be returned.

Full usage

import "github.com/valkey-io/valkey-glide/go/v2/pipeline"

options := pipeline.NewStandaloneBatchOptions().
  WithTimeout(1 * time.Second).  // 1-second timeout
  WithRetryStrategy(pipeline.NewClusterBatchRetryStrategy().
    WithRetryConnectionError(true).
    WithRetryServerError(true)
  ).
  WithRoute(config.RandomRoute)

Configuration Details

Timeout

• Specifies the maximum time to wait for the batch (atomic or non-atomic) request to complete.
• If the timeout is reached before receiving all responses, the batch fails with a timeout error.
• Defaults to the client’s requestTimeout if not explicitly set.

Retry Strategies (Cluster Only, Non-Atomic Batches)

• Retry on Server Errors

  • Applies when a command fails with a retriable server error (e.g., TRYAGAIN).
  • GLIDE will automatically retry the failed command on the same node or the new master, depending on the topology update.
  • ⚠️ Caveat: Retried commands may arrive later than subsequent commands, leading to out-of-order execution if commands target the same slot.

• Retry on Connection Errors

  • If a connection error occurs, the entire batch (or sub-pipeline, Read more in Multi-Node support) is retried from the start.
  • ⚠️ Caveat: If the server received and processed some or all commands before the connection failure, retrying the batch may lead to duplicate executions.

Route (Cluster Only)

Configures single-node routing for the batch request. The client will send the batch to the specified node defined by route. If a redirection error occurs:

• For Atomic Batches (Transactions): The entire transaction will be redirected.
• For Non-Atomic Batches (Pipelines): only the commands that encountered redirection errors will be redirected.

Usage Examples

Standalone (Atomic Batch)

import (
  glide "github.com/valkey-io/valkey-glide/go/v2"
  "github.com/valkey-io/valkey-glide/go/v2/config"
  "github.com/valkey-io/valkey-glide/go/v2/pipeline"
)

// Create client configuration
clientConf := config.NewClientConfiguration().
    WithAddress(WithAddress(&config.NodeAddress{Host: "localhost", Port: 6379})

// Initialize client
client, _ := glide.NewClient(config)

// Configure batch options
options := pipeline.NewStandaloneBatchOptions().
  WithTimeout(2 * time.Second)  // 2-second timeout

// Create atomic batch
transaction := pipeline.NewStandaloneBatch(true).
    Set("account:source", "100").
    Set("account:dest", "0").
    IncrBy("account:dest", 50).
    DecrBy("account:source", 50).
    Get("account:source")

// Execute with raiseOnError = true
res, err := client.Exec(ctx, *transaction, true)
fmt.Printf("Atomic Batch Results: %+v\n", res)
// Atomic Batch Results: [OK OK 50 50 50]

Standalone (Non-Atomic Batch)

import (
  glide "github.com/valkey-io/valkey-glide/go/v2"
  "github.com/valkey-io/valkey-glide/go/v2/config"
  "github.com/valkey-io/valkey-glide/go/v2/pipeline"
)

// Create client configuration
clientConf := config.NewClientConfiguration().
    WithAddress(WithAddress(&config.NodeAddress{Host: "localhost", Port: 6379})

// Initialize client
client, _ := glide.NewClient(config)

// Configure batch options
options := pipeline.NewStandaloneBatchOptions().
  WithTimeout(2 * time.Second)  // 2-second timeout

// Create atomic batch
pipeline := pipeline.NewStandaloneBatch(false).
    Set("temp:key1", "value1").
    Set("temp:key2", "value2").
    Get("temp:key1").
    Get("temp:key2")

res, err := client.Exec(ctx, *pipeline, true)
fmt.Printf("Atomic Batch Results: %+v\n", res)
// Pipeline Results: [OK OK value1 value2]

Cluster (Atomic Batch)

import (
  glide "github.com/valkey-io/valkey-glide/go/v2"
  "github.com/valkey-io/valkey-glide/go/v2/config"
  "github.com/valkey-io/valkey-glide/go/v2/pipeline"
)

// Create client configuration
clientConf := config.NewClusterClientConfiguration().
    WithAddress(WithAddress(&config.NodeAddress{Host: "localhost", Port: 6379})

// Initialize client
client, _ := glide.NewClusterClient(config)

// Configure batch options
options := pipeline.NewClusterBatchOptions().
  WithTimeout(3 * time.Second)  // 3-second timeout

// Create atomic batch
transaction := pipeline.NewClusterBatch(true).
    Set("{user:100}:visits", "1")
    IncrBy("{user:100}:visits", 5)
    Get("{user:100}:visits")

// Execute with raiseOnError = true
res, err := client.Exec(ctx, *transaction, true)
fmt.Printf("Atomic Batch Results: %+v\n", res)
// Atomic Cluster Batch Results: [OK 6 6]

Caution

If you attempt to include keys from different slots, the batch creation will throw an exception informing you that keys must map to the same slot when isAtomic = true.

Cluster (Non-Atomic Batch / Pipeline)

import (
  glide "github.com/valkey-io/valkey-glide/go/v2"
  "github.com/valkey-io/valkey-glide/go/v2/config"
  "github.com/valkey-io/valkey-glide/go/v2/pipeline"
)

// Create client configuration
clientConf := config.NewClusterClientConfiguration().
    WithAddress(WithAddress(&config.NodeAddress{Host: "localhost", Port: 6379})

// Initialize client
client, _ := glide.NewClusterClient(config)

// Configure retry strategy and pipeline options
retryStrategy := pipeline.NewClusterBatchRetryStrategy().
  WithRetryConnectionError(true).
  WithRetryServerError(false)

options := pipeline.NewClusterBatchOptions().
  WithTimeout(5 * time.Second)  // 5-second timeout
  WithRetryStrategy(retryStrategy)

// Create pipeline spanning multiple slots
pipeline := pipeline.NewClusterBatch(false).
    Set("page:home:views", "100").
    IncrBy("page:home:views", 25).
    Get("page:home:views").
    Lpush("recent:logins", "user1").
    Lpush("recent:logins", "user2").
    Lrange("recent:logins", 0, 1)

// Execute with raiseOnError = false
res, err := client.ExecWithOptions(ctx, *pipeline, false, *options)
fmt.Printf("Pipeline Cluster Results: %+v\n", res)
// Pipeline Cluster Results: [OK 125 125 1 2 [user2 user1]]

Multi-Node Support

While atomic batches (transactions) are restricted to a single Valkey node — all commands must map to the same hash slot in cluster mode—non-atomic batches (pipelines) can span multiple nodes. This enables operations that involve keys located in different slots or even multi-node commands.

When GLIDE processes a pipeline:

1. Slot Calculation and Routing: For each key-based command (e.g., GET, SET), GLIDE computes the hash slot and determines which node owns that slot. If a command does not reference a key (e.g., INFO), it follows the command’s default request policy.
2. Grouping into Sub-Pipelines: Commands targeting the same node are grouped together into a sub-pipeline. Each sub-pipeline contains all commands destined for a specific node.
3. Dispatching Sub-Pipelines: GLIDE sends each sub-pipeline independently to its target node as a pipelined request.
4. Aggregating Responses: Once all sub-pipelines return their results, GLIDE reassembles the responses into a single array, preserving the original command order. Multi-node commands are automatically split and dispatched appropriately.

Retry Strategy in Pipelines

When errors occur during pipeline execution, GLIDE handles them efficiently and granularly — each command in the pipeline receives its own response, whether successful or not. This means pipeline execution is not all-or-nothing: some commands may succeed while others may return errors (See the ClusterBatchRetryStrategy configuration and error handling details in the classes and API section for how to handle these errors programmatically).

GLIDE distinguishes between different types of errors and handles them as follows:

• Redirection Errors (e.g., MOVED or ASK): These are always handled automatically. GLIDE will update the topology map if needed and redirect the command to the appropriate node, regardless of the retry configuration.
• Retriable Server Errors (e.g., TRYAGAIN): If the retryServerError option is enabled in the batch’s retry strategy, GLIDE will retry commands that fail with retriable server errors. ⚠️ Retrying may cause out-of-order execution for commands targeting the same slot.
• Connection Errors: If the retryConnectionError option is enabled, GLIDE will retry the batch if a connection failure occurs. ⚠️ Retrying after a connection error may result in duplicate executions, since the server might have already received and processed the request before the error occurred.

Retry strategies are currently supported only for non-atomic (pipeline) cluster batches. You can configure these using the ClusterBatchRetryStrategy options:

• retryServerError: Retry on server errors.
• retryConnectionError: Retry on connection failures.

Example Scenario:

Suppose you issue the following commands:

MGET key {key}:1
SET key "value"

When keys are empty, the result is expected to be:

[null, null]
OK

However, suppose the slot of key is migrating. In this case, both commands will return an ASK error and be redirected. Upon ASK redirection, a multi-key command (like MGET) may return a TRYAGAIN error (triggering a retry), while the SET command succeeds immediately. This can result in an unintended reordering of commands if the first command is retried after the slot stabilizes:

["value", null]
OK