feat(modules.cockroachdb) Adds cockroachdb module

.github/dependabot.yml

@@ -23,13 +23,6 @@ updates:
         day: sunday
       open-pull-requests-limit: 3
       rebase-strategy: disabled
-    - package-ecosystem: gomod
-      directory: /examples/cockroachdb
-      schedule:
-        interval: monthly
-        day: sunday
-      open-pull-requests-limit: 3
-      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /examples/consul
       schedule:
@@ -79,6 +72,13 @@ updates:
         day: sunday
       open-pull-requests-limit: 3
       rebase-strategy: disabled
+    - package-ecosystem: gomod
+      directory: /modules/cockroachdb
+      schedule:
+        interval: monthly
+        day: sunday
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /modules/compose
       schedule:

.github/workflows/ci.yml

@@ -104,7 +104,7 @@ jobs:
       matrix:
         go-version: [1.20.x, 1.x]
         platform: [ubuntu-latest]
-        module: [artemis, cassandra, clickhouse, compose, couchbase, elasticsearch, gcloud, inbucket, k3s, k6, kafka, localstack, mariadb, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, openldap, postgres, pulsar, rabbitmq, redis, redpanda, vault]
+        module: [artemis, cassandra, clickhouse, cockroachdb, compose, couchbase, elasticsearch, gcloud, inbucket, k3s, k6, kafka, localstack, mariadb, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, openldap, postgres, pulsar, rabbitmq, redis, redpanda, vault]
         exclude:
           - go-version: 1.20.x
             module: compose
@@ -124,7 +124,7 @@ jobs:
     needs: test-modules
     strategy:
       matrix:
-        module: [cockroachdb, consul, nginx, toxiproxy]
+        module: [consul, nginx, toxiproxy]
     uses: ./.github/workflows/ci-test-go.yml
     with:
       go-version: "1.20.x"

.vscode/.testcontainers-go.code-workspace

@@ -5,10 +5,6 @@
             "name": "testcontainers-go",
             "path": "../"
         },
-        {
-            "name": "example / cockroachdb",
-            "path": "../examples/cockroachdb"
-        },
         {
             "name": "example / consul",
             "path": "../examples/consul"
@@ -33,6 +29,10 @@
             "name": "module / clickhouse",
             "path": "../modules/clickhouse"
         },
+        {
+            "name": "module / cockroachdb",
+            "path": "../modules/cockroachdb"
+        },
         {
             "name": "module / compose",
             "path": "../modules/compose"

RELEASING.md

@@ -150,7 +150,6 @@ git add modules/**/go.*
 git commit -m chore: use new version (v0.20.1) in modules and examples
 git tag v0.20.1
 git tag examples/bigtable/v0.20.1
-git tag examples/cockroachdb/v0.20.1
 git tag examples/consul/v0.20.1
 git tag examples/datastore/v0.20.1
 git tag examples/firestore/v0.20.1
@@ -159,6 +158,7 @@ git tag examples/nginx/v0.20.1
 git tag examples/pubsub/v0.20.1
 git tag examples/spanner/v0.20.1
 git tag examples/toxiproxy/v0.20.1
+git tag modules/cockroachdb/v0.20.1
 git tag modules/compose/v0.20.1
 git tag modules/couchbase/v0.20.1
 git tag modules/localstack/v0.20.1
@@ -178,7 +178,6 @@ git commit -m chore: prepare for next minor development cycle (0.21.0)
 git push origin main --tags
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/bigtable/@v/v0.20.1.info
-curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/cockroachdb/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/consul/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/datastore/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/firestore/@v/v0.20.1.info
@@ -187,6 +186,7 @@ curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/exampl
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/pubsub/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/spanner/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/toxiproxy/@v/v0.20.1.info
+curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/modules/cockroachdb/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/modules/compose/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/modules/couchbase/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/modules/localstack/@v/v0.20.1.info

docs/modules/cockroachdb.md

@@ -0,0 +1,81 @@
+# CockroachDB
+
+Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+## 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
+
+<!--codeinclude-->
+[Creating a CockroachDB container](../../modules/cockroachdb/examples_test.go) inside_block:runCockroachDBContainer
+<!--/codeinclude-->
+
+## Module reference
+
+The CockroachDB module exposes one entrypoint function to create the CockroachDB container, and this function receives two parameters:
+
+```golang
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*CockroachDBContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+!!!warning
+    When TLS is enabled there's a very small, unlikely chance that the underlying driver can panic when registering the driver as part of waiting for CockroachDB to be ready to accept connections. If this is repeatedly happening please open an issue.
+
+### Container Options
+
+When starting the CockroachDB container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+If you need to set a different CockroachDB Docker image, you can use `testcontainers.WithImage` with a valid Docker image
+for CockroachDB. E.g. `testcontainers.WithImage("cockroachdb/cockroach:latest-v23.1")`.
+
+{% include "../features/common_functional_options.md" %}
+
+#### Database
+
+Set the database that is created & dialled with `cockroachdb.WithDatabase`.
+
+#### Password authentication
+
+Disable insecure mode and connect with password authentication by setting `cockroachdb.WithUser` and `cockroachdb.WithPassword`.
+
+#### 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.WithTLS` lets you provide the CA certificate along with the certicate and key for the node & clients to connect with.
+Internally CockroachDB requires a client certificate for the user to connect with.
+
+A helper `cockroachdb.NewTLSConfig` exists to generate all of this for you.
+
+### 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`.

mkdocs.yml

@@ -66,6 +66,7 @@ nav:
         - modules/artemis.md
         - modules/cassandra.md
         - modules/clickhouse.md
+        - modules/cockroachdb.md
         - modules/couchbase.md
         - modules/elasticsearch.md
         - modules/gcloud.md
@@ -91,7 +92,6 @@ nav:
         - modules/vault.md
     - Examples:
         - examples/index.md
-        - examples/cockroachdb.md
         - examples/consul.md
         - examples/nginx.md
         - examples/toxiproxy.md