cockroachdb

Documentation

Index

• Variables
• func WithDatabase(database string) testcontainers.CustomizeRequestOption
• func WithInitScripts(scripts ...string) testcontainers.CustomizeRequestOption
• func WithInsecure() testcontainers.CustomizeRequestOption
• func WithNoClusterDefaults() testcontainers.CustomizeRequestOption
• func WithPassword(password string) testcontainers.CustomizeRequestOption
• func WithStoreSize(size string) testcontainers.CustomizeRequestOption
• func WithUser(user string) testcontainers.CustomizeRequestOption
• type CockroachDBContainer
  • func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*CockroachDBContainer, error)
  • func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*CockroachDBContainer, error)
  • func (c *CockroachDBContainer) ConnectionConfig(ctx context.Context) (*pgx.ConnConfig, error)
  • func (c *CockroachDBContainer) ConnectionString(ctx context.Context) (string, error)
  • func (c *CockroachDBContainer) MustConnectionString(ctx context.Context) string
  • func (c *CockroachDBContainer) TLSConfig() (*tls.Config, error)

Examples

• Run
• Run (WithInitOptions)

Variables

var ErrTLSNotEnabled = errors.New("tls not enabled")

ErrTLSNotEnabled is returned when trying to get a TLS config from a container that does not have TLS enabled.

Functions

func WithDatabase

func WithDatabase(database string) testcontainers.CustomizeRequestOption

WithDatabase sets the name of the database to create and use. This will be converted to lowercase as CockroachDB forces the database to be lowercase. The database creation will be skipped if data exists in the `/cockroach/cockroach-data` directory within the container.

func WithInitScripts

func WithInitScripts(scripts ...string) testcontainers.CustomizeRequestOption

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.

func WithInsecure

func WithInsecure() testcontainers.CustomizeRequestOption

WithInsecure enables insecure mode which disables TLS.

func WithNoClusterDefaults

func WithNoClusterDefaults() testcontainers.CustomizeRequestOption

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.

func WithPassword

func WithPassword(password string) testcontainers.CustomizeRequestOption

WithPassword sets the password of the user to create and connect as. The user creation will be skipped if data exists in the `/cockroach/cockroach-data` directory within the container. This will error if insecure mode is enabled.

func WithStoreSize

func WithStoreSize(size string) testcontainers.CustomizeRequestOption

WithStoreSize sets the amount of available in-memory storage.

func WithUser

func WithUser(user string) testcontainers.CustomizeRequestOption

WithUser sets the name of the user to create and connect as. This will be converted to lowercase as CockroachDB forces the user to be lowercase. The user creation will be skipped if data exists in the `/cockroach/cockroach-data` directory within the container.

Types

type CockroachDBContainer

type CockroachDBContainer struct {
	testcontainers.Container
	// contains filtered or unexported fields
}

CockroachDBContainer represents the CockroachDB container type used in the module

func Run

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*CockroachDBContainer, error)

Run start an instance of the CockroachDB container type using the given image and options.

By default, the container will be configured with:

• Cluster: Single node
• Storage: 100% in-memory
• User: root
• Password: ""
• Database: defaultdb
• Exposed ports: 26257/tcp (SQL), 8080/tcp (Admin UI)
• Init Scripts: `data/cluster_defaults.sql`

This supports CockroachDB images v22.2.0 and later, earlier versions will only work with customised options, such as disabling TLS and removing the wait for `init_success` using a testcontainers.ContainerCustomizer.

The init script `data/cluster_defaults.sql` configures the settings recommended by Cockroach Labs for local testing clusters unless data exists in the `/cockroach/cockroach-data` directory within the container. Use WithNoClusterDefaults to disable this behaviour and provide your own settings using WithInitScripts.

For more information see starting a local cluster in docker.

Example

// runCockroachDBContainer {
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
}
// }

