Testcontainers for Go

https://golang.testcontainers.org
Admin
Testcontainers for Go is a Go package that simplifies the creation and cleanup of container-based...
Tokens:328,019
Snippets:2,667
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Get KubeConfig and list nodes with k3s.Run

Source: https://golang.testcontainers.org/modules/k3s

Shows how to start a K3s container with k3s.Run, retrieve its kubeconfig via GetKubeConfig, and use it to create a Kubernetes client and list nodes. The example prints the container running state and the number of nodes, with expected output true and 1.

```go
package k3s_test

import (
    "context"
    "fmt"
    "log"

    v1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/kubernetes"
    "k8s.io/client-go/tools/clientcmd"

    "github.com/testcontainers/testcontainers-go"
    "github.com/testcontainers/testcontainers-go/modules/k3s"
)

func ExampleRun() {
    // runK3sContainer {
    ctx := context.Background()

    k3sContainer, err := k3s.Run(ctx, "rancher/k3s:v1.27.1-k3s1")
    defer func() {
        if err := testcontainers.TerminateContainer(k3sContainer); err != nil {
            log.Printf("failed to terminate container: %s", err)
        }
    }()
    if err != nil {
        log.Printf("failed to start container: %s", err)
        return
    }
    // }

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

    fmt.Println(state.Running)

    kubeConfigYaml, err := k3sContainer.GetKubeConfig(ctx)
    if err != nil {
        log.Printf("failed to get kubeconfig: %s", err)
        return
    }

    restcfg, err := clientcmd.RESTConfigFromKubeConfig(kubeConfigYaml)
    if err != nil {
        log.Printf("failed to create rest config: %s", err)
        return
    }

    k8s, err := kubernetes.NewForConfig(restcfg)
    if err != nil {
        log.Printf("failed to create k8s client: %s", err)
        return
    }

    nodes, err := k8s.CoreV1().Nodes().List(ctx, v1.ListOptions{})
    if err != nil {
        log.Printf("failed to list nodes: %s", err)
        return
    }

    fmt.Println(len(nodes.Items))

    // Output:
    // true
    // 1
}

```

--------------------------------

### Postgres init script example

Source: https://golang.testcontainers.org/modules/postgres

An example of a *.sh script that creates a user and database. It uses the psql command with ON_ERROR_STOP=1 and the POSTGRES_USER and POSTGRES_DB environment variables. The script is copied to /docker-entrypoint-initdb.d and executed before the Postgres service starts.

```bash
#!/bin/bash
set -e

psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
    CREATE USER docker;
    CREATE DATABASE docker;
    GRANT ALL PRIVILEGES ON DATABASE docker TO docker;
    CREATE TABLE IF NOT EXISTS testdb (id int, name varchar(255));
    INSERT INTO testdb (id, name) VALUES (1, 'test')
EOSQL

```

--------------------------------

### Build and serve docs with make serve-docs

Source: https://golang.testcontainers.org/contributing

Build and serve the documentation locally from the repository root. Uses a Docker container to install dependencies and starts a local server at http://localhost:8000.

```bash
make serve-docs

```

--------------------------------

### Usage example: Create and use a Pinecone container

Source: https://golang.testcontainers.org/modules/pinecone

This example shows how to run a Pinecone container, get its HTTP endpoint, create a Pinecone client, and create a serverless index. It includes error handling and prints the container state and index name.

```go
ctx := context.Background()

pineconeContainer, err := tcpinecone.Run(ctx, "ghcr.io/pinecone-io/pinecone-local:v0.7.0")
defer func() {
    if err := testcontainers.TerminateContainer(pineconeContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

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

fmt.Println(state.Running)

// httpConnection {
host, err := pineconeContainer.HttpEndpoint()
if err != nil {
    log.Printf("failed to get container state: %s", err)
    return
}
// }

pc, err := pinecone.NewClient(pinecone.NewClientParams{
    ApiKey: "testcontainers-go", // API key is required, else use headers
    Host:   host,
})
if err != nil {
    log.Printf("failed to create pinecone client: %s", err)
    return
}

indexName := "my-serverless-index"

idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
    Name:      indexName,
    Dimension: 3,
    Metric:    pinecone.Cosine,
    Cloud:     pinecone.Aws,
    Region:    "us-east-1",
    Tags:      &pinecone.IndexTags{"environment": "development"},
})
if err != nil {
    log.Printf("failed to create serverless index: %s", err)
    return
}

fmt.Println(idx.Name)

// Output:
// true
// my-serverless-index

```

--------------------------------

### Create and use a NebulaGraph cluster with Testcontainers

Source: https://golang.testcontainers.org/modules/nebulagraph

This example shows how to start a NebulaGraph cluster using RunCluster, obtain a connection string, and perform basic operations like authentication and a YIELD query. It requires the testcontainers-go NebulaGraph module and the nebula-sirius client library. The example includes error handling and cleanup.

