Principle:MaterializeInc Materialize Service Dependency Configuration
| Knowledge Sources | misc/python/materialize/mzcompose/composition.py
|
|---|---|
| Domains | Integration Testing, Service Orchestration, Runtime Configuration |
| Last Updated | 2026-02-08 |
Overview
Runtime service orchestration starts services with dependency ordering and dynamic configuration overrides, enabling test scenarios that modify service definitions between workflow steps.
Description
The Service Dependency Configuration principle addresses the challenge of managing service lifecycles within integration tests. In a streaming database like Materialize, tests frequently need to:
- Start services in the correct dependency order (e.g., ZooKeeper before Kafka, Kafka before Materialized).
- Wait for services to pass health checks before proceeding.
- Modify service configurations between test steps (e.g., restart Materialized with different flags or a different image version).
- Handle transient failures during service startup by retrying.
This principle is realized through two complementary operations:
Starting services with up(): The up() operation builds, (re)creates, and starts named services. It delegates to docker compose up with options for detached mode and waiting for health checks. Services can be passed as strings (referring to services already defined in the composition) or as Service objects (for ad-hoc service definitions). The method supports starting "idle" services -- containers whose entrypoint is replaced with sleep infinity so they are running but not executing their main process, which is useful for testdrive and other exec-based services.
Overriding service definitions with override(): The override() operation is a context manager that temporarily replaces service definitions in the composition. When the with block exits, the original definitions are restored. This enables test patterns like: "run the test with Materialized v1, then override to Materialized v2 and verify upgrade behavior." The override performs a wholesale replacement of the service config (not a deep merge), ensuring that the overridden definition is exactly what the test author specifies.
Usage
Use this principle when:
- Starting a subset of services for a specific test phase.
- Testing upgrade or migration scenarios that require changing the Materialized image version mid-test.
- Modifying environment variables or command-line flags for a specific test step without affecting subsequent steps.
- Creating fault injection scenarios where a service is restarted with degraded configuration.
Theoretical Basis
The principle draws on several concepts:
- Dependency-ordered startup: Docker Compose's
depends_onmechanism withservice_healthyconditions ensures that services start in topological order of their dependency DAG. Theup()method leverages this by passing--waitto Docker Compose, which blocks until all targeted services and their transitive dependencies have passed health checks.
- Configuration snapshot and restore: The
override()context manager uses a memento pattern -- it takes a deep copy of the current composition state before applying the override, then restores the snapshot when the context manager exits. This ensures that configuration changes are scoped to a specific test phase and do not leak into subsequent phases.
- Idempotent recreation: The
up()operation is idempotent with respect to service state. If a service is already running with the current configuration, it is a no-op. If the configuration has changed (due to an override), the service is recreated. This property simplifies test authoring because workflow authors do not need to track which services are currently running.
- Retry resilience: The
up()method includes amax_triesparameter (default 5) that retries the Docker Compose invocation on failure. This handles transient issues like image pull failures or port conflicts that can occur in CI environments.
- Idle service pattern: The ability to start a service in "idle" mode (with
sleep infinityreplacing its entrypoint) enables the testdrive execution model, where the service container is kept running and commands are executed inside it viadocker compose exec. This avoids the overhead of creating and destroying containers for each testdrive invocation.