0
# Database Configuration
1

2
MySQL-specific configuration options including custom configuration files, environment variables, connection parameters, and timeout settings inherited from JdbcDatabaseContainer.
3

4
## Capabilities
5

6
### Connection Parameters
7

8
Configure additional JDBC URL parameters and connection behavior.
9

10
```java { .api }
11
/**
12
 * Adds a parameter to the JDBC connection URL
13
 * @param paramName Parameter name (e.g., "useSSL", "serverTimezone")
14
 * @param paramValue Parameter value (e.g., "false", "UTC")
15
 * @return Container instance for method chaining
16
 */
17
public SELF withUrlParam(String paramName, String paramValue);
18
```
19

20
**Usage Examples:**
21

22
```java
23
MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
24
    .withDatabaseName("testdb")
25
    .withUrlParam("useSSL", "false")
26
    .withUrlParam("serverTimezone", "UTC")
27
    .withUrlParam("allowPublicKeyRetrieval", "true");
28

29
mysql.start();
30

31
// JDBC URL will include the parameters:
32
// jdbc:mysql://localhost:32768/testdb?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
33
String jdbcUrl = mysql.getJdbcUrl();
34
```
35

36
### Timeout Configuration
37

38
Configure startup and connection timeout behavior.
39

40
```java { .api }
41
/**
42
 * Set startup time to allow, including image pull time, in seconds
43
 * @param startupTimeoutSeconds startup time to allow, including image pull time, in seconds
44
 * @return Container instance for method chaining
45
 */
46
public SELF withStartupTimeoutSeconds(int startupTimeoutSeconds);
47

48
/**
49
 * Set time to allow for the database to start and establish an initial connection, in seconds
50
 * @param connectTimeoutSeconds time to allow for the database to start and establish an initial connection in seconds
51
 * @return Container instance for method chaining
52
 */
53
public SELF withConnectTimeoutSeconds(int connectTimeoutSeconds);
54
```
55

56
**Usage Examples:**
57

58
```java
59
MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
60
    .withStartupTimeoutSeconds(300)  // Allow 5 minutes for startup
61
    .withConnectTimeoutSeconds(60);  // Allow 1 minute for connection
62

63
mysql.start();
64
```
65

66
### Custom MySQL Configuration
67

68
Override MySQL server configuration using custom .cnf files to control MySQL behavior.
69

70
```java { .api }
71
/**
72
 * Provides a custom MySQL configuration file override
73
 * Maps the configuration file to /etc/mysql/conf.d in the container
74
 * @param configPath Path to custom MySQL .cnf configuration file
75
 * @return Container instance for method chaining
76
 */
77
public SELF withConfigurationOverride(String configPath);
78
```
79

80
**Usage Examples:**
81

82
```java
83
// Custom configuration file: src/test/resources/mysql-config/custom.cnf
84
MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
85
    .withConfigurationOverride("mysql-config/custom.cnf");
86

87
mysql.start();
88
```
89

90
Example custom configuration file (`mysql-config/custom.cnf`):
91

92
```ini
93
[mysqld]
94
# InnoDB Configuration
95
innodb_buffer_pool_size=512M
96
innodb_log_file_size=256M
97
innodb_flush_log_at_trx_commit=2
98

99
# Connection Configuration  
100
max_connections=1000
101
wait_timeout=28800
102

103
# Query Optimization
104
query_cache_type=1
105
query_cache_size=64M
106

107
# Logging
108
slow_query_log=1
109
slow_query_log_file=/var/log/mysql/slow.log
110
long_query_time=2
111

112
# Character Set
113
character-set-server=utf8mb4
114
collation-server=utf8mb4_unicode_ci
115

116
[mysql]
117
default-character-set=utf8mb4
118
```
119

120
### Environment Variable Configuration
121

122
The container automatically configures MySQL environment variables based on the configured database settings:
123

124
- `MYSQL_DATABASE` - Set to the configured database name
125
- `MYSQL_USER` - Set to the configured username (if not root)
126
- `MYSQL_PASSWORD` - Set to the configured password
127
- `MYSQL_ROOT_PASSWORD` - Set to the configured password  
128
- `MYSQL_ALLOW_EMPTY_PASSWORD` - Set to "yes" for root user with empty password
129

130
**Example Environment Configuration:**
131

132
```java
133
MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
134
    .withDatabaseName("myapp")
135
    .withUsername("appuser")
136
    .withPassword("secret123");
137

138
// This configuration results in these environment variables:
139
// MYSQL_DATABASE=myapp
140
// MYSQL_USER=appuser  
141
// MYSQL_PASSWORD=secret123
142
// MYSQL_ROOT_PASSWORD=secret123
143
```
144

145
### Connection URL Construction
146

147
The container automatically constructs JDBC URLs with appropriate MySQL-specific parameters for secure connections.
148

149
**Default URL Parameters Added:**
150

151
- `useSSL=false` - Disables SSL for local testing (if not explicitly set)
152
- `allowPublicKeyRetrieval=true` - Allows public key retrieval for authentication
153

154
**URL Construction Logic:**
155

156
```java
157
// Base URL format
158
jdbc:mysql://{host}:{port}/{database}
159

160
// Additional parameters are appended
161
?useSSL=false&allowPublicKeyRetrieval=true&{custom_params}
162
```
163

164
**Usage Examples:**
165

166
```java
167
MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
168
    .withDatabaseName("testdb")
169
    .withUrlParam("characterEncoding", "UTF-8")
170
    .withUrlParam("useUnicode", "true");
171

172
mysql.start();
173

174
// Resulting JDBC URL:
175
// jdbc:mysql://localhost:32768/testdb?useSSL=false&allowPublicKeyRetrieval=true&characterEncoding=UTF-8&useUnicode=true
176
String jdbcUrl = mysql.getJdbcUrl();
177
```
178

179
### Container Startup Configuration
180

181
Configure container startup behavior and retry logic.
182

183
```java { .api }
184
// Default startup configuration (automatically applied)
185
// - Port 3306 is exposed and mapped to random host port
186
// - Startup attempts: 3 (with retry logic)
187
// - Health check using "SELECT 1" query
188
// - Container readiness check on successful query execution
189
```
190

191
**Internal Configuration Details:**
192

193
The container applies these configurations automatically:
194

195
1. **Port Exposure**: MySQL port 3306 is exposed and mapped to a random available host port
196
2. **Startup Attempts**: Container will attempt to start up to 3 times if initial startup fails
197
3. **Health Check**: Uses "SELECT 1" query to verify database is ready
198
4. **Environment Setup**: Configures MySQL environment variables based on provided settings
199

200
**Error Handling:**
201

202
```java
203
try {
204
    MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
205
        .withDatabaseName("testdb")
206
        .withUsername("testuser")
207
        .withPassword(""); // Empty password for non-root user will fail
208
    
209
    mysql.start(); // This will throw ContainerLaunchException
210
} catch (org.testcontainers.containers.ContainerLaunchException e) {
211
    // Handle container launch failure
212
    System.err.println("Failed to start MySQL container: " + e.getMessage());
213
    // Error: "Empty password can be used only with the root user"
214
}
215
```