```go
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
defer cancel()

container, err := nebulagraph.RunCluster(ctx,
    defaultGraphdImage, []testcontainers.ContainerCustomizer{},
    defaultStoragedImage, []testcontainers.ContainerCustomizer{},
    defaultMetadImage, []testcontainers.ContainerCustomizer{},
)
require.NoError(t, err)
t.Cleanup(func() { _ = container.Terminate(ctx) })

conn, err := container.ConnectionString(ctx)
require.NoError(t, err)
require.NotEmpty(t, conn)

// Parse the connection string to get host and port
host, portt, err := net.SplitHostPort(conn)
require.NoError(t, err)

portInt, err := strconv.Atoi(portt)
require.NoError(t, err)

// Create client factory
clientFactory := nebula_sirius.NewNebulaClientFactory(
    &nebula_sirius.NebulaClientConfig{
        HostAddress: nebula_sirius.HostAddress{
            Host: host,
            Port: portInt,
        },
    },
    nebula_sirius.DefaultLogger{},
    nebula_sirius.DefaultClientNameGenerator,
)

// Create client pool
nebulaClientPool := pool.NewObjectPool(
    ctx,
    clientFactory,
    &pool.ObjectPoolConfig{
        MaxIdle:  5,
        MaxTotal: 10,
    },
)

// Test client connection and basic queries
t.Run("basic-operations", func(t *testing.T) {
    // Get a client from the pool
    clientObj, err := nebulaClientPool.BorrowObject(ctx)
    require.NoError(t, err)
    defer func() {
        err := nebulaClientPool.ReturnObject(ctx, clientObj)
        require.NoError(t, err)
    }()

    client := clientObj.(*nebula_sirius.WrappedNebulaClient)
    require.NotNil(t, client)

    // Get graph client
    g, err := client.GraphClient()
    require.NoError(t, err)

    // Authenticate
    auth, err := g.Authenticate(ctx, []byte("root"), []byte("nebula"))
    require.NoError(t, err)
    require.Equal(t, nebula.ErrorCode_SUCCEEDED, auth.GetErrorCode(), "Auth error: %s", auth.GetErrorMsg())

    // Test YIELD query
    result, err := g.Execute(ctx, *auth.SessionID, []byte("YIELD 1;"))
    require.NoError(t, err)
    require.Equal(t, nebula.ErrorCode_SUCCEEDED, result.GetErrorCode(), "Query error: %s", result.GetErrorMsg())

    // Validate result contains our storage node
    resultSet, err := nebula_sirius.GenResultSet(result)
    require.NoError(t, err)

    // Convert result to string for validation
    rows := resultSet.GetRows()
    require.NotEmpty(t, rows, "Expected at least one row in YIELD output")

    row := rows[0]
    require.NotNil(t, row, "Row should not be nil")

    vals := row.GetValues()
    require.NotEmpty(t, vals, "Row values should not be empty")
    require.Equal(t, int64(1), vals[0].GetIVal())
})

```

--------------------------------

### Connect and create database with CosmosDB

Source: https://golang.testcontainers.org/modules/azure

Example of connecting to a CosmosDB container and creating a database. It runs the container, gets the connection string, creates a client, and creates a database named 'myDatabase'.

```go
ctx := context.Background()

cosmosdbContainer, err := cosmosdb.Run(ctx, "mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview")
defer func() {
    if err := testcontainers.TerminateContainer(cosmosdbContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

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

p, err := cosmosdb.NewContainerPolicy(ctx, cosmosdbContainer)
if err != nil {
    log.Printf("failed to create policy: %s", err)
    return
}

client, err := azcosmos.NewClientFromConnectionString(connString, p.ClientOptions())
if err != nil {
    log.Printf("failed to create cosmosdb client: %s", err)
    return
}

createDatabaseResp, err := client.CreateDatabase(ctx, azcosmos.DatabaseProperties{ID: "myDatabase"}, nil)
if err != nil {
    log.Printf("failed to create database: %s", err)
    return
}

```

--------------------------------

### Update Go dependencies in examples

Source: https://golang.testcontainers.org/examples

Run these commands from the examples directory to update Go dependencies in the examples. The commands are executed in a shell.

```shell
$ cd examples
$ make tidy-examples

```

--------------------------------

### Example init script for WithScripts

Source: https://golang.testcontainers.org/modules/mariadb

Example init script to be used with the WithScripts option. It creates a profile table and inserts a row.

```sql
CREATE TABLE IF NOT EXISTS profile (
    id MEDIUMINT NOT NULL AUTO_INCREMENT,
    name VARCHAR(30) NOT NULL,
    PRIMARY KEY (id)
);

INSERT INTO profile (name) values ('profile 1');

```

--------------------------------

### Full Qdrant usage example

Source: https://golang.testcontainers.org/modules/qdrant

Full example showing how to run a Qdrant container and retrieve its gRPC endpoint. It includes container termination and error handling.

