0
# Container Management
1

2
Docker container lifecycle management for database testing environments with support for multiple database systems, configurable timeouts, and automated resource cleanup.
3

4
## Capabilities
5

6
### DatabaseContainerManager
7

8
Main class for managing Docker containers used in database integration testing.
9

10
```scala { .api }
11
/**
12
 * Manages Docker container lifecycle for database testing
13
 * Handles container creation, startup, monitoring, and cleanup
14
 */
15
class DatabaseContainerManager {
16
  
17
  /**
18
   * Create a new database container
19
   * @param dbType Database type (postgresql, mysql, mariadb, oracle, db2, sqlserver)
20
   * @param imageTag Docker image tag to use
21
   * @return Container ID of the created container
22
   */
23
  def createContainer(dbType: String, imageTag: String): String
24
  
25
  /**
26
   * Start a specific container and wait for it to be ready
27
   * @param containerId Container ID to start
28
   * @return ContainerInfo with connection details
29
   */
30
  def startContainer(containerId: String): ContainerInfo
31
  
32
  /**
33
   * Stop a running container
34
   * @param containerId Container ID to stop
35
   */
36
  def stopContainer(containerId: String): Unit
37
  
38
  /**
39
   * Get connection information for a running container
40
   * @param containerId Container ID
41
   * @return ConnectionInfo with JDBC details
42
   */
43
  def getConnectionInfo(containerId: String): ConnectionInfo
44
  
45
  /**
46
   * Configure timeout settings for container operations
47
   * @param timeout Maximum time to wait for container operations
48
   */
49
  def configureTimeout(timeout: Duration): Unit
50
  
51
  /**
52
   * Check if a container is running and healthy
53
   * @param containerId Container ID to check
54
   * @return true if container is healthy, false otherwise
55
   */
56
  def isContainerHealthy(containerId: String): Boolean
57
  
58
  /**
59
   * Get logs from a container for debugging
60
   * @param containerId Container ID
61
   * @return Container logs as string
62
   */
63
  def getContainerLogs(containerId: String): String
64
  
65
  /**
66
   * Remove a container (running or stopped)
67
   * @param containerId Container ID to remove
68
   */
69
  def removeContainer(containerId: String): Unit
70
}
71
```
72

73
**Usage Examples:**
74

75
```scala
76
val containerManager = new DatabaseContainerManager()
77

78
// Configure timeout
79
containerManager.configureTimeout(Duration.ofMinutes(5))
80

81
// Create and start PostgreSQL container
82
val containerId = containerManager.createContainer("postgresql", "postgres:13")
83
val containerInfo = containerManager.startContainer(containerId)
84

85
// Use connection info
86
val df = spark.read
87
  .format("jdbc")
88
  .option("url", containerInfo.jdbcUrl)
89
  .option("user", containerInfo.username)
90
  .option("password", containerInfo.password)
91
  .option("dbtable", "information_schema.tables")
92
  .load()
93

94
// Cleanup
95
containerManager.stopContainer(containerId)
96
containerManager.removeContainer(containerId)
97
```
98

99
### Container Creation
100

101
Methods for creating database-specific Docker containers.
102

103
```scala { .api }
104
/**
105
 * Create a new database container with default settings
106
 * @param dbType Database type identifier
107
 * @param imageTag Docker image with tag
108
 * @return Container ID string
109
 */
110
def createContainer(dbType: String, imageTag: String): String
111

112
/**
113
 * Create container with custom configuration
114
 * @param dbType Database type
115
 * @param imageTag Docker image with tag  
116
 * @param config Custom container configuration
117
 * @return Container ID string
118
 */
119
def createContainer(dbType: String, imageTag: String, config: ContainerConfig): String
120

121
/**
122
 * Create container with environment variables
123
 * @param dbType Database type
124
 * @param imageTag Docker image with tag
125
 * @param envVars Environment variables for the container
126
 * @return Container ID string
127
 */
128
def createContainerWithEnv(dbType: String, imageTag: String, envVars: Map[String, String]): String
129
```
130

131
### Container Lifecycle
132

133
Methods for managing the container lifecycle.
134

