Couchbase

Testcontainers module for Couchbase. Couchbase is a document oriented NoSQL database.

Adding this module to your project dependencies

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

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

Usage example

1. The StartContainer function is the main entry point to create a new CouchbaseContainer instance. It takes a context and zero or more Option values to configure the container. It creates a new container instance, initializes the couchbase cluster, and creates buckets. If successful, it returns the CouchbaseContainer instance.

Start Couchbase

bucketName := "testBucket"
container, err := tccouchbase.StartContainer(ctx, tccouchbase.WithImageName(communityEdition), tccouchbase.WithBucket(tccouchbase.NewBucket(bucketName)))
if err != nil {
    t.Fatal(err)
}

1. The ConnectionString method returns the connection string to connect to the Couchbase container instance. It returns a string with the format couchbase://<host>:<port>. The Username method returns the username of the Couchbase administrator. The Password method returns the password of the Couchbase administrator.

Connect to Couchbase

func connectCluster(ctx context.Context, container *tccouchbase.CouchbaseContainer) (*gocb.Cluster, error) {
    connectionString, err := container.ConnectionString(ctx)
    if err != nil {
        return nil, err
    }

    return gocb.Connect(connectionString, gocb.ClusterOptions{
        Username: container.Username(),
        Password: container.Password(),
    })
}

Module Reference

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

func StartContainer(ctx context.Context, opts ...Option) (*CouchbaseContainer, error)

• context.Context, the Go context.
• Option, a variad argument for passing options.

Container Options

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

Image

If you need to set a different Couchbase Docker image, you can use WithImageName with a valid Docker image for Couchbase. E.g. WithImageName("docker.io/couchbase:6.5.1").

By default, the container will use the following Docker image:

Default Docker image

imageName: "couchbase:6.5.1",

Credentials

If you need to change the default credentials for the admin user, you can use WithCredentials(user, password) with a valid username and password.

Info

The default username is Administrator and the default password is password.

Bucket

When creating a new Couchbase container, you can create one or more buckets. The module provides a NewBucket function to create a new bucket, where you can pass the bucket name.

Adding a new bucket

bucketName := "testBucket"
container, err := tccouchbase.StartContainer(ctx, tccouchbase.WithImageName(communityEdition), tccouchbase.WithBucket(tccouchbase.NewBucket(bucketName)))
if err != nil {
    t.Fatal(err)
}

It's possible to customize a newly created bucket, using the following options:

• WithQuota: sets the bucket quota in megabytes. The minimum value is 100 MB.
• WithReplicas: sets the number of replicas for this bucket. The minimum value is 0 and the maximum value is 3.
• WithFlushEnabled: sets whether the bucket should be flushed when the container is stopped.
• WithPrimaryIndex: sets whether the primary index should be created for this bucket.

bucket := NewBucket(
    "bucketName",
    WithQuota(100),
    WithReplicas(1),
    WithFlushEnabled(true),
    WithPrimaryIndex(true),
)

Index Storage

It's possible to set the storage mode to be used for all global secondary indexes in the cluster.

Warning

Please note: plasma and memory optimized are options in the Enterprise Edition of Couchbase Server. If you are using the Community Edition, the only value allowed is forestdb.

Storage types

const (
    // MemoryOptimized sets the cluster-wide index storage mode to use memory optimized global
    // secondary indexes which can perform index maintenance and index scan faster at in-memory speeds.
    // This is the default value for the testcontainers couchbase implementation.
    MemoryOptimized indexStorageMode = "memory_optimized"

    // Plasma sets the cluster-wide index storage mode to use the Plasma storage engine,
    // which can utilize both memory and persistent storage for index maintenance and index scans.
    Plasma indexStorageMode = "plasma"

    // ForestDB sets the cluster-wide index storage mode to use the forestdb storage engine,
    // which only utilizes persistent storage for index maintenance and scans. It is the only option available
    // for the community edition.
    ForestDB indexStorageMode = "forestdb"
)

Services

By default, the container will start with the following services: kv, n1ql, fts and index.

Warning

When running the Enterprise Edition of Couchbase Server, the module provides two functions to enable or disable services: WithAnalyticsService and WithEventingService. Else, it will throw an error and the container won't be created.

Docker images

const (
    enterpriseEdition = "couchbase:enterprise-7.1.3"
    communityEdition  = "couchbase:community-7.1.1"
)