0
# Configuration and Initialization
1

2
Configuration override capabilities and CQL script initialization for custom Cassandra setups and test data preparation.
3

4
## Capabilities
5

6
### Configuration Override
7

8
Replace the default Cassandra configuration with custom configuration files from the classpath.
9

10
```java { .api }
11
/**
12
 * Initialize Cassandra with custom overridden Cassandra configuration.
13
 * Docker effectively replaces all /etc/cassandra content with the content of config location,
14
 * so if cassandra.yaml in configLocation is absent or corrupted, Cassandra won't launch.
15
 * 
16
 * @param configLocation relative classpath with the directory that contains cassandra.yaml 
17
 *                      and other configuration files
18
 * @return CassandraContainer instance for method chaining
19
 */
20
public CassandraContainer withConfigurationOverride(String configLocation);
21
```
22

23
**Usage Examples:**
24

25
```java
26
import org.testcontainers.cassandra.CassandraContainer;
27

28
// Use custom configuration from classpath
29
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
30
    .withConfigurationOverride("my-cassandra-config");
31

32
// Configuration directory structure in src/test/resources:
33
// my-cassandra-config/
34
// ├── cassandra.yaml          (required - main configuration)
35
// ├── cassandra-rackdc.properties
36
// └── logback.xml
37
cassandra.start();
38
```
39

40
**Configuration Requirements:**
41

42
- The configuration directory must contain a valid `cassandra.yaml` file
43
- All files in the directory will replace the default `/etc/cassandra` content
44
- Configuration files must be accessible via the classpath
45
- Invalid or missing `cassandra.yaml` will cause container startup failure
46

47
**Common Configuration Use Cases:**
48

49
```java
50
// Enable authentication
51
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
52
    .withConfigurationOverride("cassandra-auth-config");
53

54
// Custom cluster settings
55
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")  
56
    .withConfigurationOverride("cassandra-cluster-config");
57

58
// Performance tuning for tests
59
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
60
    .withConfigurationOverride("cassandra-test-optimized");
61
```
62

63
### Initialization Scripts  
64

65
Execute CQL scripts after container startup to prepare test data and database schema.
66

67
```java { .api }
68
/**
69
 * Initialize Cassandra with init CQL script.
70
 * CQL script will be applied after container is started (using WaitStrategy).
71
 * 
72
 * @param initScriptPath relative classpath resource path to CQL script
73
 * @return CassandraContainer instance for method chaining
74
 */
75
public CassandraContainer withInitScript(String initScriptPath);
76
```
77

78
**Usage Examples:**
79

80
```java
81
import org.testcontainers.cassandra.CassandraContainer;
82

83
// Execute initialization script from classpath
84
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
85
    .withInitScript("init-schema.cql");
86

87
// Chain with configuration override
88
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
89
    .withConfigurationOverride("cassandra-auth-config")
90
    .withInitScript("init-with-auth.cql");
91
```
92

93
**Example Initialization Script (`init-schema.cql`):**
94

95
```sql
96
-- Create keyspace
97
CREATE KEYSPACE IF NOT EXISTS test_keyspace 
98
WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};
99

100
-- Use keyspace
101
USE test_keyspace;
102

103
-- Create table
104
CREATE TABLE IF NOT EXISTS users (
105
    id UUID PRIMARY KEY,
106
    username text,
107
    email text,
108
    created_at timestamp
109
);
110

111
-- Insert test data
112
INSERT INTO users (id, username, email, created_at) 
113
VALUES (uuid(), 'testuser', 'test@example.com', toTimestamp(now()));
114
```
115

116
**Script Execution Process:**
117

118
1. Container starts and becomes ready (via wait strategy)
119
2. Script is copied into the container as a temporary file
120
3. Script is executed using `cqlsh` command inside the container
121
4. Execution success/failure is reported via logs
122
5. Temporary script file is cleaned up
123

124
**Error Handling:**
125

126
```java
127
import org.testcontainers.ext.ScriptUtils.ScriptLoadException;
128
import org.testcontainers.ext.ScriptUtils.UncategorizedScriptException;
129

130
try (CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
131
    .withInitScript("nonexistent-script.cql")) {
132
    cassandra.start();
133
} catch (ScriptLoadException e) {
134
    // Script file not found in classpath
135
    logger.error("Init script not found", e);
136
} catch (UncategorizedScriptException e) {
137
    // CQL execution error
138
    logger.error("Init script execution failed", e);
139
}
140
```
141

142
### Combined Configuration and Initialization
143

144
Common pattern combining custom configuration with initialization scripts for complex test setups.
145

146
**Usage Example:**
147

148
```java
149
// Complete setup with authentication and test data
150
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
151
    .withConfigurationOverride("cassandra-auth-enabled")
152
    .withInitScript("setup-auth-and-data.cql");
153

154
cassandra.start();
155

156
// Connect with authentication
157
CqlSession session = CqlSession.builder()
158
    .addContactPoint(cassandra.getContactPoint())
159
    .withLocalDatacenter(cassandra.getLocalDatacenter())
160
    .withAuthCredentials(cassandra.getUsername(), cassandra.getPassword())
161
    .build();
162
```
163

164
**Execution Order:**
165

166
1. Container is created with specified Docker image
167
2. Configuration override is applied (if specified)
168
3. Container starts with custom configuration
169
4. Wait strategy ensures Cassandra is ready for connections
170
5. Initialization script is executed (if specified)
171
6. Container is ready for test connections
172

173
## Error Scenarios
174

175
### Configuration Override Errors
176

177
- `ContainerLaunchException`: Thrown when configuration directory is empty or cassandra.yaml is invalid
178
- `IllegalArgumentException`: Thrown when configuration path cannot be resolved from classpath
179

180
### Initialization Script Errors
181

182
- `ScriptLoadException`: Thrown when script file cannot be found in classpath
183
- `ScriptStatementFailedException`: Thrown when CQL statement execution fails
184
- `UncategorizedScriptException`: Thrown for general script execution errors