How does Docker Swarm handle database (PostgreSQL) replication?

How does it deal out of the box with database containers?

It doesn't.

There is a pretty good description of Swarm services here: How services work (emphasis mine)

When you deploy the service to the swarm, the swarm manager accepts your service definition as the desired state for the service. Then it schedules the service on nodes in the swarm as one or more replica tasks.

Swarm has no idea what's inside the task, all it knows is how many instances of it there are, whether those instances are passing their health checks, and if there are enough of them to satisfy the task definition you gave it. The word overlap between this and database replicas is a little unfortunate, but they are different concepts.

What is the expected pattern to handle data consistency between replicas of a database container?

Setting up data replication is on you. These are probably as good a place to start as any

• How to Set Up PostgreSQL for High Availability and Replication with Hot Standby
• PostgreSQL Replication Example

Docker swarm currently scales well for the stateless applications. For database replication, you have to rely on every database's own replication mechanism. Swarm could not manage the datatbase replication. The volume or file system level replication could provide the protection for a single instance database, but are not aware of database replication/cluster.

For databases such as PostgreSQL, the additional works are required. There are a few options:

1. Use host's local directory. You will need to create one service for every replica, and use constraint to schedule the container to one specific host. You will also need custom postgresql docker image to set up the postgresql replication among replicas. While, when one node goes down, one PostgreSQL replica will go down. You will need to work to bring up another replica. See crunchydata's example.

2. Use the volume plugin, such as flocker, REX-Ray. You will still need to create one service for every replica, and bind one volume to one service. You need to create all services in the same overlay network and configure the PostgreSQL replicas to talk with each other via the dns name (the docker service name of the replica). You will still need to set up the postgresql replication among replicas.