135
```scala { .api }
136
/**
137
 * Start container and wait for database to be ready
138
 * @param containerId Container to start
139
 * @return ContainerInfo with connection details
140
 */
141
def startContainer(containerId: String): ContainerInfo
142

143
/**
144
 * Stop a running container gracefully
145
 * @param containerId Container to stop
146
 */
147
def stopContainer(containerId: String): Unit
148

149
/**
150
 * Force stop a container (if graceful stop fails)
151
 * @param containerId Container to force stop
152
 */
153
def forceStopContainer(containerId: String): Unit
154

155
/**
156
 * Restart a container
157
 * @param containerId Container to restart
158
 * @return Updated ContainerInfo
159
 */
160
def restartContainer(containerId: String): ContainerInfo
161
```
162

163
### Container Monitoring
164

165
Methods for monitoring container health and status.
166

167
```scala { .api }
168
/**
169
 * Check if container is running and healthy
170
 * @param containerId Container to check
171
 * @return true if healthy, false otherwise
172
 */
173
def isContainerHealthy(containerId: String): Boolean
174

175
/**
176
 * Get container status information
177
 * @param containerId Container to inspect
178
 * @return ContainerStatus with detailed information
179
 */
180
def getContainerStatus(containerId: String): ContainerStatus
181

182
/**
183
 * Wait for container to become healthy
184
 * @param containerId Container to wait for
185
 * @param timeout Maximum time to wait
186
 * @return true if became healthy within timeout
187
 */
188
def waitForHealthy(containerId: String, timeout: Duration): Boolean
189

190
/**
191
 * Get container resource usage statistics
192
 * @param containerId Container to inspect
193
 * @return ResourceStats with CPU, memory usage
194
 */
195
def getResourceStats(containerId: String): ResourceStats
196
```
197

198
### Database-Specific Configuration
199

200
Pre-configured settings for supported database systems.
201

202
```scala { .api }
203
/**
204
 * Get default configuration for a database type
205
 * @param dbType Database type
206
 * @return Default ContainerConfig for the database
207
 */
208
def getDefaultConfig(dbType: String): ContainerConfig
209

210
/**
211
 * Get default environment variables for a database type
212
 * @param dbType Database type
213
 * @return Map of environment variables
214
 */
215
def getDefaultEnvVars(dbType: String): Map[String, String]
216

217
/**
218
 * Get default port mapping for a database type
219
 * @param dbType Database type
220
 * @return Default port number
221
 */
222
def getDefaultPort(dbType: String): Int
223

224
/**
225
 * Get JDBC driver class for a database type
226
 * @param dbType Database type
227
 * @return JDBC driver class name
228
 */
229
def getDriverClass(dbType: String): String
230
```
231

232
## Types
233

234
```scala { .api }
235
case class ContainerInfo(
236
  containerId: String,
237
  jdbcUrl: String,
238
  hostPort: Int,
239
  username: String,
240
  password: String,
241
  driverClass: String
242
)
243

244
case class ContainerConfig(
245
  memoryLimit: String,
246
  cpuLimit: Double,
247
  portBindings: Map[Int, Int],
248
  volumeMounts: Map[String, String],
249
  networkMode: String
250
)
251

252
case class ContainerStatus(
253
  containerId: String,
254
  status: String,
255
  isRunning: Boolean,
256
  isHealthy: Boolean,
257
  startedAt: Instant,
258
  finishedAt: Option[Instant]
259
)
260

261
case class ResourceStats(
262
  cpuUsagePercent: Double,
263
  memoryUsageMB: Long,
264
  memoryLimitMB: Long,
265
  networkRxBytes: Long,
266
  networkTxBytes: Long
267
)
268
```
269

270
## Supported Database Types
271

272
The container manager supports the following database systems:
273

274
- **postgresql**: PostgreSQL database
275
- **mysql**: MySQL database  
276
- **mariadb**: MariaDB database
277
- **oracle**: Oracle Database
278
- **db2**: IBM DB2 database
279
- **sqlserver**: Microsoft SQL Server
280

281
Each database type has pre-configured default settings for container creation, environment variables, and connection parameters.