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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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

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}")