0
# Database Containers
1

2
Pre-configured containers for popular databases including relational databases (PostgreSQL, MySQL), NoSQL databases (MongoDB, Cassandra), and specialized data stores. Each container provides service-specific configuration options, connection utilities, and client integration.
3

4
## Capabilities
5

6
### PostgreSQL Container
7

8
PostgreSQL relational database container with automatic database, user, and password configuration, supporting multiple PostgreSQL versions and client drivers.
9

10
```python { .api }
11
class PostgresContainer:
12
    def __init__(
13
        self,
14
        image: str = "postgres:latest",
15
        port: int = 5432,
16
        username: Optional[str] = None,
17
        password: Optional[str] = None,
18
        dbname: Optional[str] = None,
19
        driver: str = "psycopg2",
20
        **kwargs: Any
21
    ):
22
        """
23
        Initialize PostgreSQL container.
24
        
25
        Args:
26
            image: PostgreSQL Docker image
27
            port: PostgreSQL port (default 5432)
28
            username: Database username (auto-generated if None)
29
            password: Database password (auto-generated if None)
30
            dbname: Database name (auto-generated if None)
31
            driver: Database driver for connection URL
32
            **kwargs: Additional container options
33
        """
34

35
    def get_connection_url(self, host: Optional[str] = None, driver: Optional[str] = None) -> str:
36
        """
37
        Get PostgreSQL connection URL.
38
        
39
        Args:
40
            host: Override host (uses container host if None)
41
            driver: Override driver (uses instance driver if None)
42
            
43
        Returns:
44
            PostgreSQL connection URL string
45
        """
46
```
47

48
### MySQL Container
49

50
MySQL relational database container with configurable authentication, database initialization, and support for different MySQL variants.
51

52
```python { .api }
53
class MySqlContainer:
54
    def __init__(
55
        self,
56
        image: str = "mysql:latest",
57
        dialect: Optional[str] = None,
58
        username: Optional[str] = None,
59
        root_password: Optional[str] = None,
60
        password: Optional[str] = None,
61
        dbname: Optional[str] = None,
62
        port: int = 3306,
63
        seed: Optional[str] = None,
64
        **kwargs: Any
65
    ):
66
        """
67
        Initialize MySQL container.
68
        
69
        Args:
70
            image: MySQL Docker image
71
            dialect: SQL dialect (mysql, mysql+pymysql)
72
            username: Database username
73
            root_password: Root user password
74
            password: User password
75
            dbname: Database name
76
            port: MySQL port (default 3306)
77
            seed: SQL file path for database initialization
78
            **kwargs: Additional container options
79
        """
80

81
    def get_connection_url(self) -> str:
82
        """
83
        Get MySQL connection URL.
84
        
85
        Returns:
86
            MySQL connection URL string
87
        """
88
```
89

90
### MongoDB Container
91

92
MongoDB NoSQL document database container with authentication support and direct client integration.
93

94
```python { .api }
95
class MongoDbContainer:
96
    def __init__(
97
        self,
98
        image: str = "mongo:latest",
99
        port: int = 27017,
100
        username: Optional[str] = None,
101
        password: Optional[str] = None,
102
        dbname: Optional[str] = None,
103
        **kwargs: Any
104
    ):
105
        """
106
        Initialize MongoDB container.
107
        
108
        Args:
109
            image: MongoDB Docker image
110
            port: MongoDB port (default 27017)
111
            username: Database username
112
            password: Database password
113
            dbname: Database name
114
            **kwargs: Additional container options
115
        """
116

117
    def get_connection_url(self) -> str:
118
        """
119
        Get MongoDB connection URL.
120
        
121
        Returns:
122
            MongoDB connection URL string
123
        """
124

125
    def get_connection_client(self):
126
        """
127
        Get configured PyMongo client.
128
        
129
        Returns:
130
            PyMongo MongoClient instance
131
        """
132
```
133

134
### ClickHouse Container
135

136
ClickHouse analytical database container optimized for OLAP workloads with configurable users and databases.
137

138
```python { .api }
139
class ClickHouseContainer:
140
    def __init__(
141
        self,
142
        image: str = "clickhouse/clickhouse-server:latest",
143
        port: int = 8123,
144
        username: str = "default",
145
        password: str = "",
146
        dbname: str = "default",
147
        **kwargs: Any
148
    ):
149
        """
150
        Initialize ClickHouse container.
151
        
152
        Args:
153
            image: ClickHouse Docker image
154
            port: HTTP port (default 8123)
155
            username: Database username
156
            password: Database password
157
            dbname: Database name
158
            **kwargs: Additional container options
159
        """
160

161
    def get_connection_url(self) -> str:
162
        """
163
        Get ClickHouse connection URL.
164
        
165
        Returns:
166
            ClickHouse connection URL string
167
        """
168
```
169