```go
qdrantContainer, err := qdrant.Run(context.Background(), "qdrant/qdrant:v1.7.4")
defer func() {
    if err := testcontainers.TerminateContainer(qdrantContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

grpcEndpoint, err := qdrantContainer.GRPCEndpoint(context.Background())
if err != nil {
    log.Printf("failed to get gRPC endpoint: %s", err)
    return
}

```

--------------------------------

### Configure custom credentials

Source: https://golang.testcontainers.org/modules/opensearch

Example of starting an OpenSearch container with custom username and password credentials using WithUsername and WithPassword options.

```go
ctx := context.Background()

opensearchContainer, err := opensearch.Run(
    ctx,
    "opensearchproject/opensearch:2.11.1",
    opensearch.WithUsername("new-username"),
    opensearch.WithPassword("new-password"),
)
defer func() {
    if err := testcontainers.TerminateContainer(opensearchContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}
```

--------------------------------

### Create Elasticsearch client with container settings

Source: https://golang.testcontainers.org/modules/elasticsearch

Create an Elasticsearch client using the official Go client. It starts a container with password "foo", builds a config with the container's address, credentials, and CA certificate, then creates the client and calls Info(). Requires installing the Elasticsearch Go client.

```go
ctx := context.Background()
elasticsearchContainer, err := elasticsearch.Run(
    ctx,
    "docker.elastic.co/elasticsearch/elasticsearch:8.9.0",
    elasticsearch.WithPassword("foo"),
)
defer func() {
    if err := testcontainers.TerminateContainer(elasticsearchContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

cfg := es.Config{
    Addresses: []string{
        elasticsearchContainer.Settings.Address,
    },
    Username: "elastic",
    Password: elasticsearchContainer.Settings.Password,
    CACert:   elasticsearchContainer.Settings.CACert,
}

esClient, err := es.NewClient(cfg)
if err != nil {
    log.Printf("error creating the client: %s", err)
    return
}

resp, err := esClient.Info()
if err != nil {
    log.Printf("error getting response: %s", err)
    return
}
defer resp.Body.Close()

```

--------------------------------

### Properties file example for Docker host configuration

Source: https://golang.testcontainers.org/features/configuration

Example of ~/.testcontainers.properties file to configure Docker host connection. Environment variables take precedence over these properties.

```properties
docker.host=tcp://my.docker.host:1234       # Equivalent to the DOCKER_HOST environment variable.
docker.tls.verify=1                         # Equivalent to the DOCKER_TLS_VERIFY environment variable
docker.cert.path=/some/path                 # Equivalent to the DOCKER_CERT_PATH environment variable

```

--------------------------------

### Run modulegen to create an example module

Source: https://golang.testcontainers.org/modules

Run from the modulegen directory to generate an example module with no public API. Requires the same flags as the module command.

```bash
go run . new example --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}

```

--------------------------------

### Install the Compose module

Source: https://golang.testcontainers.org/features/docker_compose

Install the Testcontainers for Go Compose module. Requires Go 1.21 or later.

```bash
go get github.com/testcontainers/testcontainers-go/modules/compose

```

--------------------------------

### ForAll wait strategy with WithDeadline and WithStartupTimeoutDefault

Source: https://golang.testcontainers.org/features/wait/all

Creates a ForAll wait strategy that runs inner strategies in series, failing the entire wait if any fails. Use WithStartupTimeoutDefault to set a default timeout for inner strategies that don't define one, and WithDeadline to set an overall deadline. The example shows how to build the strategy and start waiting with WaitUntilReady.

```go
// The following are run in series. Any that fail will fail the entire
// ForAll, and the remaining waiting strategies will be cancelled. All must
// succeed for the ForAll to succeed.
strategy := wait.ForAll(
    wait.ForLog("port: 3306  MySQL Community Server - GPL"),              // Timeout: 120s
    wait.ForExposedPort().WithStartupTimeout(180*time.Second),            // Timeout: 180s
    wait.ForListeningPort("3306/tcp").WithStartupTimeout(10*time.Second), // Timeout: 10s
)

// You can apply a default StartupTimeout for any inner strategy that didn't define it.
strategy = strategy.WithStartupTimeoutDefault(120 * time.Second)

// You can apply an overall deadline for all the strategies to complete within.
strategy = strategy.WithDeadline(360 * time.Second)

// Call WaitUntilReady, or pass the strategy to a function that uses it, to
// start waiting.
_ = strategy.WaitUntilReady(context.Background(), &wait.NopStrategyTarget{})
```

--------------------------------

### Install Testcontainers for Go with go get

Source: https://golang.testcontainers.org/quickstart

Installs the Testcontainers for Go module using go mod.

```bash
go get github.com/testcontainers/testcontainers-go

```

--------------------------------

### Full Go gRPC example for Qdrant

Source: https://golang.testcontainers.org/modules/qdrant

