Skip to content

Commit c411ba4

Browse files
iyiola-devmdelapenya
iyiola-dev
and
mdelapenya
authored
feat: add TiDB module (#3575)
Add a new Testcontainers module for TiDB, a MySQL-compatible distributed SQL database. - Container struct with Run(), ConnectionString(), MustConnectionString() - Ports 4000/tcp (MySQL protocol) and 10080/tcp (REST API) - wait.ForAll with ForListeningPort and ForHTTP(/status) readiness strategy - Tests and testable examples - Documentation and config updates (mkdocs, dependabot) - Go 1.25 / toolchain go1.25.7 Closes #3543 Co-authored-by: Manuel de la Peña <mdelapenya@gmail.com>
1 parent 6f68717 commit c411ba4

File tree

9 files changed

+583
-0
lines changed

9 files changed

+583
-0
lines changed

‎.github/dependabot.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ updates:
7272
- /modules/socat
7373
- /modules/solace
7474
- /modules/surrealdb
75+
- /modules/tidb
7576
- /modules/toxiproxy
7677
- /modules/valkey
7778
- /modules/vault

‎docs/modules/tidb.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# TiDB
2+
3+
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>
4+
5+
## Introduction
6+
7+
The Testcontainers module for TiDB. TiDB is a MySQL-compatible distributed SQL database.
8+
9+
## Adding this module to your project dependencies
10+
11+
Please run the following command to add the TiDB module to your Go dependencies:
12+
13+
```
14+
go get github.com/testcontainers/testcontainers-go/modules/tidb
15+
```
16+
17+
## Usage example
18+
19+
<!--codeinclude-->
20+
[Creating a TiDB container](../../modules/tidb/examples_test.go) inside_block:runTiDBContainer
21+
<!--/codeinclude-->
22+
23+
## Module Reference
24+
25+
### Run function
26+
27+
The TiDB module exposes one entrypoint function to create the container, and this function receives three parameters:
28+
29+
```golang
30+
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
31+
```
32+
33+
- `context.Context`, the Go context.
34+
- `string`, the Docker image to use.
35+
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
36+
37+
#### Image
38+
39+
Use the second argument in the `Run` function to set a valid Docker image.
40+
In example: `Run(context.Background(), "pingcap/tidb:v8.4.0")`.
41+
42+
### Container Options
43+
44+
When starting the TiDB container, you can pass options in a variadic way to configure it.
45+
46+
!!!tip
47+
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).
48+
49+
!!!info
50+
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.
51+
52+
{% include "../features/common_functional_options_list.md" %}
53+
54+
### Container Methods
55+
56+
#### ConnectionString
57+
58+
This method returns the connection string to connect to the TiDB container, using the default `4000` port.
59+
It's possible to pass extra parameters to the connection string, e.g. `charset=utf8mb4`, in a variadic way.
60+
61+
<!--codeinclude-->
62+
[Get connection string](../../modules/tidb/tidb_test.go) inside_block:connectionString
63+
<!--/codeinclude-->
64+
65+
#### MustConnectionString
66+
67+
Same as `ConnectionString`, but panics if an error occurs while getting the connection string.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@ nav:
130130
- modules/socat.md
131131
- modules/solace.md
132132
- modules/surrealdb.md
133+
- modules/tidb.md
133134
- modules/toxiproxy.md
134135
- modules/valkey.md
135136
- modules/vault.md

‎modules/tidb/Makefile‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
include ../../commons-test.mk
2+
3+
.PHONY: test
4+
test:
5+
$(MAKE) test-tidb

‎modules/tidb/examples_test.go‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
package tidb_test
2+
3+
import (
4+
"context"
5+
"database/sql"
6+
"fmt"
7+
"log"
8+
9+
_ "github.com/go-sql-driver/mysql"
10+
11+
"github.com/testcontainers/testcontainers-go"
12+
"github.com/testcontainers/testcontainers-go/modules/tidb"
13+
)
14+
15+
func ExampleRun() {
16+
// runTiDBContainer {
17+
ctx := context.Background()
18+
19+
ctr, err := tidb.Run(ctx,
20+
"pingcap/tidb:v8.4.0",
21+
)
22+
defer func() {
23+
if err := testcontainers.TerminateContainer(ctr); err != nil {
24+
log.Printf("failed to terminate container: %s", err)
25+
}
26+
}()
27+
if err != nil {
28+
log.Printf("failed to start container: %s", err)
29+
return
30+
}
31+
// }
32+
33+
state, err := ctr.State(ctx)
34+
if err != nil {
35+
log.Printf("failed to get container state: %s", err)
36+
return
37+
}
38+
39+
fmt.Println(state.Running)
40+
41+
// Output:
42+
// true
43+
}
44+
45+
func ExampleRun_connect() {
46+
ctx := context.Background()
47+
48+
ctr, err := tidb.Run(ctx,
49+
"pingcap/tidb:v8.4.0",
50+
)
51+
defer func() {
52+
if err := testcontainers.TerminateContainer(ctr); err != nil {
53+
log.Printf("failed to terminate container: %s", err)
54+
}
55+
}()
56+
if err != nil {
57+
log.Printf("failed to start container: %s", err)
58+
return
59+
}
60+
61+
connectionString, err := ctr.ConnectionString(ctx)
62+
if err != nil {
63+
log.Printf("failed to get connection string: %s", err)
64+
return
65+
}
66+
67+
db, err := sql.Open("mysql", connectionString)
68+
if err != nil {
69+
log.Printf("failed to connect to TiDB: %s", err)
70+
return
71+
}
72+
defer db.Close()
73+
74+
if err = db.Ping(); err != nil {
75+
log.Printf("failed to ping TiDB: %s", err)
76+
return
77+
}
78+
79+
var result int
80+
row := db.QueryRow("SELECT 1")
81+
if err = row.Scan(&result); err != nil {
82+
log.Printf("failed to scan row: %s", err)
83+
return
84+
}
85+
86+
fmt.Println(result)
87+
88+
// Output:
89+
// 1
90+
}

