Skip to content

CockroachDB

Since v0.28.0

Introduction

The Testcontainers module for CockroachDB.

Adding this module to your project dependencies

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

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

Usage example

ctx := context.Background()

cockroachdbContainer, err := cockroachdb.Run(ctx, "cockroachdb/cockroach:latest-v23.1")
defer func() {
    if err := testcontainers.TerminateContainer(cockroachdbContainer); 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 CockroachDB module exposes one entrypoint function to create the CockroachDB container, and this function receives three parameters:

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

Container Options

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

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "cockroachdb/cockroach:latest-v23.1").

Database

Set the database that is created & dialled with cockroachdb.WithDatabase.

User and Password

You can configure the container to create a user with a password by setting cockroachdb.WithUser and cockroachdb.WithPassword.

cockroachdb.WithPassword is incompatible with cockroachdb.WithInsecure.

Store size

Control the maximum amount of memory used for storage, by default this is 100% but can be changed by provided a valid option to WithStoreSize. Checkout https://www.cockroachlabs.com/docs/stable/cockroach-start#store for the full range of options available.

TLS authentication

cockroachdb.WithInsecure lets you disable the use of TLS on connections.

cockroachdb.WithInsecure is incompatible with cockroachdb.WithPassword.

Initialization Scripts

cockroachdb.WithInitScripts adds the given scripts to those automatically run when the container starts. These will be ignored if data exists in the /cockroach/cockroach-data directory within the container.

No Cluster Defaults

cockroachdb.WithNoClusterDefaults disables the default cluster settings script.

Without this option Cockroach containers run data/cluster-defaults.sql on startup which configures the settings recommended by Cockroach Labs for local testing clusters unless data exists in the /cockroach/cockroach-data directory within the container.

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 CockroachDB container exposes the following methods:

ConnectionString

Dial address to open a new connection.

MustConnectionString

Same as ConnectionString but any error to generate the address will raise a panic

TLSConfig

Returns *tls.Config setup to allow you to dial your client over TLS, if enabled, else this will error with cockroachdb.ErrTLSNotEnabled.

Info

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

ConnectionConfig

Returns *pgx.ConnConfig which can be passed to pgx.ConnectConfig to open a new connection.