Complete example that connects to Qdrant, creates a collection, lists collections, and creates field indexes. It uses the Qdrant gRPC API with insecure credentials and demonstrates error handling with log.Printf.

```go
// Set up a connection to the server.
conn, err := grpc.NewClient(grpcEndpoint, grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
    log.Printf("did not connect: %v", err)
    return
}
defer conn.Close()

collectionsClient := pb.NewCollectionsClient(conn)

const (
    collectionName        = "test_collection"
    vectorSize     uint64 = 4
    distance              = pb.Distance_Dot
)

// 1. create the collection
var defaultSegmentNumber uint64 = 2
_, err = collectionsClient.Create(context.Background(), &pb.CreateCollection{
    CollectionName: collectionName,
    VectorsConfig: &pb.VectorsConfig{Config: &pb.VectorsConfig_Params{
        Params: &pb.VectorParams{
            Size:     vectorSize,
            Distance: distance,
        },
    }},
    OptimizersConfig: &pb.OptimizersConfigDiff{
        DefaultSegmentNumber: &defaultSegmentNumber,
    },
})
if err != nil {
    log.Printf("Could not create collection: %v", err)
    return
}

// 2. Contact the server and print out its response.
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
r, err := collectionsClient.List(ctx, &pb.ListCollectionsRequest{})
if err != nil {
    log.Printf("could not get collections: %v", err)
    return
}
fmt.Printf("List of collections: %s\n", r.GetCollections())

// 3. Create points grpc client
pointsClient := pb.NewPointsClient(conn)

// 4. Create keyword field index
fieldIndex1Type := pb.FieldType_FieldTypeKeyword
fieldIndex1Name := "city"
_, err = pointsClient.CreateFieldIndex(context.Background(), &pb.CreateFieldIndexCollection{
    CollectionName: collectionName,
    FieldName:      fieldIndex1Name,
    FieldType:      &fieldIndex1Type,
})
if err != nil {
    log.Printf("Could not create field index: %v", err)
    return
}

// 5. Create integer field index
fieldIndex2Type := pb.FieldType_FieldTypeInteger
fieldIndex2Name := "count"
_, err = pointsClient.CreateFieldIndex(context.Background(), &pb.CreateFieldIndexCollection{
    CollectionName: collectionName,
    FieldName:      fieldIndex2Name,
    FieldType:      &fieldIndex2Type,
})
if err != nil {
    log.Printf("Could not create field index: %v", err)
    return
}
```

--------------------------------

### Install Valkey module with go get

Source: https://golang.testcontainers.org/modules/valkey

Adds the Valkey module to your Go dependencies.

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

```

--------------------------------

### Install Presto module with go get

Source: https://golang.testcontainers.org/modules/presto

Adds the Presto module to your Go dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/presto

```

--------------------------------

### Install OpenSearch module with go get

Source: https://golang.testcontainers.org/modules/opensearch

Adds the OpenSearch module to your Go dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/opensearch

```

--------------------------------

### Install Neo4j module with go get

Source: https://golang.testcontainers.org/modules/neo4j

Adds the Neo4j module to your Go dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/neo4j

```

--------------------------------

### Create a MySQL container with mysql.Run

Source: https://golang.testcontainers.org/modules/mysql

This example creates a MySQL container using the mysql.Run function with configuration options for config file, database, username, password, and scripts. It includes deferred termination and error handling.

```go
ctx := context.Background()

mysqlContainer, err := mysql.Run(ctx,
    "mysql:8.0.36",
    mysql.WithConfigFile(filepath.Join("testdata", "my_8.cnf")),
    mysql.WithDatabase("foo"),
    mysql.WithUsername("root"),
    mysql.WithPassword("password"),
    mysql.WithScripts(filepath.Join("testdata", "schema.sql")),
)
defer func() {
    if err := testcontainers.TerminateContainer(mysqlContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

```

--------------------------------

### Install ClickHouse module with go get

Source: https://golang.testcontainers.org/modules/clickhouse

Adds the ClickHouse module to Go dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/clickhouse

```

--------------------------------

### Install CrateDB module with go get

Source: https://golang.testcontainers.org/modules/cratedb

Adds the CrateDB module to your Go dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/cratedb

```

--------------------------------

### Install Chroma module with go get

Source: https://golang.testcontainers.org/modules/chroma

Adds the Chroma module to your Go dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/chroma
```

--------------------------------

### Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*CassandraContainer, error)

Source: https://golang.testcontainers.org/modules/cassandra

Creates a Cassandra container with the specified Docker image and options. This is the main entrypoint for starting a Cassandra container.

```APIDOC
## Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*CassandraContainer, error)

### Description
Creates a Cassandra container with the specified Docker image and options. This is the main entrypoint for starting a Cassandra container.

### Parameters
- **ctx** (context.Context) - Required - The Go context.
- **img** (string) - Required - The Docker image to use.
- **opts** (testcontainers.ContainerCustomizer) - Optional - Variadic options for configuring the container.

