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

لماذا يفشل `depends_on` الافتراضي

العواقب العملية لـ race condition عند الإقلاع

• connection refused — مقبس TCP الخاص بـ PostgreSQL لم يُفتح بعد، ويفشل التطبيق عند أول استدعاء PDO أو SQLAlchemy.
• FATAL: role does not exist — PostgreSQL يستمع، لكن سكريبتات التهيئة (docker-entrypoint-initdb.d) لم تُنشئ بعد الدور أو قاعدة البيانات.
• FATAL: the database system is starting up — الـ cluster في طور الاسترداد بعد إيقاف نظيف؛ الاتصالات مرفوضة مؤقتاً.
• حلقة تعطل صامتة — يعيد Docker تشغيل التطبيق باستمرار بفضل restart: unless-stopped، وتتكرر السجلات، ويبدو الأمر كخطأ في التطبيق.
• نتائج كاذبة في CI — تفشل اختبارات التكامل بصورة متقطعة بحسب سرعة الـ runner.
• تبعيات متسلسلة — إذا كانت واجهة برمجية تعتمد على تطبيق يعتمد على قاعدة بيانات، توارثت المشكلة ذاتها إن لم تكن سلسلة depends_on صحيحة في كل حلقة.

المتطلبات الأساسية: Docker Compose v2 والإضافة الرسمية

docker compose version

إعداد healthcheck موثوق لـ PostgreSQL خطوة بخطوة

1. 01

   فهم الفرق بين service_started و service_healthy

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

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

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

2. 02

   كتابة healthcheck الخاص بـ PostgreSQL في خدمة `db`

   أضف كتلة 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.

3. 03

   فهم دور `start_period`

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

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

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

4. 04

   كتابة `depends_on` مع `condition: service_healthy`

   في كل خدمة تعتمد على قاعدة البيانات، استبدل الشكل المختصر لـ 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.

5. 05

   الاختبار باستخدام `docker compose up`

   أطلق الـ 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، وتسرد مخرجات آخر الفحوصات.

6. 06

   حالة Redis: healthcheck مُكيَّف

   لا يمتلك 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 في الغالب.

7. 07

   حالة MySQL / MariaDB: استخدام `mysqladmin ping`

   لـ 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 أو متغير بيئة إن كانت السرية مطلوبة.

8. 08

   استكشاف الأخطاء: أربعة أخطاء شائعة

   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 لمعرفة مخرجات آخر الفحوصات وتحديد الأمر الفاشل.

السلوك الافتراضي مقابل السلوك مع healthcheck

مرّر الجدول أفقيًا

الخطوات التالية