170
### Neo4j Container
171

172
Neo4j graph database container with authentication configuration and Bolt protocol support.
173

174
```python { .api }
175
class Neo4jContainer:
176
    def __init__(
177
        self,
178
        image: str = "neo4j:latest",
179
        username: str = "neo4j",
180
        password: str = "test",
181
        **kwargs: Any
182
    ):
183
        """
184
        Initialize Neo4j container.
185
        
186
        Args:
187
            image: Neo4j Docker image
188
            username: Database username
189
            password: Database password
190
            **kwargs: Additional container options
191
        """
192

193
    def get_connection_url(self) -> str:
194
        """
195
        Get Neo4j Bolt connection URL.
196
        
197
        Returns:
198
            Neo4j Bolt connection URL string
199
        """
200
```
201

202
### Cassandra Container
203

204
Apache Cassandra NoSQL wide-column database container with cluster configuration support.
205

206
```python { .api }
207
class CassandraContainer:
208
    def __init__(
209
        self,
210
        image: str = "cassandra:latest",
211
        **kwargs: Any
212
    ):
213
        """
214
        Initialize Cassandra container.
215
        
216
        Args:
217
            image: Cassandra Docker image
218
            **kwargs: Additional container options
219
        """
220

221
    def get_connection_url(self) -> str:
222
        """
223
        Get Cassandra connection URL.
224
        
225
        Returns:
226
            Cassandra connection URL string
227
        """
228
```
229

230
### InfluxDB Container
231

232
InfluxDB time-series database container with configurable authentication and database initialization.
233

234
```python { .api }
235
class InfluxDbContainer:
236
    def __init__(
237
        self,
238
        image: str = "influxdb:latest",
239
        port: int = 8086,
240
        username: Optional[str] = None,
241
        password: Optional[str] = None,
242
        dbname: Optional[str] = None,
243
        **kwargs: Any
244
    ):
245
        """
246
        Initialize InfluxDB container.
247
        
248
        Args:
249
            image: InfluxDB Docker image
250
            port: InfluxDB port (default 8086)
251
            username: Database username
252
            password: Database password
253
            dbname: Database name
254
            **kwargs: Additional container options
255
        """
256

257
    def get_connection_url(self) -> str:
258
        """
259
        Get InfluxDB connection URL.
260
        
261
        Returns:
262
            InfluxDB connection URL string
263
        """
264
```
265

266
### Microsoft SQL Server Container
267

268
Microsoft SQL Server relational database container with SA authentication and database configuration.
269

270
```python { .api }
271
class SqlServerContainer:
272
    def __init__(
273
        self,
274
        image: str = "mcr.microsoft.com/mssql/server:latest",
275
        password: Optional[str] = None,
276
        **kwargs: Any
277
    ):
278
        """
279
        Initialize SQL Server container.
280
        
281
        Args:
282
            image: SQL Server Docker image
283
            password: SA user password
284
            **kwargs: Additional container options
285
        """
286

287
    def get_connection_url(self) -> str:
288
        """
289
        Get SQL Server connection URL.
290
        
291
        Returns:
292
            SQL Server connection URL string
293
        """
294
```
295

296
### Oracle Free Container
297

298
Oracle Database Free (formerly Oracle XE) container for Oracle database testing.
299

300
```python { .api }
301
class OracleDbContainer:
302
    def __init__(
303
        self,
304
        image: str = "gvenzl/oracle-free:latest",
305
        username: Optional[str] = None,
306
        password: Optional[str] = None,
307
        **kwargs: Any
308
    ):
309
        """
310
        Initialize Oracle Database container.
311
        
312
        Args:
313
            image: Oracle Database Docker image
314
            username: Database username
315
            password: Database password
316
            **kwargs: Additional container options
317
        """
318

319
    def get_connection_url(self) -> str:
320
        """
321
        Get Oracle Database connection URL.
322
        
323
        Returns:
324
            Oracle Database connection URL string
325
        """
326
```
327

328
### ArangoDB Container
329

330
ArangoDB multi-model NoSQL database container supporting documents, graphs, and search.
331

332
```python { .api }
333
class ArangoDbContainer:
334
    def __init__(
335
        self,
336
        image: str = "arangodb:latest",
337
        username: str = "root",
338
        password: Optional[str] = None,
339
        **kwargs: Any
340
    ):
341
        """
342
        Initialize ArangoDB container.
343
        
344
        Args:
345
            image: ArangoDB Docker image
346
            username: Database username
347
            password: Database password
348
            **kwargs: Additional container options
349
        """
350

351
    def get_connection_url(self) -> str:
352
        """
353
        Get ArangoDB connection URL.
354
        
355
        Returns:
356
            ArangoDB connection URL string
357
        """
358
```
359

