depends_on لا يكفي: healthcheck لـ PostgreSQL في Compose

يقبل depends_on ثلاثة شروط:

- service_started (افتراضي) — ينتظر انطلاق الحاوية فقط.
- service_healthy — ينتظر حتى يُعيد healthcheck الحاوية healthy.
- service_completed_successfully — للحاويات قصيرة العمر (jobs، migrations).

لأي قاعدة بيانات، service_healthy هو الشرط الوحيد الذي يضمن أن الخدمة تقبل الاتصالات فعلاً.

أضف كتلة healthcheck مباشرة في تعريف خدمة db:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "app", "-d", "appdb"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 30s

يستقبل الحقل test قائمة: العنصر الأول CMD (يُنفّذ Docker الأمر مباشرة)، تليه الوسائط. يُعيد pg_isready القيمة 0 إذا كان PostgreSQL جاهزاً لقبول الاتصالات بالمستخدم وقاعدة البيانات المحددَين، وكوداً غير صفري إذا لم يكن كذلك — وهو ما يُفسّره Docker على أنه healthy أو unhealthy.

start_period هو فترة السماح الممنوحة للحاوية للتهيئة قبل أن تبدأ إخفاقات healthcheck في الاحتساب ضمن retries. خلال هذه الفترة، ينفّذ Docker healthcheck، لكن الإخفاق لا يزيد العداد.

بدون start_period، فإن PostgreSQL الذي يستغرق 15 ثانية للتهيئة سيُخفق في أول 5 فحوصات (interval: 5s × 5 محاولات = 25 ثانية) وينتهي unhealthy قبل أن يصبح تشغيلياً.

القيمة الموصى بها هي 30 ثانية لـ PostgreSQL القياسي: كافية لاستيعاب التهيئات البطيئة (أول إقلاع بحجم فارغ، إضافات ثقيلة) دون تأخير غير ضروري عند الإقلاع في الظروف العادية. interval وstart_period متمايزان: interval يُوقّت الفحوصات في التشغيل الطبيعي، وstart_period يحمي مرحلة الإقلاع.

في كل خدمة تعتمد على قاعدة البيانات، استبدل الشكل المختصر لـ depends_on بالشكل المفصّل مع الشرط:

services:
  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://app:secret@db:5432/appdb

بهذا الإعداد، ينتظر Docker حتى يُعيد healthcheck خدمة db القيمة healthy قبل تشغيل app. إذا أصبح db بحالة unhealthy بعد retries إخفاق، لا تنطلق app.

أطلق الـ stack وراقب التسلسل:

docker compose up

سترى في السجلات أسطراً من قبيل:

db  | database system is ready to accept connections
app | Waiting for db to be healthy...
app | Starting application server

للتحقق من حالة healthcheck في أي وقت:

docker inspect <db_container_name> | grep -A 5 '"Health"'

تُظهر المخرجات Status: healthy أو starting أو unhealthy، وتسرد مخرجات آخر الفحوصات.

لا يمتلك Redis أداة redis-isready، لكن معادلها هو redis-cli ping:

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s

يُعيد redis-cli ping القيمة PONG وكود الخروج 0 إذا كان Redis يقبل الاتصالات. بما أن Redis يبدأ أسرع من PostgreSQL، تكفي start_period: 10s في الغالب.

لـ MySQL أو MariaDB، استخدم mysqladmin ping:

  mysql:
    image: mariadb:11
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: appdb
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-psecret"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 30s

تنبيه: يُدمج كلمة المرور مباشرة مع -p بلا مسافة (-psecret)، وهو السلوك المتوقع لـ mysqladmin. يظهر هذا الأمر في مخرجات docker inspect، لذا فضّل استخدام Compose secret أو متغير بيئة إن كانت السرية مطلوبة.

pg_isready: command not found — لا تستخدم الصورة الرسمية postgres (أو صورة مشتقة تتضمنها). تحقق باستخدام: docker compose exec db which pg_isready.

healthcheck في حلقة، لا يصل أبداً إلى healthy — لا يُعيد test القيمة 0. اختبر يدوياً: docker compose exec db pg_isready -U app -d appdb. إذا فشل الأمر، تحقق من متغيرات POSTGRES_USER وPOSTGRES_DB.

start_period قصير جداً — عند أول إقلاع بحجم فارغ، قد يستغرق PostgreSQL أكثر من 30 ثانية. ارفع القيمة إلى 60s أو راقب السجلات: database system was shut down at … LOG: database system is ready to accept connections يُشير إلى التأخير الفعلي.

الحاوية في حالة unhealthy دائمة — بعد retries إخفاق، يُصنّف Docker الحاوية unhealthy لكنه لا يُعيد تشغيلها (ذلك دور restart). راجع docker inspect لمعرفة مخرجات آخر الفحوصات وتحديد الأمر الفاشل.