state, err := cockroachdbContainer.State(ctx)
if err != nil {
	log.Printf("failed to get container state: %s", err)
	return
}
fmt.Println(state.Running)

cfg, err := cockroachdbContainer.ConnectionConfig(ctx)
if err != nil {
	log.Printf("failed to get connection string: %s", err)
	return
}

conn, err := pgx.ConnectConfig(ctx, cfg)
if err != nil {
	log.Printf("failed to connect: %s", err)
	return
}

defer func() {
	if err := conn.Close(ctx); err != nil {
		log.Printf("failed to close connection: %s", err)
	}
}()

if err = conn.Ping(ctx); err != nil {
	log.Printf("failed to ping: %s", err)
	return
}

Output:

true

Example (WithInitOptions)

ctx := context.Background()

cockroachdbContainer, err := cockroachdb.Run(ctx, "cockroachdb/cockroach:latest-v23.1",
	cockroachdb.WithNoClusterDefaults(),
	cockroachdb.WithInitScripts("testdata/__init.sql"),
)
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
}

state, err := cockroachdbContainer.State(ctx)
if err != nil {
	log.Printf("failed to get container state: %s", err)
	return
}
fmt.Println(state.Running)

addr, err := cockroachdbContainer.ConnectionString(ctx)
if err != nil {
	log.Printf("failed to get connection string: %s", err)
	return
}

db, err := sql.Open("pgx/v5", addr)
if err != nil {
	log.Printf("failed to open connection: %s", err)
	return
}
defer func() {
	if err := db.Close(); err != nil {
		log.Printf("failed to close connection: %s", err)
	}
}()

var interval string
if err := db.QueryRow("SHOW CLUSTER SETTING kv.range_merge.queue_interval").Scan(&interval); err != nil {
	log.Printf("failed to scan row: %s", err)
	return
}
fmt.Println(interval)

if err := db.QueryRow("SHOW CLUSTER SETTING jobs.registry.interval.gc").Scan(&interval); err != nil {
	log.Printf("failed to scan row: %s", err)
	return
}
fmt.Println(interval)

var statsCollectionEnabled bool
if err := db.QueryRow("SHOW CLUSTER SETTING sql.stats.automatic_collection.enabled").Scan(&statsCollectionEnabled); err != nil {
	log.Printf("failed to scan row: %s", err)
	return
}
fmt.Println(statsCollectionEnabled)

Output:

true
00:00:05
00:00:50
true

func RunContainer

func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*CockroachDBContainer, error)

Deprecated: use Run instead. RunContainer creates an instance of the CockroachDB container type

func (*CockroachDBContainer) ConnectionConfig

func (c *CockroachDBContainer) ConnectionConfig(ctx context.Context) (*pgx.ConnConfig, error)

ConnectionConfig returns a pgx.ConnConfig for the CockroachDB container. This can be passed to pgx.ConnectConfig to open a new connection.

func (*CockroachDBContainer) ConnectionString

func (c *CockroachDBContainer) ConnectionString(ctx context.Context) (string, error)

ConnectionString returns a connection string to open a new connection to CockroachDB. The returned string is suitable for use by [sql.Open] but is not compatible with pgx.ParseConfig, so if you want to call pgx.ConnectConfig use the CockroachDBContainer.ConnectionConfig method instead.

func (*CockroachDBContainer) MustConnectionString

func (c *CockroachDBContainer) MustConnectionString(ctx context.Context) string

MustConnectionString returns a connection string to open a new connection to CockroachDB as described by CockroachDBContainer.ConnectionString. It panics if an error occurs.

func (*CockroachDBContainer) TLSConfig

func (c *CockroachDBContainer) TLSConfig() (*tls.Config, error)

TLSConfig returns config necessary to connect to CockroachDB over TLS. Returns ErrTLSNotEnabled if TLS is not enabled.

Deprecated: use CockroachDBContainer.ConnectionString or CockroachDBContainer.ConnectionConfig instead.