The problem

Our online shop runs in development with one Docker Compose stack per service: order, stock, shipping. Each one has its FrankenPHP api, its PostgreSQL database and its redis. RabbitMQ and Mercure live in a common stack, which the others join through an external network, app-network.

It all starts with the API. To reach RabbitMQ, it gets networks: [app-network] and, in doing so, leaves its stack's default network. It can no longer find database, and the quick fix also plugs database and redis into app-network.

This works as long as a single stack runs. Once stock starts, the name database points to two containers on app-network, because every service name is a network alias there. Docker's embedded DNS then returns both addresses, shuffled on every answer.

The PostgreSQL client (libpq, under pdo_pgsql) tries the addresses in the order received and keeps the first one that accepts the connection. The stacks come from the same template: same user, same password, same database name. So the order API can read, write or migrate the stock database without a single error, and redis has the same problem.

On the shared network, “database” points to two containers order stack default network api database redis app-network external network rabbitmq mercure stock stack default network api database redis “database”? Docker's DNS returns both addresses: the order API can open the stock database. Fix: only the api joins app-network , and it also lists default database and redis stay on their stack's default ; the other stacks call order-api .

The solution

Only the API joins the shared network: it talks to RabbitMQ and Mercure, and the other stacks call it. It also lists default, because naming a network removes the implicit one. database and redis list no network: Compose attaches them to default, and to it alone.

# services/order/compose.override.yaml
services:
  api:
    networks:
      # Naming a network removes the implicit one: we keep it.
      default: {}
      app-network:
        # The name to use from the other stacks.
        aliases:
          - order-api
  # database and redis list no network: they stay on default.

networks:
  app-network:
    external: true

On default, database now only points to the stack's own database. On app-network, the name api stays ambiguous: every stack plugs its own into it. So the other stacks call order-api, an alias that only exists on that network.

Docker Compose 5.7.0, released on 2 November 2026, adds use_service_name_alias. Set to false next to aliases, it removes the name api from app-network. Before that version, the rule remains: never call api from another stack.

The pitfall

An API that starts proves nothing: it may have migrated the database next door. We check name resolution from inside the container, since it is the one querying the embedded DNS. The test only makes sense with at least two stacks running.

# From the order stack, with the stock stack running
docker compose exec api getent hosts database
docker compose exec api getent hosts redis
docker compose exec api bin/console dbal:run-sql "SELECT inet_server_addr()"

On a Debian image, getent hosts prints one line per address found (Alpine's prints only the first): we expect exactly one. The SQL query returns the address of the server that accepted the connection, to compare with the one from getent. If getent returns nothing, the API has lost default: that is the slip that had pushed the database onto the shared network.

Sources