feat: add TiDB module

.github/dependabot.yml

@@ -71,6 +71,7 @@ updates:
         - /modules/socat
         - /modules/solace
         - /modules/surrealdb
+        - /modules/tidb
         - /modules/toxiproxy
         - /modules/valkey
         - /modules/vault

docs/modules/tidb.md

@@ -0,0 +1,67 @@
+# TiDB
+
+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 TiDB. TiDB is a MySQL-compatible distributed SQL database.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the TiDB module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/tidb
+```
+
+## Usage example
+
+<!--codeinclude--> 
+[Creating a TiDB container](../../modules/tidb/examples_test.go) inside_block:runTiDBContainer
+<!--/codeinclude-->
+
+## Module Reference
+
+### Run function
+
+The TiDB module exposes one entrypoint function to create the container, and this function receives three parameters:
+
+```golang
+func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
+```
+
+- `context.Context`, the Go context.
+- `string`, the Docker image to use.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+#### Image
+
+Use the second argument in the `Run` function to set a valid Docker image.
+In example: `Run(context.Background(), "pingcap/tidb:v8.4.0")`.
+
+### Container Options
+
+When starting the TiDB container, you can pass options in a variadic way to configure it.
+
+!!!tip
+    You can find all the available configuration and environment variables for the TiDB Docker image on [Docker Hub](https://hub.docker.com/r/pingcap/tidb).
+
+!!!info
+    TiDB is MySQL-compatible, so you can use any MySQL driver (e.g. `github.com/go-sql-driver/mysql`) to connect and execute SQL statements after the container is ready.
+
+{% include "../features/common_functional_options_list.md" %}
+
+### Container Methods
+
+#### ConnectionString
+
+This method returns the connection string to connect to the TiDB container, using the default `4000` port.
+It's possible to pass extra parameters to the connection string, e.g. `charset=utf8mb4`, in a variadic way.
+
+<!--codeinclude-->
+[Get connection string](../../modules/tidb/tidb_test.go) inside_block:connectionString
+<!--/codeinclude-->
+
+#### MustConnectionString
+
+Same as `ConnectionString`, but panics if an error occurs while getting the connection string.

mkdocs.yml

@@ -129,6 +129,7 @@ nav:
         - modules/socat.md
         - modules/solace.md
         - modules/surrealdb.md
+        - modules/tidb.md
         - modules/toxiproxy.md
         - modules/valkey.md
         - modules/vault.md

modules/tidb/Makefile

@@ -0,0 +1,5 @@
+include ../../commons-test.mk
+
+.PHONY: test
+test:
+	$(MAKE) test-tidb

modules/tidb/examples_test.go

@@ -0,0 +1,90 @@
+package tidb_test
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"log"
+
+	_ "github.com/go-sql-driver/mysql"
+
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/tidb"
+)
+
+func ExampleRun() {
+	// runTiDBContainer {
+	ctx := context.Background()
+
+	ctr, err := tidb.Run(ctx,
+		"pingcap/tidb:v8.4.0",
+	)
+	defer func() {
+		if err := testcontainers.TerminateContainer(ctr); err != nil {
+			log.Printf("failed to terminate container: %s", err)
+		}
+	}()
+	if err != nil {
+		log.Printf("failed to start container: %s", err)
+		return
+	}
+	// }
+
+	state, err := ctr.State(ctx)
+	if err != nil {
+		log.Printf("failed to get container state: %s", err)
+		return
+	}
+
+	fmt.Println(state.Running)
+
+	// Output:
+	// true
+}
+
+func ExampleRun_connect() {
+	ctx := context.Background()
+
+	ctr, err := tidb.Run(ctx,
+		"pingcap/tidb:v8.4.0",
+	)
+	defer func() {
+		if err := testcontainers.TerminateContainer(ctr); err != nil {
+			log.Printf("failed to terminate container: %s", err)
+		}
+	}()
+	if err != nil {
+		log.Printf("failed to start container: %s", err)
+		return
+	}
+
+	connectionString, err := ctr.ConnectionString(ctx)
+	if err != nil {
+		log.Printf("failed to get connection string: %s", err)
+		return
+	}
+
+	db, err := sql.Open("mysql", connectionString)
+	if err != nil {
+		log.Printf("failed to connect to TiDB: %s", err)
+		return
+	}
+	defer db.Close()
+
+	if err = db.Ping(); err != nil {
+		log.Printf("failed to ping TiDB: %s", err)
+		return
+	}
+
+	var result int
+	row := db.QueryRow("SELECT 1")
+	if err = row.Scan(&result); err != nil {
+		log.Printf("failed to scan row: %s", err)
+		return
+	}
+
+	fmt.Println(result)
+
+	// Output:
+	// 1
+}

modules/tidb/go.mod

@@ -0,0 +1,70 @@
+module github.com/testcontainers/testcontainers-go/modules/tidb
+
+go 1.25.0
+
+toolchain go1.25.7
+
+require (
+	github.com/go-sql-driver/mysql v1.7.1
+	github.com/stretchr/testify v1.11.1
+	github.com/testcontainers/testcontainers-go v0.40.0
+)
+
+require (
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/containerd/errdefs v1.0.0 // indirect
+	github.com/containerd/errdefs/pkg v0.3.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/containerd/platforms v0.2.1 // indirect
+	github.com/cpuguy83/dockercfg v0.3.2 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/docker v28.5.2+incompatible // indirect
+	github.com/docker/go-connections v0.6.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/ebitengine/purego v0.9.1 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/klauspost/compress v1.18.0 // indirect
+	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/go-archive v0.1.0 // indirect
+	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/user v0.4.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/moby/term v0.5.0 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.1 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
+	github.com/shirou/gopsutil/v4 v4.25.12 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
+	github.com/tklauser/go-sysconf v0.3.16 // indirect
+	github.com/tklauser/numcpus v0.11.0 // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 // indirect
+	go.opentelemetry.io/otel v1.41.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.41.0 // indirect
+	go.opentelemetry.io/otel/metric v1.41.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.41.0 // indirect
+	go.opentelemetry.io/otel/trace v1.41.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.9.0 // indirect
+	golang.org/x/crypto v0.45.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/testcontainers/testcontainers-go => ../..