‎modules/tidb/go.mod‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
module github.com/testcontainers/testcontainers-go/modules/tidb
2+
3+
go 1.25.0
4+
5+
toolchain go1.25.7
6+
7+
require (
8+
github.com/go-sql-driver/mysql v1.7.1
9+
github.com/stretchr/testify v1.11.1
10+
github.com/testcontainers/testcontainers-go v0.40.0
11+
)
12+
13+
require (
14+
dario.cat/mergo v1.0.2 // indirect
15+
github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
16+
github.com/Microsoft/go-winio v0.6.2 // indirect
17+
github.com/cenkalti/backoff/v4 v4.3.0 // indirect
18+
github.com/cespare/xxhash/v2 v2.3.0 // indirect
19+
github.com/containerd/errdefs v1.0.0 // indirect
20+
github.com/containerd/errdefs/pkg v0.3.0 // indirect
21+
github.com/containerd/log v0.1.0 // indirect
22+
github.com/containerd/platforms v0.2.1 // indirect
23+
github.com/cpuguy83/dockercfg v0.3.2 // indirect
24+
github.com/davecgh/go-spew v1.1.1 // indirect
25+
github.com/distribution/reference v0.6.0 // indirect
26+
github.com/docker/docker v28.5.2+incompatible // indirect
27+
github.com/docker/go-connections v0.6.0 // indirect
28+
github.com/docker/go-units v0.5.0 // indirect
29+
github.com/ebitengine/purego v0.9.1 // indirect
30+
github.com/felixge/httpsnoop v1.0.4 // indirect
31+
github.com/go-logr/logr v1.4.3 // indirect
32+
github.com/go-logr/stdr v1.2.2 // indirect
33+
github.com/go-ole/go-ole v1.2.6 // indirect
34+
github.com/google/uuid v1.6.0 // indirect
35+
github.com/klauspost/compress v1.18.0 // indirect
36+
github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
37+
github.com/magiconair/properties v1.8.10 // indirect
38+
github.com/moby/docker-image-spec v1.3.1 // indirect
39+
github.com/moby/go-archive v0.1.0 // indirect
40+
github.com/moby/patternmatcher v0.6.0 // indirect
41+
github.com/moby/sys/sequential v0.6.0 // indirect
42+
github.com/moby/sys/user v0.4.0 // indirect
43+
github.com/moby/sys/userns v0.1.0 // indirect
44+
github.com/moby/term v0.5.0 // indirect
45+
github.com/morikuni/aec v1.0.0 // indirect
46+
github.com/opencontainers/go-digest v1.0.0 // indirect
47+
github.com/opencontainers/image-spec v1.1.1 // indirect
48+
github.com/pkg/errors v0.9.1 // indirect
49+
github.com/pmezard/go-difflib v1.0.0 // indirect
50+
github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
51+
github.com/shirou/gopsutil/v4 v4.25.12 // indirect
52+
github.com/sirupsen/logrus v1.9.3 // indirect
53+
github.com/tklauser/go-sysconf v0.3.16 // indirect
54+
github.com/tklauser/numcpus v0.11.0 // indirect
55+
github.com/yusufpapurcu/wmi v1.2.4 // indirect
56+
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
57+
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 // indirect
58+
go.opentelemetry.io/otel v1.41.0 // indirect
59+
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.41.0 // indirect
60+
go.opentelemetry.io/otel/metric v1.41.0 // indirect
61+
go.opentelemetry.io/otel/sdk v1.41.0 // indirect
62+
go.opentelemetry.io/otel/trace v1.41.0 // indirect
63+
go.opentelemetry.io/proto/otlp v1.9.0 // indirect
64+
golang.org/x/crypto v0.45.0 // indirect
65+
golang.org/x/sys v0.41.0 // indirect
66+
google.golang.org/protobuf v1.36.11 // indirect
67+
gopkg.in/yaml.v3 v3.0.1 // indirect
68+
)
69+
70+
replace github.com/testcontainers/testcontainers-go => ../..

0 commit comments

Comments
 (0)