codeflash-agent/.tessl/tiles/tessl/pypi-testcontainers/docs/database-containers.md

# Database Containers

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.

## Capabilities

### PostgreSQL Container

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

```python { .api }
class PostgresContainer:
    def __init__(
        self,
        image: str = "postgres:latest",
        port: int = 5432,
        username: Optional[str] = None,
        password: Optional[str] = None,
        dbname: Optional[str] = None,
        driver: str = "psycopg2",
        **kwargs: Any
    ):
        """
        Initialize PostgreSQL container.
        
        Args:
            image: PostgreSQL Docker image
            port: PostgreSQL port (default 5432)
            username: Database username (auto-generated if None)
            password: Database password (auto-generated if None)
            dbname: Database name (auto-generated if None)
            driver: Database driver for connection URL
            **kwargs: Additional container options
        """

    def get_connection_url(self, host: Optional[str] = None, driver: Optional[str] = None) -> str:
        """
        Get PostgreSQL connection URL.
        
        Args:
            host: Override host (uses container host if None)
            driver: Override driver (uses instance driver if None)
            
        Returns:
            PostgreSQL connection URL string
        """
```

### MySQL Container

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

```python { .api }
class MySqlContainer:
    def __init__(
        self,
        image: str = "mysql:latest",
        dialect: Optional[str] = None,
        username: Optional[str] = None,
        root_password: Optional[str] = None,
        password: Optional[str] = None,
        dbname: Optional[str] = None,
        port: int = 3306,
        seed: Optional[str] = None,
        **kwargs: Any
    ):
        """
        Initialize MySQL container.
        
        Args:
            image: MySQL Docker image
            dialect: SQL dialect (mysql, mysql+pymysql)
            username: Database username
            root_password: Root user password
            password: User password
            dbname: Database name
            port: MySQL port (default 3306)
            seed: SQL file path for database initialization
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get MySQL connection URL.
        
        Returns:
            MySQL connection URL string
        """
```

### MongoDB Container

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

```python { .api }
class MongoDbContainer:
    def __init__(
        self,
        image: str = "mongo:latest",
        port: int = 27017,
        username: Optional[str] = None,
        password: Optional[str] = None,
        dbname: Optional[str] = None,
        **kwargs: Any
    ):
        """
        Initialize MongoDB container.
        
        Args:
            image: MongoDB Docker image
            port: MongoDB port (default 27017)
            username: Database username
            password: Database password
            dbname: Database name
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get MongoDB connection URL.
        
        Returns:
            MongoDB connection URL string
        """

    def get_connection_client(self):
        """
        Get configured PyMongo client.
        
        Returns:
            PyMongo MongoClient instance
        """
```

### ClickHouse Container

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

```python { .api }
class ClickHouseContainer:
    def __init__(
        self,
        image: str = "clickhouse/clickhouse-server:latest",
        port: int = 8123,
        username: str = "default",
        password: str = "",
        dbname: str = "default",
        **kwargs: Any
    ):
        """
        Initialize ClickHouse container.
        
        Args:
            image: ClickHouse Docker image
            port: HTTP port (default 8123)
            username: Database username
            password: Database password
            dbname: Database name
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get ClickHouse connection URL.
        
        Returns:
            ClickHouse connection URL string
        """
```

### Neo4j Container

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

```python { .api }
class Neo4jContainer:
    def __init__(
        self,
        image: str = "neo4j:latest",
        username: str = "neo4j",
        password: str = "test",
        **kwargs: Any
    ):
        """
        Initialize Neo4j container.
        
        Args:
            image: Neo4j Docker image
            username: Database username
            password: Database password
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get Neo4j Bolt connection URL.
        
        Returns:
            Neo4j Bolt connection URL string
        """
```

### Cassandra Container

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

```python { .api }
class CassandraContainer:
    def __init__(
        self,
        image: str = "cassandra:latest",
        **kwargs: Any
    ):
        """
        Initialize Cassandra container.
        
        Args:
            image: Cassandra Docker image
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get Cassandra connection URL.
        
        Returns:
            Cassandra connection URL string
        """
```

### InfluxDB Container

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

```python { .api }
class InfluxDbContainer:
    def __init__(
        self,
        image: str = "influxdb:latest",
        port: int = 8086,
        username: Optional[str] = None,
        password: Optional[str] = None,
        dbname: Optional[str] = None,
        **kwargs: Any
    ):
        """
        Initialize InfluxDB container.
        
        Args:
            image: InfluxDB Docker image
            port: InfluxDB port (default 8086)
            username: Database username
            password: Database password
            dbname: Database name
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get InfluxDB connection URL.
        
        Returns:
            InfluxDB connection URL string
        """
```

