feat(modules.cockroachdb) Adds cockroachdb module (#2131)

* modulegen cockroachdb init * start insecure crdb node * Method & options to docs * Use more standard naming for connection * Remove examples/cockroachdb * Cover changing default database * Drop ImageTag option to simplify * Set COCKROACH_DATABASE * Reduce API surface area * Supply user & password * Docs for password authn * Move to test-suite ahead of TLS * TLS support * Warn cant currently change user with TLS * Robust wait for by using SQL query Cockroach wasn't being consistent with log messages to use that as a reliable mechanism across the different authentication methods. This commit makes an actual SQL query to validate CRDB is correctly running. So we can make use of sql.DB driver and `wait.ForSQL` we've had to register a connection URL that includes TLS config, as there's no way to do that through standard connection strings. * Update docs/modules/cockroachdb.md Co-authored-by: Manuel de la Peña <[email protected]> * Use lifecycle to add TLS files * Bump pgx/v5 deps * Use clearer name for connection TLSConfig * Note about the possibility of a panic when starting * Update docs/modules/cockroachdb.md Co-authored-by: Manuel de la Peña <[email protected]> --------- Co-authored-by: Manuel de la Peña <[email protected]>
testcontainers · Jan 29, 2024 · 7151628 · 7151628
1 parent 8d33968
commit 7151628
Show file tree

Hide file tree

Showing 18 changed files with 823 additions and 343 deletions.
diff --git a/.github/dependabot.yml b/.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:

diff --git a/.github/workflows/ci.yml b/.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"

diff --git a/.vscode/.testcontainers-go.code-workspace b/.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"

diff --git a/RELEASING.md b/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

diff --git a/docs/examples/cockroachdb.md b/docs/examples/cockroachdb.md
diff --git a/docs/modules/cockroachdb.md b/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`.
diff --git a/examples/cockroachdb/cockroachdb.go b/examples/cockroachdb/cockroachdb.go
diff --git a/examples/cockroachdb/cockroachdb_test.go b/examples/cockroachdb/cockroachdb_test.go
diff --git a/mkdocs.yml b/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

diff --git a/examples/cockroachdb/Makefile → modules/cockroachdb/Makefile b/examples/cockroachdb/Makefile → modules/cockroachdb/Makefile