DEV Community: Jhoan Sebastian Rojas Holguin

Healthchecks and depends_on in Docker Compose: why your API starts before Postgres

Jhoan Sebastian Rojas Holguin — Thu, 12 Nov 2026 22:55:28 +0000

Your API isn't broken: it just arrived at the party before Postgres. It's a classic failure in local environments and in CI, and it's fixed with about 6 net lines of YAML. I'll be direct: reproduce, fix, and measure.

🐛 The problem

depends_on in its short form only guarantees the startup order of containers. Compose starts db, sees that the process exists, and starts api. Whether Postgres is still initializing the cluster or replaying WAL doesn't matter to it.

Result: your API tries to connect, gets Connection refused or the database system is starting up, and crashes.

🧪 Step 1: reproduce it

So it can be verified without depending on your app, I use the Postgres image as a client. The "api" runs a single query and exits.

# compose.yaml (versión con el fallo)
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app

  api:
    image: postgres:16
    depends_on:
      - db
    command: ["psql", "postgresql://postgres:secret@db:5432/app", "-c", "select 1"]

Run it from scratch, without previous volumes, and capture the exit code:

docker compose down -v
time docker compose up --abort-on-container-exit --exit-code-from api
echo "exit code: $?"

On a clean volume, Postgres takes a few seconds to run initdb. Expect something like connection to server at "db" ... failed: Connection refused and a non-zero exit code. It's a timing race, so on a very fast machine or with an already-initialized volume it might not happen; that's why we use down -v.

🔧 Step 2: healthcheck + condition

Two changes are needed: db must report when it's ready, and api must wait for that signal.

# compose.yaml (versión corregida)
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U postgres -d app"]
      interval: 2s
      timeout: 3s
      retries: 15

  api:
    image: postgres:16
    depends_on:
      db:
        condition: service_healthy
    command: ["psql", "postgresql://postgres:secret@db:5432/app", "-c", "select 1"]

Net lines: 5 from the healthcheck block plus 1 for changing depends_on from a list to a map with condition. Those are the 6.

⚠️ The `-h 127.0.0.1` trap

On first startup, the official Postgres image starts a temporary server to run the scripts in /docker-entrypoint-initdb.d. That temporary server listens only on a Unix socket, not over TCP. If your healthcheck uses pg_isready without -h, it queries that socket and can report "healthy" just before Postgres restarts to open the real port.

Forcing -h 127.0.0.1 makes the check go over TCP, so it only turns green once the final server is accepting connections, which is what your API needs.

📏 Step 3: measure before and after

Run the same command with both files (-f compose.yaml) and note:

docker compose down -v
/usr/bin/time -f "%e s" docker compose up --abort-on-container-exit --exit-code-from api
echo "exit code: $?"
docker compose logs api | grep -ci "refused\|starting up"

This measures three things: total time, exit code, and the number of connection errors in the log. My measurements in this test:

Version	Time until api OK	Connection errors	Exit code

Without a healthcheck, Compose considers the database ready as soon as its container starts, so the api tries to connect too early and usually leaves "refused" errors in the log.

What you should see with the corrected version: 0 connection errors and exit code 0. The total time may be a bit longer than the failed attempt, because now you actually wait; what changes is that the result stops being a lottery.

🔁 Why it matters in CI

In a pipeline, startup is slower and less predictable than on your laptop. A sleep 10 is a patch: either there's time to spare or there isn't enough. The healthcheck waits just long enough and fails with a clear message if Postgres never becomes ready (after retries attempts), instead of leaving the API restarting in a loop. In my work with PostgreSQL and GitHub Actions deployments, I prefer that the dependency declares its state rather than having each service guess.

✅ Result

A simple depends_on = startup order, not availability.
healthcheck on the database + condition: service_healthy on the API = the API starts when Postgres already responds over TCP.
Verify with --exit-code-from api and count the errors in the log; don't rely on "it works on my machine".

You still should give your app retries with backoff for production outages: the healthcheck solves coordinated startup, not a crash mid-flight.

Idempotency in REST APIs: how I prevented duplicate charges with an Idempotency-Key

Jhoan Sebastian Rojas Holguin — Wed, 11 Nov 2026 21:35:21 +0000

🔥 The problem

The client sends a POST /payments, the network drops before the response arrives, and the client retries. The server had already charged the customer. Result: two charges for a single purchase.

This isn't a rare case: a timeout, a double click, or an HTTP client's automatic retry can cause it. And POST is not idempotent by definition, so the protection is up to you.

The idea: the client generates a unique Idempotency-Key per operation and sends it in the header. If the same key arrives again, you don't repeat the work: you return the saved response.

To test it, I simulated 50 simultaneous retries against the endpoint. Without idempotency: 50 records. With it: 1. Everything you need to reproduce it is below.

🧱 Step 1: the tables

The key piece is a unique constraint. Let the database enforce it, not your code: an if in the application doesn't hold up under concurrency.

