Skip to content

Commit acffeed

Browse files
mdelapenyadanielhe4rtstevenh
authored
feat: add ScyllaDB module (#2992)
* feat(scylladb): add base packages * feat(scylladb): container implementation with file config and shard-awareness * feat(scylladb): container base test implementation with files and shard-awareness port * feat(scylladb): add makefile test runner command * feat(scylladb): add alternator integration * feat(scylladb): add WithCustomCommand and code cleanup * feat(scylladb): implementation cleanup with test coverage * docs(scylladb): add scylladb base documentation module * docs: add links to the version it was introduced * chore: add scaffolding files * chore: rename to Container * chore: run mod tidy * fix: wrong state after code generation * chore: concat strings * chore: use int * chore: calculate variable once * chore: simplify types * chore(scylladb): WithConfig standardising Co-authored-by: Steven Hartland <stevenmhartland@gmail.com> * chore(scylladb): WithConfig enhancements * chore: use uint16 for port * chore: tune up regex in wait for log See Java implementation here: https://github.com/testcontainers/testcontainers-java/blob/5af66d700e942474afabd8e550bf089196fdb5f9/modules/scylladb/src/main/java/org/testcontainers/scylladb/ScyllaDBContainer.java#L52 * chore: rename to WithConfig using an io.Reader * fixup port * chore: convert createTable into a test helper Applied to the dynamoDB module too * chore: training newline in scylladb config * docs: refine message * docs: refine message * fix: separate tests * chore: extract alternator port in examples * chore: return error in examples helper * docs: refine method comment * chore: wrap errors * docs: refine method comment * docs: document why the cluster name * fix: update tests * fix: lint * chore: wording * chore: revert dynamodb * chore: use proper format for link in comment * chore: remove double whitespace * chore: change option to receive a variadic argument of flags * chore: use newPort * chore: use net.JoinHostPort * fix: reverse order when cleaning containers in tests * chore: more descriptive error message * chore: refactor getAlternator test helper * chore: split connection host into three methods * chore: simplify option * chore: simplify wait * chore: do not run in parallel * chore: pin alternator port to 8000 --------- Co-authored-by: danielhe4rt <danielhe4rt@gmail.com> Co-authored-by: Steven Hartland <stevenmhartland@gmail.com> Co-authored-by: Daniel Reis <idanielreiss@gmail.com>
1 parent 2fffed1 commit acffeed

File tree

11 files changed

+1231
-1
lines changed

11 files changed

+1231
-1
lines changed

‎.vscode/.testcontainers-go.code-workspace‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,10 @@
189189
"name": "module / registry",
190190
"path": "../modules/registry"
191191
},
192+
{
193+
"name": "module / scylladb",
194+
"path": "../modules/scylladb"
195+
},
192196
{
193197
"name": "module / surrealdb",
194198
"path": "../modules/surrealdb"

‎docs/modules/scylladb.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# ScyllaDB
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 ScyllaDB, a NoSQL database fully compatible with Apache Cassandra and DynamoDB, allows you
8+
to create a ScyllaDB container for testing purposes.
9+
10+
## Adding this module to your project dependencies
11+
12+
Please run the following command to add the ScyllaDB module to your Go dependencies:
13+
14+
```shell
15+
go get github.com/testcontainers/testcontainers-go/modules/scylladb
16+
```
17+
18+
## Usage example
19+
20+
<!--codeinclude-->
21+
[Creating a ScyllaDB container](../../modules/scylladb/examples_test.go) inside_block:ExampleRun
22+
<!--/codeinclude-->
23+
24+
## Module Reference
25+
26+
### Run function
27+
28+
- 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>
29+
30+
The ScyllaDB module exposes one entrypoint function to create the ScyllaDB container, and this function receives three parameters:
31+
32+
```golang
33+
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ScyllaDBContainer, error)
34+
```
35+
36+
- `context.Context`, the Go context.
37+
- `string`, the Docker image to use.
38+
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
39+
40+
!!! info
41+
By default, we add the `--developer-mode=1` flag to the ScyllaDB container to disable the various checks Scylla
42+
performs.
43+
Also in scenarios in which static partitioning is not desired - like mostly-idle cluster without hard latency
44+
requirements, the `--overprovisioned` command-line option is recommended. This enables certain optimizations for ScyllaDB
45+
to run efficiently in an overprovisioned environment. You can change it by using the `WithCustomCommand` function.
46+
47+
### Container Options
48+
49+
When starting the ScyllaDB container, you can pass options in a variadic way to configure it.
50+
51+
#### Image
52+
53+
If you need to set a different ScyllaDB Docker image, you can set a valid Docker image as the second argument in the
54+
`Run` function. Eg:
55+
56+
```golang
57+
scylladb.Run(context.Background(), "scylladb/scylla:6.2.1")
58+
// OR
59+
scylladb.Run(context.Background(), "scylladb/scylla:5.6")
60+
```
61+
62+
{% include "../features/common_functional_options.md" %}
63+
64+
#### With Database Configuration File (scylla.yaml)
65+
66+
- 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>
67+
68+
In the case you have a custom config file for ScyllaDB, it's possible to copy that file into the container before it's
69+
started, using the `WithConfig(r io.Reader)` function.
70+
71+
<!--codeinclude-->
72+
[With Config YAML](../../modules/scylladb/examples_test.go) inside_block:runScyllaDBContainerWithConfig
73+
<!--/codeinclude-->
74+
!!!warning
75+
You should provide a valid ScyllaDB configuration file as an `io.Reader` when using the function, otherwise the container will fail to
76+
start. The configuration file should be a valid YAML file and follows
77+
the [ScyllaDB configuration file](https://github.com/scylladb/scylladb/blob/master/conf/scylla.yaml).
78+
79+
#### With Shard Awareness
80+
81+
- 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>
82+
83+
If you want to test ScyllaDB with shard awareness, you can use the `WithShardAwareness` function. This function will
84+
configure the ScyllaDB container to use the `19042` port and ask the container to wait until the port is ready.
85+
86+
<!--codeinclude-->
87+
[With Shard Awareness](../../modules/scylladb/examples_test.go) inside_block:runScyllaDBContainerWithShardAwareness
88+
<!--/codeinclude-->
89+
90+
#### With Alternator (DynamoDB Compatible API)
91+
92+
- 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>
93+
94+
If you want to test ScyllaDB with the Alternator API, you can use the `WithAlternator` function. This function will
95+
configure the ScyllaDB container to use the port any port you want and ask the container to wait until the port is
96+
ready.
97+
By default, you can choose the port `8000`.
98+
99+
<!--codeinclude-->
100+
[With Alternator API](../../modules/scylladb/examples_test.go) inside_block:runScyllaDBContainerWithAlternator
101+
<!--/codeinclude-->
102+
103+
#### With Custom Commands
104+
105+
- 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>
106+
107+
If you need to pass any flag to the ScyllaDB container, you can use the `WithCustomCommand` function. This also rewrites
108+
predefined commands like `--developer-mode=1`. You can check
109+
the [ScyllaDB Docker Best Practices](https://opensource.docs.scylladb.com/stable/operating-scylla/procedures/tips/best-practices-scylla-on-docker.html) for more information.
110+
111+
<!--codeinclude-->
112+
[With Custom Commands](../../modules/scylladb/examples_test.go) inside_block:runScyllaDBContainerWithCustomCommands
113+
<!--/codeinclude-->
114+
115+
### Container Methods
116+
117+
The ScyllaDB container exposes the following methods:
118+
119+
#### ConnectionHost methods
120+
121+
- 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>
122+
123+
There exist three methods to get the host and port of the ScyllaDB container, depending on the feature you want.
124+
125+
If you just want to test it with a single node and a single core, you can use the `NonShardAwareConnectionHost` method. However, if you're planning
126+
to use more than one core, you should use the `ShardAwareConnectionHost` method, which uses the **shard-awareness** `19042` port.
127+
128+
Else, if you're planning to use the **Alternator** API, you should use the `AlternatorConnectionHost` method,
129+
which uses the default port `8000`.
130+
131+
<!--codeinclude-->
132+
[Non-shard-aware connection host](../../modules/scylladb/examples_test.go) inside_block:scyllaDbNonShardAwareConnectionHost
133+
[Shard-aware connection host](../../modules/scylladb/examples_test.go) inside_block:scyllaDbShardAwareConnectionHost
134+
[Alternator host](../../modules/scylladb/examples_test.go) inside_block:scyllaDbAlternatorConnectionHost
135+
<!--/codeinclude-->

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,7 @@ nav:
111111
- modules/redis.md
112112
- modules/redpanda.md
113113
- modules/registry.md
114+
- modules/scylladb.md
114115
- modules/surrealdb.md
115116
- modules/valkey.md
116117
- modules/vault.md

‎modules/scylladb/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-scylladb

0 commit comments

Comments
 (0)