{"id":9729,"library":"exasol-integration-test-docker-environment","title":"Exasol Integration Test Docker Environment","description":"The Exasol Integration Test Docker Environment (ITDE) provides a Python API and CLI to easily spawn and manage Exasol database instances within Docker for integration testing. It ensures a consistent and isolated environment for running tests against various Exasol DB versions. The current version is 6.1.0, with frequent minor/patch releases and occasional major releases driven by Exasol DB updates or significant API changes.","status":"active","version":"6.1.0","language":"en","source_language":"en","source_url":"https://github.com/exasol/integration-test-docker-environment","tags":["exasol","docker","testing","database","integration-testing"],"install":[{"cmd":"pip install exasol-integration-test-docker-environment","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.10 to <3.15.","package":"python","optional":false},{"reason":"Core dependency for interacting with Docker daemon.","package":"docker","optional":false},{"reason":"Used for the command-line interface.","package":"click","optional":false}],"imports":[{"note":"The `api.common` module was refactored and split in v4.0.0; specific classes moved to new paths.","wrong":"from exasol_integration_test_docker_environment.api.common import DockerTestEnvironment","symbol":"DockerTestEnvironment","correct":"from exasol_integration_test_docker_environment.environment.docker_test_environment import DockerTestEnvironment"},{"note":"The `api.common` module was refactored and split in v4.0.0; specific functions moved to new paths.","wrong":"from exasol_integration_test_docker_environment.api.common import spawn_test_environment","symbol":"spawn_test_environment","correct":"from exasol_integration_test_docker_environment.lib.api.spawn_test_environment import spawn_test_environment"}],"quickstart":{"code":"from exasol_integration_test_docker_environment.environment.docker_test_environment import DockerTestEnvironment\n\n# Configure with a supported Exasol Docker DB version. (e.g., 2025.1.8, 8.29.13)\n# Check the library's GitHub for currently supported versions.\nEXASOL_DB_VERSION = \"8.34.0\" # Or '2025.1.8'\n\ntry:\n    with DockerTestEnvironment(\n        docker_db_version=EXASOL_DB_VERSION,\n        name=\"my_integration_test\"\n    ) as environment:\n        connection_info = environment.get_connection_info()\n        print(f\"Exasol DB IP: {connection_info.host}\")\n        print(f\"Exasol DB Port: {connection_info.port}\")\n        print(f\"Exasol DB User: {connection_info.user}\")\n        print(f\"Exasol DB Password: {connection_info.password}\")\n        print(f\"Exasol DB Schema: {connection_info.schema}\")\n\n        # Your test code goes here, using connection_info to connect to the DB\n        print(\"Exasol test environment is running.\")\n\nexcept Exception as e:\n    print(f\"Failed to spawn Exasol Docker environment: {e}\")","lang":"python","description":"This quickstart demonstrates how to use `DockerTestEnvironment` to launch an Exasol database instance in Docker. It automatically pulls the specified Docker image, configures the environment, and provides connection details. The `with` statement ensures the environment is properly shut down afterwards."},"warnings":[{"fix":"Review existing scripts that interact directly with Docker image tags. The ITDE API should handle this transparently, but direct Docker CLI calls may need adjustment.","message":"Starting from v6.0.0, the Docker image tag format has changed to support platform-specific builds. This may affect CI/CD pipelines or scripts relying on a specific tag naming convention.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Update your `docker_db_version` parameter to a currently supported Exasol Docker DB version (e.g., '2025.1.8' or '8.29.13'). Check the ITDE GitHub repository for the latest supported versions.","message":"Version 5.0.0 removed support for older Exasol Docker DB versions (e.g., those prior to 2025.1.8, 8.29.13, 7.1.30) because Exasol removed them from Docker Hub. Attempting to use these versions will result in a `DockerVersionNotSupportedError`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Python environment to version 3.10 or newer. The library currently supports Python up to 3.14.","message":"Minimum Python version was updated to 3.10 in v4.4.0. Running the library on Python 3.9 or older will lead to compatibility errors or crashes.","severity":"breaking","affected_versions":">=4.4.0"},{"fix":"Update your Python import statements. For example, `from exasol_integration_test_docker_environment.api.common import DockerTestEnvironment` should become `from exasol_integration_test_docker_environment.environment.docker_test_environment import DockerTestEnvironment`.","message":"Version 4.0.0 introduced significant API refactorings, specifically splitting `api/common.py` into more granular modules. This changes import paths for core classes and functions like `DockerTestEnvironment` and `spawn_test_environment`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to `exasol-integration-test-docker-environment` v4.4.1 or newer. It's recommended to use the `connection_info.bucketfs_port` or similar attributes for accurate port information.","message":"Prior to v4.4.1, the deprecated `bucketfs` property returned the wrong HTTP port. If you were using this property and expecting HTTP access, connections would fail.","severity":"gotcha","affected_versions":"<4.4.1"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Update your import statements to reflect the new module structure. For example, `from exasol_integration_test_docker_environment.api.common import DockerTestEnvironment` should be changed to `from exasol_integration_test_docker_environment.environment.docker_test_environment import DockerTestEnvironment`.","cause":"The `api.common` module was refactored and split into multiple files in v4.0.0, changing the import paths for many classes and functions.","error":"ModuleNotFoundError: No module named 'exasol_integration_test_docker_environment.api.common'"},{"fix":"Specify a currently supported `docker_db_version` in your `DockerTestEnvironment` constructor or CLI command. Valid versions include '2025.1.8' or '8.29.13' (check the official documentation for the latest).","cause":"You are attempting to use an Exasol Docker DB version that is no longer supported by the ITDE after v5.0.0, often due to Exasol removing older images from Docker Hub.","error":"exasol_integration_test_docker_environment.lib.api.options.docker_options.DockerVersionNotSupportedError: Docker DB version 'X.Y.Z' is not supported."},{"fix":"Upgrade your Python environment to version 3.10, 3.11, 3.12, 3.13, or 3.14.","cause":"The library requires Python 3.10 or newer, a change introduced in v4.4.0.","error":"RuntimeError: Python 3.9.x is not supported. Please use Python 3.10 or newer."},{"fix":"Upgrade to `exasol-integration-test-docker-environment` v6.0.0 or newer to fix serialization issues for internal data structures.","cause":"A bug in serialization for `ImageInfo` (and potentially other data models) was present in versions prior to 6.0.0.","error":"TypeError: Object of type <class 'exasol_integration_test_docker_environment.lib.api.data_model.image_info.ImageInfo'> is not JSON serializable"}]}