CREATE TABLE payments (
  id BIGSERIAL PRIMARY KEY,
  amount_cents INTEGER NOT NULL,
  currency CHAR(3) NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE idempotency_keys (
  key TEXT PRIMARY KEY,
  request_hash TEXT NOT NULL,
  response JSONB,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

request_hash detects when someone reuses the same key with a different body. That's a client error and shouldn't be ignored.

⚙️ Step 2: the endpoint

Example with FastAPI and psycopg 3. Everything happens in a single transaction: reserve the key, create the payment, and store the response.

import hashlib, os
from fastapi import FastAPI, Header, HTTPException
from fastapi.responses import JSONResponse
from psycopg.types.json import Jsonb
from psycopg_pool import ConnectionPool
from pydantic import BaseModel

pool = ConnectionPool(os.environ["DATABASE_URL"], min_size=5, max_size=20, open=True)
app = FastAPI()

class PaymentIn(BaseModel):
    amount_cents: int
    currency: str

@app.post("/payments")
def create_payment(body: PaymentIn, idempotency_key: str = Header(...)):
    req_hash = hashlib.sha256(body.model_dump_json().encode()).hexdigest()
    with pool.connection() as conn:  # commit al salir, rollback si hay excepción
        reserved = conn.execute(
            "INSERT INTO idempotency_keys (key, request_hash) "
            "VALUES (%s, %s) ON CONFLICT (key) DO NOTHING RETURNING key",
            (idempotency_key, req_hash),
        ).fetchone()

        if reserved is None:  # la clave ya existía
            saved_hash, saved_response = conn.execute(
                "SELECT request_hash, response FROM idempotency_keys WHERE key = %s",
                (idempotency_key,),
            ).fetchone()
            if saved_hash != req_hash:
                raise HTTPException(422, "Idempotency-Key reutilizada con otro cuerpo")
            return JSONResponse(saved_response, status_code=200,
                                headers={"Idempotent-Replayed": "true"})

        payment_id = conn.execute(
            "INSERT INTO payments (amount_cents, currency) VALUES (%s, %s) RETURNING id",
            (body.amount_cents, body.currency),
        ).fetchone()[0]
        response = {"id": payment_id, "status": "created"}
        conn.execute(
            "UPDATE idempotency_keys SET response = %s WHERE key = %s",
            (Jsonb(response), idempotency_key),
        )
    return JSONResponse(response, status_code=201)

Why does it work under concurrency? If two transactions insert the same key, the second one blocks until the first finishes. When the first commits, the second one's ON CONFLICT DO NOTHING returns no row, reads the stored response, and replays it. No "in progress" state or manual locks are needed.

🧪 Step 3: 50 simultaneous retries

import sys, uuid, concurrent.futures as cf
import httpx

URL = "http://localhost:8000/payments"
BODY = {"amount_cents": 4999, "currency": "USD"}
mode = sys.argv[1]  # "same" = misma clave, "unique" = una clave por request
fixed = str(uuid.uuid4())

def pay(_):
    key = fixed if mode == "same" else str(uuid.uuid4())
    return httpx.post(URL, json=BODY, headers={"Idempotency-Key": key}, timeout=15).status_code

with cf.ThreadPoolExecutor(max_workers=50) as ex:
    codes = list(ex.map(pay, range(50)))

print({c: codes.count(c) for c in set(codes)})

Run the server with uvicorn app:app, then:

python stress.py unique   # control: sin idempotencia efectiva
python stress.py same     # 50 reintentos con la misma clave
psql "$DATABASE_URL" -c "SELECT count(*) FROM payments;"

What you should see:

unique: 50 201 responses and 50 rows in payments. This is the unprotected scenario.
After clearing the table (TRUNCATE payments, idempotency_keys;), same: one 201, 49 200s, and count(*) = 1.

⚠️ Details people forget

Expiration. Delete old keys with a job (24 to 72 hours is usually enough), or the table grows forever.
Same key, different body. Return 422, as in the code.
External side effects. If you call a payment provider inside the transaction, pass your key to it too. The database can't undo a charge that was already made outside it.
Errors. If it fails before the commit, the key isn't reserved and the client can retry without problems.

✅ Result

With one table, one primary key, and one transaction, you go from 50 payments to 1 under simultaneous retries. No queues, no distributed locks, and behavior you can verify with a 15-line script.

The underlying lesson: in distributed systems, assume every message can arrive twice, and design for that from the first endpoint.``

Docker Volumes vs Bind Mounts (Step-by-Step Guide) 🐳

Jhoan Sebastian Rojas Holguin — Tue, 08 Sep 2026 20:56:49 +0000

Learn Docker data persistence with a practical 5-minute lab comparing Docker Volumes and Bind Mounts.

Docker Data Persistence: Volumes vs Bind Mounts 🧪

By default, Docker containers are ephemeral. If a container stops or gets deleted, any data created inside it vanishes forever.

To prevent data loss, Docker provides two primary mechanisms for data persistence: Docker Volumes and Bind Mounts.

In this practical guide, we will walk through a 5-minute hands-on lab so you can test both approaches directly on your machine.

📊 Quick Comparison Matrix

Feature	Docker Volumes (Volúmenes)	Bind Mounts
Managed By	Docker Engine (`/var/lib/docker/volumes/`)	User / Host OS
Path on Host	Managed automatically by Docker	Explicit path (e.g., `/home/user/app`)
Best For	Production, Databases, Persistent Storage	Local Development, Live Code Reloading
Portability	High (Easy to backup, restore, migrate)	Low (Tied to specific host folder structure)
CLI Example	`-v my_volume:/app`	`-v /host/path:/app`

🧪 Hands-on Lab: Try It Yourself

Follow these step-by-step exercises in your terminal.

🔒 Part 1: Docker Volumes (Best for Production & Databases)

Docker Volumes are completely managed by Docker and isolated from the core host file system.

Step 1: Create a managed volume

docker volume create my_volume

Verify that the volume was created:

docker volume ls

Step 2: Start a container with the volume attached

docker run -d --name app_volume -v my_volume:/app nginx

Step 3: Write data inside the container

docker exec app_volume bash -c "echo 'Persistent data from Volume' > /app/data.txt"

Verify the file exists inside:

docker exec app_volume cat /app/data.txt

Step 4: Simulate a crash / Destroy the container

docker rm -f app_volume

Step 5: Attach the same volume to a NEW container

docker run -d --name app_volume_new -v my_volume:/app nginx

Step 6: Verify data persistence

docker exec app_volume_new cat /app/data.txt

Result: You will see Persistent data from Volume. The data survived the total destruction of the original container!

Cleanup Part 1:

docker rm -f app_volume_new
docker volume rm my_volume

📂 Part 2: Bind Mounts (Best for Local Development)

Bind Mounts directly link a folder on your host machine to a directory inside the container.

Step 1: Create a local directory on your host machine

mkdir -p ~/docker_lab/html
echo "<h1>Hello from Local Host (V1)</h1>" > ~/docker_lab/html/index.html

Step 2: Start an Nginx container using the bind mount

docker run -d --name web_server -v ~/docker_lab/html:/usr/share/nginx/html -p 8080:80 nginx

Step 3: Test access in your browser or terminal

curl http://localhost:8080

Output: <h1>Hello from Local Host (V1)</h1>

Step 4: Edit the file locally on your host machine (no container restart!)

echo "<h1>Live update reflected instantly! (V2)</h1>" > ~/docker_lab/html/index.html

Step 5: Verify immediate change

curl http://localhost:8080

Output: <h1>Live update reflected instantly! (V2)</h1>

Cleanup Part 2:

docker rm -f web_server
rm -rf ~/docker_lab

💡 Summary & Takeaways / Resumen

Use Docker Volumes when you need secure, isolated, and high-performance storage for databases (e.g., PostgreSQL, MySQL, MongoDB) or production services.
Use Bind Mounts when developing code locally so your IDE edits immediately reflect inside the container without rebuilding images.

💬 Discussion

Which persistence method do you use more in your daily workflow? Have you ever lost data due to container recreation? Let's discuss in the comments below! 👇

#docker #devops #backend #learning

[Boost]

Jhoan Sebastian Rojas Holguin — Wed, 03 Sep 2025 17:28:34 +0000

Jay

Aug 29 '25

DIY Local AI Stack: Who’s Interested?

#ai #opensource #linux

4 min read

DEV Community: Jhoan Sebastian Rojas Holguin

Healthchecks and depends_on in Docker Compose: why your API starts before Postgres

🐛 The problem

🧪 Step 1: reproduce it

🔧 Step 2: healthcheck + condition

⚠️ The -h 127.0.0.1 trap

📏 Step 3: measure before and after

🔁 Why it matters in CI

✅ Result

Idempotency in REST APIs: how I prevented duplicate charges with an Idempotency-Key

🔥 The problem

🧱 Step 1: the tables

⚙️ Step 2: the endpoint

🧪 Step 3: 50 simultaneous retries

⚠️ Details people forget

✅ Result

Docker Volumes vs Bind Mounts (Step-by-Step Guide) 🐳

Docker Data Persistence: Volumes vs Bind Mounts 🧪

📊 Quick Comparison Matrix

🧪 Hands-on Lab: Try It Yourself

🔒 Part 1: Docker Volumes (Best for Production & Databases)

Step 1: Create a managed volume

Step 2: Start a container with the volume attached

Step 3: Write data inside the container

Step 4: Simulate a crash / Destroy the container

Step 5: Attach the same volume to a NEW container

Step 6: Verify data persistence

Cleanup Part 1:

📂 Part 2: Bind Mounts (Best for Local Development)

Step 1: Create a local directory on your host machine

Step 2: Start an Nginx container using the bind mount

Step 3: Test access in your browser or terminal

Step 4: Edit the file locally on your host machine (no container restart!)

Step 5: Verify immediate change

Cleanup Part 2:

💡 Summary & Takeaways / Resumen

💬 Discussion

[Boost]

DIY Local AI Stack: Who’s Interested?

⚠️ The `-h 127.0.0.1` trap