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.
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
-
Docker Compose,
services: networks,
aliases
and
use_service_name_alias: implicit
defaultnetwork, service name registered as an alias, shared alias with no guarantee on the container picked. - Docker Compose, Networking in Compose and external networks: several projects on a shared network.
-
Docker Compose,
pull request 14342
and
version 5.7.0
of 2 November 2026:
use_service_name_alias. - Docker Engine, DNS services, 1.11.0 release notes (several A records for one name) and resolver.go: addresses shuffled on every answer.
- PostgreSQL 18, libpq, multiple hosts and inet_server_addr(); PHP, PDO_PGSQL (libpq).
- Symfony, dbal:run-sql; Linux, getent(1); Alpine, getent.c (only the first address is printed).
- Lychen, pull request 266: an open-source implementation of what this note describes, in a moon monorepo.