### Microsoft SQL Server Container

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

```python { .api }
class SqlServerContainer:
    def __init__(
        self,
        image: str = "mcr.microsoft.com/mssql/server:latest",
        password: Optional[str] = None,
        **kwargs: Any
    ):
        """
        Initialize SQL Server container.
        
        Args:
            image: SQL Server Docker image
            password: SA user password
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get SQL Server connection URL.
        
        Returns:
            SQL Server connection URL string
        """
```

### Oracle Free Container

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

```python { .api }
class OracleDbContainer:
    def __init__(
        self,
        image: str = "gvenzl/oracle-free:latest",
        username: Optional[str] = None,
        password: Optional[str] = None,
        **kwargs: Any
    ):
        """
        Initialize Oracle Database container.
        
        Args:
            image: Oracle Database Docker image
            username: Database username
            password: Database password
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get Oracle Database connection URL.
        
        Returns:
            Oracle Database connection URL string
        """
```

### ArangoDB Container

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

```python { .api }
class ArangoDbContainer:
    def __init__(
        self,
        image: str = "arangodb:latest",
        username: str = "root",
        password: Optional[str] = None,
        **kwargs: Any
    ):
        """
        Initialize ArangoDB container.
        
        Args:
            image: ArangoDB Docker image
            username: Database username
            password: Database password
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get ArangoDB connection URL.
        
        Returns:
            ArangoDB connection URL string
        """
```

### DB2 Container

IBM DB2 database container for enterprise database testing.

```python { .api }
class Db2Container:
    def __init__(
        self,
        image: str = "ibmcom/db2:latest",
        username: Optional[str] = None,
        password: Optional[str] = None,
        dbname: Optional[str] = None,
        **kwargs: Any
    ):
        """
        Initialize DB2 container.
        
        Args:
            image: DB2 Docker image  
            username: Database username
            password: Database password
            dbname: Database name
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get DB2 connection URL.
        
        Returns:
            DB2 connection URL string
        """
```

### Scylla Container

Scylla high-performance Cassandra-compatible NoSQL database container.

```python { .api }
class ScyllaContainer:
    def __init__(
        self,
        image: str = "scylladb/scylla:latest",
        **kwargs: Any
    ):
        """
        Initialize Scylla container.
        
        Args:
            image: Scylla Docker image
            **kwargs: Additional container options
        """

    def get_connection_url(self) -> str:
        """
        Get Scylla connection URL.
        
        Returns:
            Scylla connection URL string
        """
```

## Usage Examples

### PostgreSQL Integration

```python
from testcontainers.postgres import PostgresContainer
import psycopg2

with PostgresContainer("postgres:13") as postgres:
    # Get connection details
    connection_url = postgres.get_connection_url()
    
    # Connect using psycopg2
    conn = psycopg2.connect(connection_url)
    cursor = conn.cursor()
    
    # Execute queries
    cursor.execute("CREATE TABLE users (id SERIAL PRIMARY KEY, email VARCHAR(255))")
    cursor.execute("INSERT INTO users (email) VALUES (%s)", ("test@example.com",))
    conn.commit()
    
    cursor.execute("SELECT * FROM users")
    users = cursor.fetchall()
    print(users)
    
    conn.close()
```

### MongoDB Integration

```python
from testcontainers.mongodb import MongoDbContainer

with MongoDbContainer("mongo:4.4") as mongo:
    # Get MongoDB client
    client = mongo.get_connection_client()
    
    # Use the database
    db = client.test_database
    collection = db.test_collection
    
    # Insert document
    result = collection.insert_one({"name": "John", "age": 30})
    print(f"Inserted document ID: {result.inserted_id}")
    
    # Query documents
    users = list(collection.find({"age": {"$gte": 18}}))
    print(f"Found {len(users)} adult users")
```

### Multi-Database Setup

```python
from testcontainers.postgres import PostgresContainer
from testcontainers.redis import RedisContainer
from testcontainers.core.network import Network

# Create shared network for containers
with Network() as network:
    # Start multiple databases
    with PostgresContainer("postgres:13") as postgres, \
         RedisContainer("redis:6") as redis:
        
        postgres.with_network(network).with_network_aliases("postgres")
        redis.with_network(network).with_network_aliases("redis")
        
        # Use both databases in your application
        pg_url = postgres.get_connection_url()
        redis_client = redis.get_client()
        
        # Application logic using both databases
        print(f"PostgreSQL: {pg_url}")
        print(f"Redis client: {redis_client}")
```

### Custom Database Configuration

```python
from testcontainers.mysql import MySqlContainer

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

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