### Returns
- **(*CassandraContainer, error)** - The created container and an error if any.

### Example
```go
cassandraContainer, err := cassandra.Run(ctx, "cassandra:4.1.3", cassandra.WithInitScripts(filepath.Join("testdata", "init.cql")), cassandra.WithConfigFile(filepath.Join("testdata", "config.yaml")))
```
```

--------------------------------

### Create a Solace Pubsub+ container with Run

Source: https://golang.testcontainers.org/modules/solace

This example creates a Solace Pubsub+ container using the Run function with credentials, services, environment variables, and shared memory size. It also shows how to terminate the container and print any error.

```go
ctx := context.Background()
ctr, err := sc.Run(ctx, "solace/solace-pubsub-standard:latest",
    sc.WithCredentials("admin", "admin"),
    sc.WithServices(sc.ServiceAMQP, sc.ServiceManagement),
    testcontainers.WithEnv(map[string]string{
        "username_admin_globalaccesslevel": "admin",
        "username_admin_password":          "admin",
    }),
    sc.WithShmSize(1<<30),
)
defer func() {
    if err := testcontainers.TerminateContainer(ctr); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
fmt.Println(err)

```

--------------------------------

### Install Aerospike module with go get

Source: https://golang.testcontainers.org/modules/aerospike

Adds the Aerospike module to your Go dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/aerospike

```

--------------------------------

### Install Consul module with go get

Source: https://golang.testcontainers.org/modules/consul

Adds the Consul module to your Go dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/consul

```

--------------------------------

### Install Postgres module with go get

Source: https://golang.testcontainers.org/modules/postgres

Adds the Postgres module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/postgres

```

--------------------------------

### Create Datastore container and client

Source: https://golang.testcontainers.org/modules/gcloud

Shows how to create a Datastore container and then obtain a client. The first block runs the container with a project ID and terminates it. The second block uses the container's ProjectID and URI to create a client, with the note that option.WithEndpoint must be set to the container's URI.

```go
ctx := context.Background()

datastoreContainer, err := tcdatastore.Run(
    ctx,
    "gcr.io/google.com/cloudsdktool/cloud-sdk:emulators",
    tcdatastore.WithProjectID("datastore-project"),
)
defer func() {
    if err := testcontainers.TerminateContainer(datastoreContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to run container: %v", err)
    return
}

```

```go
projectID := datastoreContainer.ProjectID()

options := []option.ClientOption{
    option.WithEndpoint(datastoreContainer.URI()),
    option.WithoutAuthentication(),
    option.WithGRPCDialOption(grpc.WithTransportCredentials(insecure.NewCredentials())),
}

dsClient, err := datastore.NewClient(ctx, projectID, options...)
if err != nil {
    log.Printf("failed to create client: %v", err)
    return
}
defer dsClient.Close()

```

--------------------------------

### Install Solr module with go get

Source: https://golang.testcontainers.org/modules/solr

Adds the Solr module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/solr

```

--------------------------------

### Install Redpanda module with go get

Source: https://golang.testcontainers.org/modules/redpanda

Adds the Redpanda module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/redpanda

```

--------------------------------

### Run ScyllaDB with custom config file

Source: https://golang.testcontainers.org/modules/scylladb

Starts a ScyllaDB container with a custom scylla.yaml configuration passed as an io.Reader via WithConfig. The configuration must be valid YAML or the container will fail to start.

```go
    ctx := context.Background()

    cfgBytes := `cluster_name: 'Amazing ScyllaDB Test'
num_tokens: 256
commitlog_sync: periodic
commitlog_sync_period_in_ms: 10000
commitlog_segment_size_in_mb: 32
schema_commitlog_segment_size_in_mb: 128
seed_provider:
  - class_name: org.apache.cassandra.locator.SimpleSeedProvider
    parameters:
      - seeds: "127.0.0.1"
listen_address: localhost
native_transport_port: 9042
native_shard_aware_transport_port: 19042
read_request_timeout_in_ms: 5000
write_request_timeout_in_ms: 2000
cas_contention_timeout_in_ms: 1000
endpoint_snitch: SimpleSnitch
rpc_address: localhost
api_port: 10000
api_address: 127.0.0.1
batch_size_warn_threshold_in_kb: 128
batch_size_fail_threshold_in_kb: 1024
partitioner: org.apache.cassandra.dht.Murmur3Partitioner
commitlog_total_space_in_mb: -1
murmur3_partitioner_ignore_msb_bits: 12
strict_is_not_null_in_views: true
maintenance_socket: ignore
enable_tablets: true
`

    scyllaContainer, err := scylladb.Run(ctx,
        "scylladb/scylla:6.2",
        scylladb.WithConfig(strings.NewReader(cfgBytes)),
    )

```

--------------------------------

### Install Nginx module with go get

Source: https://golang.testcontainers.org/modules/nginx

Adds the Nginx module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/nginx
```

--------------------------------

### Run

Source: https://golang.testcontainers.org/modules/mssql

Creates and starts an MS SQL Server container. This is the main entrypoint for the module.

```APIDOC
## Run

### Description
Creates and starts an MS SQL Server container. This is the main entrypoint for the module.

### Function Signature
`func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MSSQLServerContainer, error)`

### Parameters
- `ctx` (context.Context) - Required - The Go context.
- `img` (string) - Required - The Docker image to use.
- `opts` (testcontainers.ContainerCustomizer) - Optional - Variadic argument for passing options.

### Example
```go
container, err := mssql.Run(context.Background(), "mcr.microsoft.com/mssql/server:2022-RTM-GDR1-ubuntu-20.04")
```

### Notes
- The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release.
- Since v0.32.0
```

--------------------------------

### Install MockServer module with go get

Source: https://golang.testcontainers.org/modules/mockserver

Adds the MockServer module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/mockserver

```

--------------------------------

### Run

Source: https://golang.testcontainers.org/modules/postgres

Creates a Postgres container with the specified Docker image and options. This is the main entrypoint for the module.

```APIDOC
## Run

### Description
Creates a Postgres container with the specified Docker image and options. This is the main entrypoint for the module.

### Function Signature
```go
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*PostgresContainer, error)
```

### Parameters
- **ctx** (context.Context) - Required - The Go context.
- **img** (string) - Required - The Docker image to use.
- **opts** (testcontainers.ContainerCustomizer) - Optional - Variadic argument for passing options.

### Usage Example
```go
ctx := context.Background()

