Skip to content

Valkey

Since v0.33.0

Introduction

The Testcontainers module for Valkey.

Adding this module to your project dependencies

Please run the following command to add the Valkey module to your Go dependencies:

go get github.com/testcontainers/testcontainers-go/modules/valkey

Usage example

ctx := context.Background()

valkeyContainer, err := tcvalkey.Run(ctx,
    "valkey/valkey:7.2.5",
    tcvalkey.WithSnapshotting(10, 1),
    tcvalkey.WithLogLevel(tcvalkey.LogLevelVerbose),
    tcvalkey.WithConfigFile(filepath.Join("testdata", "valkey7.conf")),
)
defer func() {
    if err := testcontainers.TerminateContainer(valkeyContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

Module Reference

Run function

Info

The RunContainer(ctx, opts...) function is deprecated and will be removed in the next major release of Testcontainers for Go.

The Valkey module exposes one entrypoint function to create the Valkey container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ValkeyContainer, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "valkey/valkey:7.2.5").

Container Options

When starting the Valkey container, you can pass options in a variadic way to configure it.

Snapshotting

By default Valkey saves snapshots of the dataset on disk, in a binary file called dump.rdb. You can configure Valkey to have it save the dataset every N seconds if there are at least M changes in the dataset. E.g. WithSnapshotting(10, 1).

Log Level

You can easily set the valkey logging level. E.g. WithLogLevel(LogLevelDebug).

Valkey configuration

In the case you have a custom config file for Valkey, it's possible to copy that file into the container before it's started. E.g. WithConfigFile(filepath.Join("testdata", "valkey.conf")).

WithTLS

  • Not available until the next release main

In the case you want to enable TLS for the Valkey container, you can use the WithTLS() option. This options enables TLS on the 6379/tcp port and uses a secure URL (e.g. rediss://host:port).

Info

In case you want to use Non-mutual TLS (i.e. client authentication is not required), you can customize the CMD arguments by using the WithCmdArgs option. E.g. WithCmdArgs("--tls-auth-clients", "no").

The module automatically generates three certificates, a CA certificate, a client certificate and a Valkey certificate. Please use the TLSConfig() container method to get the TLS configuration and use it to configure the Valkey client. See more details in the TLSConfig section.

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Container Methods

The Valkey container exposes the following methods:

ConnectionString

This method returns the connection string to connect to the Valkey container, using the default 6379 port.

uri, err := valkeyContainer.ConnectionString(ctx)

TLSConfig

  • Not available until the next release main

This method returns the TLS configuration for the Valkey container, nil if TLS is not enabled.

options.TLSConfig = valkeyContainer.TLSConfig()

In the above example, the options are used to configure a Valkey client with TLS enabled.