360
### DB2 Container
361

362
IBM DB2 database container for enterprise database testing.
363

364
```python { .api }
365
class Db2Container:
366
    def __init__(
367
        self,
368
        image: str = "ibmcom/db2:latest",
369
        username: Optional[str] = None,
370
        password: Optional[str] = None,
371
        dbname: Optional[str] = None,
372
        **kwargs: Any
373
    ):
374
        """
375
        Initialize DB2 container.
376
        
377
        Args:
378
            image: DB2 Docker image  
379
            username: Database username
380
            password: Database password
381
            dbname: Database name
382
            **kwargs: Additional container options
383
        """
384

385
    def get_connection_url(self) -> str:
386
        """
387
        Get DB2 connection URL.
388
        
389
        Returns:
390
            DB2 connection URL string
391
        """
392
```
393

394
### Scylla Container
395

396
Scylla high-performance Cassandra-compatible NoSQL database container.
397

398
```python { .api }
399
class ScyllaContainer:
400
    def __init__(
401
        self,
402
        image: str = "scylladb/scylla:latest",
403
        **kwargs: Any
404
    ):
405
        """
406
        Initialize Scylla container.
407
        
408
        Args:
409
            image: Scylla Docker image
410
            **kwargs: Additional container options
411
        """
412

413
    def get_connection_url(self) -> str:
414
        """
415
        Get Scylla connection URL.
416
        
417
        Returns:
418
            Scylla connection URL string
419
        """
420
```
421

422
## Usage Examples
423

424
### PostgreSQL Integration
425

426
```python
427
from testcontainers.postgres import PostgresContainer
428
import psycopg2
429

430
with PostgresContainer("postgres:13") as postgres:
431
    # Get connection details
432
    connection_url = postgres.get_connection_url()
433
    
434
    # Connect using psycopg2
435
    conn = psycopg2.connect(connection_url)
436
    cursor = conn.cursor()
437
    
438
    # Execute queries
439
    cursor.execute("CREATE TABLE users (id SERIAL PRIMARY KEY, email VARCHAR(255))")
440
    cursor.execute("INSERT INTO users (email) VALUES (%s)", ("test@example.com",))
441
    conn.commit()
442
    
443
    cursor.execute("SELECT * FROM users")
444
    users = cursor.fetchall()
445
    print(users)
446
    
447
    conn.close()
448
```
449

450
### MongoDB Integration
451

452
```python
453
from testcontainers.mongodb import MongoDbContainer
454

455
with MongoDbContainer("mongo:4.4") as mongo:
456
    # Get MongoDB client
457
    client = mongo.get_connection_client()
458
    
459
    # Use the database
460
    db = client.test_database
461
    collection = db.test_collection
462
    
463
    # Insert document
464
    result = collection.insert_one({"name": "John", "age": 30})
465
    print(f"Inserted document ID: {result.inserted_id}")
466
    
467
    # Query documents
468
    users = list(collection.find({"age": {"$gte": 18}}))
469
    print(f"Found {len(users)} adult users")
470
```
471

472
### Multi-Database Setup
473

474
```python
475
from testcontainers.postgres import PostgresContainer
476
from testcontainers.redis import RedisContainer
477
from testcontainers.core.network import Network
478

479
# Create shared network for containers
480
with Network() as network:
481
    # Start multiple databases
482
    with PostgresContainer("postgres:13") as postgres, \
483
         RedisContainer("redis:6") as redis:
484
        
485
        postgres.with_network(network).with_network_aliases("postgres")
486
        redis.with_network(network).with_network_aliases("redis")
487
        
488
        # Use both databases in your application
489
        pg_url = postgres.get_connection_url()
490
        redis_client = redis.get_client()
491
        
492
        # Application logic using both databases
493
        print(f"PostgreSQL: {pg_url}")
494
        print(f"Redis client: {redis_client}")
495
```
496

497
### Custom Database Configuration
498

499
```python
500
from testcontainers.mysql import MySqlContainer
501

502
# Custom MySQL configuration
503
mysql = MySqlContainer("mysql:8.0") \
504
    .with_env("MYSQL_ROOT_PASSWORD", "rootpass") \
505
    .with_env("MYSQL_DATABASE", "app_db") \
506
    .with_env("MYSQL_USER", "app_user") \
507
    .with_env("MYSQL_PASSWORD", "app_pass") \
508
    .with_volume_mapping("./init.sql", "/docker-entrypoint-initdb.d/init.sql", "ro")
509

510
with mysql:
511
    connection_url = mysql.get_connection_url()
512
    print(f"MySQL connection: {connection_url}")
513
```