dbName := "users"
dbUser := "user"
dbPassword := "password"

postgresContainer, err := postgres.Run(ctx,
    "postgres:16-alpine",
    postgres.WithInitScripts(filepath.Join("testdata", "init-user-db.sh")),
    postgres.WithConfigFile(filepath.Join("testdata", "my-postgres.conf")),
    postgres.WithDatabase(dbName),
    postgres.WithUsername(dbUser),
    postgres.WithPassword(dbPassword),
    postgres.BasicWaitStrategies(),
)
defer func() {
    if err := testcontainers.TerminateContainer(postgresContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}
```

### Notes
- Since v0.32.0
- The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release.
```

--------------------------------

### Install KurrentDB module with go get

Source: https://golang.testcontainers.org/modules/kurrentdb

Adds the KurrentDB module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/kurrentdb
```

--------------------------------

### Install Firebird module with go get

Source: https://golang.testcontainers.org/modules/firebird

Adds the Firebird module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/firebird

```

--------------------------------

### Run ClickHouse container with options

Source: https://golang.testcontainers.org/modules/clickhouse

Starts a ClickHouse container with username, password, database, init script, and config file. Terminates the container on exit and logs errors if startup fails.

```go
ctx := context.Background()

user := "clickhouse"
password := "password"
dbname := "testdb"

clickHouseContainer, err := clickhouse.Run(ctx,
    "clickhouse/clickhouse-server:23.3.8.21-alpine",
    clickhouse.WithUsername(user),
    clickhouse.WithPassword(password),
    clickhouse.WithDatabase(dbname),
    clickhouse.WithInitScripts(filepath.Join("testdata", "init-db.sh")),
    clickhouse.WithConfigFile(filepath.Join("testdata", "config.xml")),
)
defer func() {
    if err := testcontainers.TerminateContainer(clickHouseContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

```

--------------------------------

### Run a Valkey container with tcvalkey.Run

Source: https://golang.testcontainers.org/modules/valkey

Creates a Valkey container using the testcontainers-go module. The example uses the valkey/valkey:7.2.5 image and configures snapshotting, log level, and a config file. It terminates the container and logs errors if startup fails.

```go
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
}

```

--------------------------------

### Install Cassandra module with go get

Source: https://golang.testcontainers.org/modules/cassandra

Adds the Cassandra module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/cassandra

```

--------------------------------

### Install ArangoDB module with go get

Source: https://golang.testcontainers.org/modules/arangodb

Adds the ArangoDB module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/arangodb

```

--------------------------------

### Create Cassandra container with init scripts, config file, or TLS

Source: https://golang.testcontainers.org/modules/cassandra

Shows two usage examples: one with init scripts and a config file, and one with TLS enabled. Both use the cassandra.Run function with the cassandra:4.1.3 image and terminate the container in a deferred function.

```go
    ctx := context.Background()

    cassandraContainer, err := cassandra.Run(ctx,
        "cassandra:4.1.3",
        cassandra.WithInitScripts(filepath.Join("testdata", "init.cql")),
        cassandra.WithConfigFile(filepath.Join("testdata", "config.yaml")),
    )
    defer func() {
        if err := testcontainers.TerminateContainer(cassandraContainer); err != nil {
            log.Printf("failed to terminate container: %s", err)
        }
    }()
    if err != nil {
        log.Printf("failed to start container: %s", err)
        return
    }

 ⋯

    ctx := context.Background()

    cassandraContainer, err := cassandra.Run(ctx,
        "cassandra:4.1.3",
        cassandra.WithTLS(),
    )
    defer func() {
        if err := testcontainers.TerminateContainer(cassandraContainer); err != nil {
            log.Printf("failed to terminate container: %s", err)
        }
    }()
    if err != nil {
        log.Printf("failed to start container: %s", err)
        return
    }

```

--------------------------------

### Install ScyllaDB module with go get

Source: https://golang.testcontainers.org/modules/scylladb

Adds the ScyllaDB Testcontainers module to your Go project dependencies.

```bash
go get github.com/testcontainers/testcontainers-go/modules/scylladb

```

--------------------------------

### Run ScyllaDB container with custom commands

Source: https://golang.testcontainers.org/modules/scylladb

Starts a ScyllaDB container with custom command-line options (--memory=1G, --smp=2) and verifies it is running. Uses NonShardAwareConnectionHost to obtain the connection host for a Go CQL test. The expected output is true.

```go
    ctx := context.Background()

    // runScyllaDBContainerWithCustomCommands {
    scyllaContainer, err := scylladb.Run(ctx,
        "scylladb/scylla:6.2",
        scylladb.WithCustomCommands("--memory=1G", "--smp=2"),
    )
    // }
    defer func() {
        if err := testcontainers.TerminateContainer(scyllaContainer); err != nil {
            log.Printf("failed to terminate container: %s", err)
        }
    }()
    if err != nil {
        log.Printf("failed to start container: %s", err)
        return
    }

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

    fmt.Println(state.Running)

    connectionHost, err := scyllaContainer.NonShardAwareConnectionHost(ctx)
    if err != nil {
        log.Printf("failed to get connection host: %s", err)
        return
    }

    if err := runGoCQLExampleTest(connectionHost); err != nil {
        log.Printf("failed to run Go CQL example test: %s", err)
        return
    }

    // Output:
    // true

```

--------------------------------

### Get ManagementURL from RavenDB container

Source: https://golang.testcontainers.org/modules/ravendb

Shows how to obtain the management URL from the container and verify it starts with http://.

```go
ctx := context.Background()

ravendbContainer, err := ravendb.Run(ctx, "ravendb/ravendb:6.0-ubuntu-latest")
defer func() {
    if err := testcontainers.TerminateContainer(ravendbContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

managementURL, err := ravendbContainer.ManagementURL(ctx)
if err != nil {
    log.Printf("failed to get management URL: %s", err)
    return
}

isHTTP := len(managementURL) > 7 && managementURL[:7] == "http://"
fmt.Println(isHTTP)

// Output:
// true

```

--------------------------------

### Create a Nginx container with nginx.Run

Source: https://golang.testcontainers.org/modules/nginx

Creates a Nginx container using the Run function. The example uses the image nginx:1.25 and includes error handling and deferred termination.

```go
ctx := context.Background()

nginxContainer, err := nginx.Run(ctx, "nginx:1.25")
defer func() {
    if err := testcontainers.TerminateContainer(nginxContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}
```

--------------------------------

### Init script for Cassandra keyspace and table creation

Source: https://golang.testcontainers.org/modules/cassandra

Example init script that creates a keyspace, a table, and inserts a row. Used with the WithInitScripts option; scripts are copied to the container root before startup.

```bash
#!/bin/bash
set -e

cqlsh -e "CREATE KEYSPACE IF NOT EXISTS init_sh_keyspace WITH REPLICATION = {'class': 'SimpleStrategy', 'replication_factor': 1};" && \
cqlsh -e "CREATE TABLE IF NOT EXISTS init_sh_keyspace.test_table (id bigint,name text,primary key (id));" && \
cqlsh -e "INSERT INTO init_sh_keyspace.test_table (id, name) VALUES (1, 'NAME');"

```

--------------------------------

### Install QuestDB module with go get

Source: https://golang.testcontainers.org/modules/questdb

Adds the QuestDB module to your Go dependencies. Run this command in your project directory.

```bash
go get github.com/testcontainers/testcontainers-go/modules/questdb

```

--------------------------------

### Run

Source: https://golang.testcontainers.org/modules/qdrant

Creates a Qdrant container with the specified Docker image and optional customizations. Returns a pointer to QdrantContainer and an error.

```APIDOC
## Run

### Description
Creates a Qdrant container with the specified Docker image and optional customizations. Returns a pointer to QdrantContainer and an error.

### Function Signature
go
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*QdrantContainer, error)


### Parameters
- **ctx** (context.Context) - Required - The Go context.
- **img** (string) - Required - The Docker image to use.
- **opts** (testcontainers.ContainerCustomizer) - Optional - Variadic argument for passing options.

### Example
go
ctx := context.Background()
qdrantContainer, err := qdrant.Run(ctx, "qdrant/qdrant:v1.7.4")
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}
defer func() {
    if err := testcontainers.TerminateContainer(qdrantContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()

```

--------------------------------

### Install ActiveMQ module with go get

Source: https://golang.testcontainers.org/modules/activemq

Adds the ActiveMQ module to your Go dependencies. Run this command in your project directory.

```bash
go get github.com/testcontainers/testcontainers-go/modules/activemq

```

--------------------------------

### Get Timeplus HTTP endpoint

Source: https://golang.testcontainers.org/modules/timeplus

Gets the HTTP endpoint of the Timeplus container using the HTTPEndpoint method. The example prints true if the endpoint is non-empty. Because Timeplus is wire-protocol compatible with ClickHouse, any ClickHouse client library can connect via this endpoint.

```go
ctx := context.Background()

timeplusContainer, err := timeplus.Run(ctx, "timeplus/timeplusd:2.3.37")
defer func() {
    if err := testcontainers.TerminateContainer(timeplusContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

httpEndpoint, err := timeplusContainer.HTTPEndpoint(ctx)
if err != nil {
    log.Printf("failed to get HTTP endpoint: %s", err)
    return
}

fmt.Println(len(httpEndpoint) > 0)

// Output:
// true

```

--------------------------------

### Create a CouchDB container with admin credentials

Source: https://golang.testcontainers.org/modules/couchdb

This example creates a CouchDB container using the couchdb.Run function with the image 'couchdb:3' and sets admin credentials. It includes a deferred termination and error handling.

```go
ctx := context.Background()

couchdbContainer, err := couchdb.Run(ctx, "couchdb:3",
    couchdb.WithAdminCredentials("admin", "password"),
)
defer func() {
    if err := testcontainers.TerminateContainer(couchdbContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

```

--------------------------------

### Copy files to a running container using CopyFileToContainer

Source: https://golang.testcontainers.org/features/files_and_mounts

Use the CopyFileToContainer method on a running container to copy a file after the container has started. The example first starts a container with a wait script, then copies hello.sh to /scripts/hello.sh with file mode 0o700.

```go
waitForPath, err := filepath.Abs(filepath.Join(".", "testdata", "waitForHello.sh"))
require.NoError(t, err)
helloPath, err := filepath.Abs(filepath.Join(".", "testdata", "hello.sh"))
require.NoError(t, err)

ctr, err := testcontainers.Run(ctx, testBashImage,
    testcontainers.WithFiles(testcontainers.ContainerFile{
        HostFilePath:      waitForPath,
        ContainerFilePath: "/waitForHello.sh",
        FileMode:          0o700,
    }),
    testcontainers.WithCmd("bash", "/waitForHello.sh"),
)
testcontainers.CleanupContainer(t, ctr)
require.NoError(t, err)

err = ctr.CopyFileToContainer(ctx, helloPath, "/scripts/hello.sh", 0o700)

```

```bash
#!/bin/bash

file=/scripts/hello.sh

until [ -s "$file" ]
do
    sleep 0.1
done

sh $file

```

--------------------------------

### Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)

Source: https://golang.testcontainers.org/modules/memcached

The Run function is the main entrypoint to create a Memcached container. It accepts a context, a Docker image, and optional container customizers.

```APIDOC
## Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)

### Description
Creates a Memcached container using the provided Docker image and optional customization options.

### Parameters
- **ctx** (context.Context) - Required - The Go context.
- **img** (string) - Required - The Docker image to use.
- **opts** (testcontainers.ContainerCustomizer) - Optional - Variadic argument for passing options.

### Example
```go
ctx := context.Background()

memcachedContainer, err := memcached.Run(ctx, "memcached:1.6-alpine")
defer func() {
    if err := testcontainers.TerminateContainer(memcachedContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}
```
```

--------------------------------

### Create a Hello World Container

Source: https://golang.testcontainers.org/modules/socat

Runs the testcontainers/helloworld:1.2.0 container on the created network, exposing port 8080/tcp. The container is terminated in a deferred function.

```go
ctr, err := testcontainers.Run(ctx, "testcontainers/helloworld:1.2.0",
    network.WithNetwork([]string{"helloworld"}, nw),
    testcontainers.WithExposedPorts("8080/tcp"),
)
if err != nil {
    log.Printf("failed to create container: %v", err)
    return
}
defer func() {
    if err := testcontainers.TerminateContainer(ctr); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()

```

--------------------------------

### Install Memcached module with go get

Source: https://golang.testcontainers.org/modules/memcached

Adds the Memcached module to your Go dependencies. Run this command in your project directory before using the module.

```bash
go get github.com/testcontainers/testcontainers-go/modules/memcached

```

--------------------------------

### Get service names with stack.Services()

Source: https://golang.testcontainers.org/features/docker_compose

Retrieves the list of all service names defined in the compose files. Note that not all services may be correctly started.

```go
serviceNames := stack.Services()

```
Tokens:
Raw