Skip to content

Commit 27f699b

Browse files
henripqtstevenhmdelapenya
authored
feat: add yugabytedb module (#2825)
* feat: add yugabytedb module * fix: documentation links * fix: codeinclude target * feat: add test example for custom methods * Update modules/yugabytedb/yugabytedb_test.go Co-authored-by: Steven Hartland <stevenmhartland@gmail.com> * Update modules/yugabytedb/yugabytedb.go Co-authored-by: Steven Hartland <stevenmhartland@gmail.com> * Update modules/yugabytedb/yugabytedb_test.go Co-authored-by: Steven Hartland <stevenmhartland@gmail.com> * fix: attended review issues * Update modules/yugabytedb/examples_test.go Co-authored-by: Steven Hartland <stevenmhartland@gmail.com> * fix: cleanup and review adjustements * fix: remove test in comments and renamed struct * feat: add documentation for options * Update modules/yugabytedb/yugabytedb_test.go Co-authored-by: Manuel de la Peña <social.mdelapenya@gmail.com> * Update modules/yugabytedb/yugabytedb_test.go Co-authored-by: Manuel de la Peña <social.mdelapenya@gmail.com> * fix: add additional wait strategy for data constraint log * fix: remove customer method for ycql config and update test code * chore: run mod tidy * chore: rename testable example to fix lint "refers to unknown field or method: Container.YCQLConfigureClusterConfig" * fix: wrong cluster addr in example test * fix: update code snippet run example --------- Co-authored-by: Steven Hartland <stevenmhartland@gmail.com> Co-authored-by: Manuel de la Peña <social.mdelapenya@gmail.com> Co-authored-by: Manuel de la Peña <mdelapenya@gmail.com>
1 parent 00e7002 commit 27f699b

File tree

12 files changed

+843
-2
lines changed

12 files changed

+843
-2
lines changed

.github/workflows/ci.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ jobs:
9494
matrix:
9595
go-version: [1.22.x, 1.x]
9696
platform: [ubuntu-latest]
97-
module: [artemis, azurite, cassandra, chroma, clickhouse, cockroachdb, compose, consul, couchbase, databend, dolt, dynamodb, elasticsearch, etcd, gcloud, grafana-lgtm, inbucket, influxdb, k3s, k6, kafka, localstack, mariadb, milvus, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, ollama, openfga, openldap, opensearch, postgres, pulsar, qdrant, rabbitmq, redis, redpanda, registry, surrealdb, valkey, vault, vearch, weaviate]
97+
module: [artemis, azurite, cassandra, chroma, clickhouse, cockroachdb, compose, consul, couchbase, databend, dolt, dynamodb, elasticsearch, etcd, gcloud, grafana-lgtm, inbucket, influxdb, k3s, k6, kafka, localstack, mariadb, milvus, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, ollama, openfga, openldap, opensearch, postgres, pulsar, qdrant, rabbitmq, redis, redpanda, registry, surrealdb, valkey, vault, vearch, weaviate, yugabytedb]
9898
uses: ./.github/workflows/ci-test-go.yml
9999
with:
100100
go-version: ${{ matrix.go-version }}

.vscode/.testcontainers-go.code-workspace

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,10 @@
201201
"name": "module / weaviate",
202202
"path": "../modules/weaviate"
203203
},
204+
{
205+
"name": "module / yugabytedb",
206+
"path": "../modules/yugabytedb"
207+
},
204208
{
205209
"name": "modulegen",
206210
"path": "../modulegen"

docs/modules/yugabytedb.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# YugabyteDB
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 yugabyteDB.
8+
9+
## Adding this module to your project dependencies
10+
11+
Please run the following command to add the yugabyteDB module to your Go dependencies:
12+
13+
```
14+
go get github.com/testcontainers/testcontainers-go/modules/yugabytedb
15+
```
16+
17+
## Usage example
18+
19+
<!--codeinclude-->
20+
[Creating a yugabyteDB container](../../modules/yugabytedb/examples_test.go) inside_block:runyugabyteDBContainer
21+
<!--/codeinclude-->
22+
23+
## Module Reference
24+
25+
### Run function
26+
27+
The yugabyteDB module exposes one entrypoint function to create the yugabyteDB container, and this function receives three parameters:
28+
29+
```golang
30+
func Run(
31+
ctx context.Context,
32+
img string,
33+
opts ...testcontainers.ContainerCustomizer,
34+
) (*Container, error)
35+
```
36+
37+
- `context.Context`, the Go context.
38+
- `string`, the Docker image to use.
39+
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
40+
41+
### Container Options
42+
43+
When starting the yugabyteDB container, you can pass options in a variadic way to configure it.
44+
45+
#### Image
46+
47+
If you need to set a different yugabyteDB Docker image, you can set a valid Docker image as the second argument in the `Run` function.
48+
E.g. `Run(context.Background(), "yugabytedb/yugabyte")`.
49+
50+
{% include "../features/common_functional_options.md" %}
51+
52+
#### Initial Database
53+
54+
By default the yugabyteDB container will start with a database named `yugabyte` and the default credentials `yugabyte` and `yugabyte`.
55+
56+
If you need to set a different database, and its credentials, you can use the `WithDatabaseName(dbName string)`, `WithDatabaseUser(dbUser string)` and `WithDatabasePassword(dbPassword string)` options.
57+
58+
#### Initial Cluster Configuration
59+
60+
By default the yugabyteDB container will start with a cluster keyspace named `yugabyte` and the default credentials `yugabyte` and `yugabyte`.
61+
62+
If you need to set a different cluster keyspace, and its credentials, you can use the `WithKeyspace(keyspace string)`, `WithUser(user string)` and `WithPassword(password string)` options.
63+
64+
### Container Methods
65+
66+
The yugabyteDB container exposes the following methods:
67+
68+
#### YSQLConnectionString
69+
70+
This method returns the connection string for the yugabyteDB container when using
71+
the YSQL query language.
72+
The connection string can then be used to connect to the yugabyteDB container using
73+
a standard PostgreSQL client.
74+
75+
<!--codeinclude-->
76+
[Create a postgres client using the connection string](../../modules/yugabytedb/examples_test.go) block:ExampleContainer_YSQLConnectionString
77+
<!--/codeinclude-->
78+
79+
### Usage examples
80+
81+
#### Usage with YSQL and gocql
82+
83+
To use the YCQL query language, you need to configure the cluster
84+
with the keyspace, user, and password.
85+
86+
By default, the yugabyteDB container will start with a cluster keyspace named `yugabyte` and the default credentials `yugabyte` and `yugabyte` but you can change it using the `WithKeyspace`, `WithUser` and `WithPassword` options.
87+
88+
In order to get the appropriate host and port to connect to the yugabyteDB container,
89+
you can use the `GetHost` and `GetMappedPort` methods on the Container struct.
90+
See the examples below:
91+
92+
<!--codeinclude-->
93+
[Create a yugabyteDB client using the cluster configuration](../../modules/yugabytedb/yugabytedb_test.go) block:TestYugabyteDB_YCQL
94+
<!--/codeinclude-->

mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,7 @@ nav:
112112
- modules/vault.md
113113
- modules/vearch.md
114114
- modules/weaviate.md
115+
- modules/yugabytedb.md
115116
- Examples:
116117
- examples/index.md
117118
- examples/nginx.md

modules/yugabytedb/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-yugabytedb
Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
package yugabytedb_test
2+
3+
import (
4+
"context"
5+
"database/sql"
6+
"fmt"
7+
"log"
8+
"net"
9+
10+
_ "github.com/lib/pq"
11+
"github.com/yugabyte/gocql"
12+
13+
"github.com/testcontainers/testcontainers-go"
14+
"github.com/testcontainers/testcontainers-go/modules/yugabytedb"
15+
)
16+
17+
func ExampleRun() {
18+
// runyugabyteDBContainer {
19+
ctx := context.Background()
20+
21+
yugabytedbContainer, err := yugabytedb.Run(
22+
ctx,
23+
"yugabytedb/yugabyte:2024.1.3.0-b105",
24+
yugabytedb.WithKeyspace("custom-keyspace"),
25+
yugabytedb.WithUser("custom-user"),
26+
yugabytedb.WithDatabaseName("custom-db"),
27+
yugabytedb.WithDatabaseUser("custom-user"),
28+
yugabytedb.WithDatabasePassword("custom-password"),
29+
)
30+
if err != nil {
31+
log.Printf("failed to start container: %s", err)
32+
return
33+
}
34+
35+
defer func() {
36+
if err := testcontainers.TerminateContainer(yugabytedbContainer); err != nil {
37+
log.Printf("failed to terminate container: %s", err)
38+
}
39+
}()
40+
// }
41+
42+
state, err := yugabytedbContainer.State(ctx)
43+
if err != nil {
44+
log.Printf("failed to get container state: %s", err)
45+
return
46+
}
47+
48+
fmt.Println(state.Running)
49+
50+
// Output: true
51+
}
52+
53+
func ExampleContainer_YSQLConnectionString() {
54+
ctx := context.Background()
55+
56+
yugabytedbContainer, err := yugabytedb.Run(
57+
ctx,
58+
"yugabytedb/yugabyte:2024.1.3.0-b105",
59+
)
60+
if err != nil {
61+
log.Printf("failed to start container: %s", err)
62+
return
63+
}
64+
65+
defer func() {
66+
if err := testcontainers.TerminateContainer(yugabytedbContainer); err != nil {
67+
log.Printf("failed to terminate container: %s", err)
68+
}
69+
}()
70+
71+
connStr, err := yugabytedbContainer.YSQLConnectionString(ctx, "sslmode=disable")
72+
if err != nil {
73+
log.Printf("failed to get connection string: %s", err)
74+
return
75+
}
76+
77+
db, err := sql.Open("postgres", connStr)
78+
if err != nil {
79+
log.Printf("failed to open connection: %s", err)
80+
return
81+
}
82+
83+
defer db.Close()
84+
85+
var i int
86+
row := db.QueryRowContext(ctx, "SELECT 1")
87+
if err := row.Scan(&i); err != nil {
88+
log.Printf("failed to scan row: %s", err)
89+
return
90+
}
91+
92+
fmt.Println(i)
93+
94+
// Output: 1
95+
}
96+
97+
func ExampleContainer_newCluster() {
98+
ctx := context.Background()
99+
100+
yugabytedbContainer, err := yugabytedb.Run(
101+
ctx,
102+
"yugabytedb/yugabyte:2024.1.3.0-b105",
103+
)
104+
if err != nil {
105+
log.Printf("failed to start container: %s", err)
106+
return
107+
}
108+
109+
defer func() {
110+
if err := testcontainers.TerminateContainer(yugabytedbContainer); err != nil {
111+
log.Printf("failed to terminate container: %s", err)
112+
}
113+
}()
114+
115+
yugabytedbContainerHost, err := yugabytedbContainer.Host(ctx)
116+
if err != nil {
117+
log.Printf("failed to get container host: %s", err)
118+
return
119+
}
120+
121+
yugabyteContainerPort, err := yugabytedbContainer.MappedPort(ctx, "9042/tcp")
122+
if err != nil {
123+
log.Printf("failed to get container port: %s", err)
124+
return
125+
}
126+
127+
cluster := gocql.NewCluster(net.JoinHostPort(yugabytedbContainerHost, yugabyteContainerPort.Port()))
128+
cluster.Keyspace = "yugabyte"
129+
cluster.Authenticator = gocql.PasswordAuthenticator{
130+
Username: "yugabyte",
131+
Password: "yugabyte",
132+
}
133+
134+
session, err := cluster.CreateSession()
135+
if err != nil {
136+
log.Printf("failed to create session: %s", err)
137+
return
138+
}
139+
140+
defer session.Close()
141+
142+
var i int
143+
if err := session.Query(`
144+
SELECT COUNT(*)
145+
FROM system_schema.keyspaces
146+
WHERE keyspace_name = 'yugabyte'
147+
`).Scan(&i); err != nil {
148+
log.Printf("failed to scan row: %s", err)
149+
return
150+
}
151+
152+
fmt.Println(i)
153+
154+
// Output: 1
155+
}

modules/yugabytedb/go.mod

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
module github.com/testcontainers/testcontainers-go/modules/yugabytedb
2+
3+
go 1.22
4+
5+
require (
6+
github.com/lib/pq v1.10.9
7+
github.com/stretchr/testify v1.9.0
8+
github.com/testcontainers/testcontainers-go v0.33.0
9+
github.com/yugabyte/gocql v1.6.0-yb-1
10+
)
11+
12+
require (
13+
dario.cat/mergo v1.0.0 // indirect
14+
github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
15+
github.com/Microsoft/go-winio v0.6.2 // indirect
16+
github.com/cenkalti/backoff/v4 v4.2.1 // indirect
17+
github.com/containerd/containerd v1.7.18 // indirect
18+
github.com/containerd/log v0.1.0 // indirect
19+
github.com/containerd/platforms v0.2.1 // indirect
20+
github.com/cpuguy83/dockercfg v0.3.2 // indirect
21+
github.com/davecgh/go-spew v1.1.1 // indirect
22+
github.com/distribution/reference v0.6.0 // indirect
23+
github.com/docker/docker v27.1.1+incompatible // indirect
24+
github.com/docker/go-connections v0.5.0 // indirect
25+
github.com/docker/go-units v0.5.0 // indirect
26+
github.com/felixge/httpsnoop v1.0.4 // indirect
27+
github.com/go-logr/logr v1.4.1 // indirect
28+
github.com/go-logr/stdr v1.2.2 // indirect
29+
github.com/go-ole/go-ole v1.2.6 // indirect
30+
github.com/gogo/protobuf v1.3.2 // indirect
31+
github.com/golang/snappy v0.0.3 // indirect
32+
github.com/google/uuid v1.6.0 // indirect
33+
github.com/hailocab/go-hostpool v0.0.0-20160125115350-e80d13ce29ed // indirect
34+
github.com/klauspost/compress v1.17.4 // indirect
35+
github.com/kr/text v0.2.0 // indirect
36+
github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
37+
github.com/magiconair/properties v1.8.7 // indirect
38+
github.com/moby/docker-image-spec v1.3.1 // indirect
39+
github.com/moby/patternmatcher v0.6.0 // indirect
40+
github.com/moby/sys/sequential v0.5.0 // indirect
41+
github.com/moby/sys/user v0.1.0 // indirect
42+
github.com/moby/term v0.5.0 // indirect
43+
github.com/morikuni/aec v1.0.0 // indirect
44+
github.com/opencontainers/go-digest v1.0.0 // indirect
45+
github.com/opencontainers/image-spec v1.1.0 // indirect
46+
github.com/pkg/errors v0.9.1 // indirect
47+
github.com/pmezard/go-difflib v1.0.0 // indirect
48+
github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
49+
github.com/shirou/gopsutil/v3 v3.23.12 // indirect
50+
github.com/shoenig/go-m1cpu v0.1.6 // indirect
51+
github.com/sirupsen/logrus v1.9.3 // indirect
52+
github.com/tklauser/go-sysconf v0.3.12 // indirect
53+
github.com/tklauser/numcpus v0.6.1 // indirect
54+
github.com/yusufpapurcu/wmi v1.2.3 // indirect
55+
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 // indirect
56+
go.opentelemetry.io/otel v1.24.0 // indirect
57+
go.opentelemetry.io/otel/metric v1.24.0 // indirect
58+
go.opentelemetry.io/otel/trace v1.24.0 // indirect
59+
golang.org/x/crypto v0.22.0 // indirect
60+
golang.org/x/sys v0.21.0 // indirect
61+
gopkg.in/inf.v0 v0.9.1 // indirect
62+
gopkg.in/yaml.v3 v3.0.1 // indirect
63+
)
64+
65+
replace github.com/testcontainers/testcontainers-go => ../..

0 commit comments

Comments
 (0)