{"id":24698,"library":"testcontainers-postgres","title":"Testcontainers PostgreSQL Module","description":"PostgreSQL component of testcontainers-python. Provides a lightweight, disposable PostgreSQL container for integration testing. Current version: 0.0.1rc1, requires Python >=3.7. Release cadence: follows the main testcontainers-python library (major releases every few months).","status":"active","version":"0.0.1rc1","language":"python","source_language":"en","source_url":"https://github.com/testcontainers/testcontainers-python","tags":["testcontainers","postgresql","testing","container","integration-test"],"install":[{"cmd":"pip install testcontainers-postgres","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Required base package for container lifecycle management","package":"testcontainers-core","optional":false},{"reason":"Required for PostgreSQL driver; if not installed, you'll get import errors","package":"psycopg2-binary","optional":true},{"reason":"Commonly used with testcontainers-postgres, but not required","package":"sqlalchemy","optional":true}],"imports":[{"note":"The package name uses hyphens, but the import path uses dots.","wrong":"from testcontainers_postgres import PostgresContainer","symbol":"PostgresContainer","correct":"from testcontainers.postgres import PostgresContainer"}],"quickstart":{"code":"from testcontainers.postgres import PostgresContainer\n\nwith PostgresContainer(\"postgres:16\") as postgres:\n    connection_url = postgres.get_connection_url()\n    print(f\"Connection URL: {connection_url}\")\n    # Use with psycopg2 or SQLAlchemy\n    import psycopg2\n    conn = psycopg2.connect(connection_url)\n    cur = conn.cursor()\n    cur.execute(\"SELECT 1;\")\n    print(cur.fetchone())\n","lang":"python","description":"Quickstart: create a PostgreSQL container, get connection URL, and run a query."},"warnings":[{"fix":"Use keyword argument `dbname` instead of `db_name`.","message":"The `PostgresContainer` constructor argument `db_name` has been renamed to `dbname` in testcontainers-python v4.14.0+.","severity":"deprecated","affected_versions":">=4.14.0"},{"fix":"Pass the image as a string directly: `PostgresContainer('postgres:16')` instead of `PostgresContainer(docker_image='postgres:16')`.","message":"The `PostgresContainer` no longer supports the `docker_image` parameter; use the first positional argument (image) instead.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always specify a full image tag (e.g., 'postgres:16-alpine') to ensure reproducibility.","message":"`PostgresContainer` silently falls back to default postgres:latest if the provided image tag is not available; this can lead to unexpected version mismatches.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install the main package with `pip install testcontainers` or ensure `testcontainers-core` is installed.","cause":"The base package `testcontainers-core` is not installed; testcontainers-postgres only adds the PostgreSQL module.","error":"ModuleNotFoundError: No module named 'testcontainers'"},{"fix":"Use `from testcontainers.postgres import PostgresContainer`.","cause":"The submodule is not imported correctly; the import path uses dots, not underscores.","error":"ImportError: cannot import name 'PostgresContainer' from 'testcontainers'"},{"fix":"Upgrade to latest version and use `get_connection_url()` instead of `get_container_host_ip()` or `get_exposed_port()`.","cause":"Method name changed in an older version (pre-4.0.0); the correct method is `get_connection_url()`.","error":"AttributeError: 'PostgresContainer' object has no attribute 'get_connection_url'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}