أقفال Postgres الاستشارية في Node.js وNestJS: كيف نشغّل المهام المجدولة على نسخة واحدة فقط
جدول المحتويات
عن الكاتب

Ahmed Mahmoud
كاتب ومطوّر
مهندس برمجيات شغوف بتطوير الويب وتصميم تجربة المستخدم.
مؤسّس ديفيا · eng-ahmed.com ↗قفل Postgres الاستشاري (advisory lock) قفل متبادل يحدده التطبيق وتفرضه Postgres، ومفتاحه عدد صحيح من 64 بت. في Devya نستخدم pg_try_advisory_xact_lock لتشغيل المهام المجدولة في Node.js وNestJS على نسخة واحدة فقط في كل مرة. القفل على مستوى المعاملة يتحرر تلقائيًا عند COMMIT أو ROLLBACK أو انقطاع الاتصال، لذا فالأعطال التي تستحق التخطيط هي مجمّعات الاتصالات التي تعمل بوضع المعاملات والآثار الجانبية التي تخرج من قاعدة البيانات.
أهم النقاط
لا يوفّر @nestjs/schedule أي تنسيق بين النسخ: كل نسخة (replica) تحمّل الوحدة تشغّل كل دالة @Cron()، لذا تعني N نسخ تشغيل كل مهمة N مرة.
في المهام التي يجب أن تعمل مرة واحدة نستدعي pg_try_advisory_xact_lock(key)، التي تُرجع false فورًا إذا كانت جلسة أخرى تحمل المفتاح، فتتخطى النسخة الخاسرة التشغيل بدل أن تنتظر ثم تشغّل المهمة مرة ثانية.
الأقفال الاستشارية على مستوى المعاملة (transaction) تعمل عبر PgBouncer في وضع المعاملات. أما الأقفال على مستوى الجلسة (session) فلا تعمل، وتتسرّب إذا أُعيد اتصال إلى المجمّع (pool) وهو ما يزال يحمل قفلًا.
عندما تُنفَّذ كتابات المهمة داخل المعاملة نفسها التي تحمل القفل، تثبّت Postgres القفل والكتابات معًا أو تتراجع عنهما معًا.
القفل لا يحمي الآثار الجانبية خارج Postgres. رسائل البريد وwebhooks واستدعاءات الدفع ما تزال تحتاج إلى مفتاح idempotency أو fencing token.
لماذا تعمل مهمة @Cron في NestJS مرتين بعد التوسّع إلى نسختين؟
تعمل مهمة @Cron() في NestJS مرة لكل عملية (process)، لأن @nestjs/schedule مجدول داخل العملية ولا يشارك أي حالة بين النسخ. عندما انتقلت إحدى واجهات NestJS لدينا من حاوية واحدة إلى حاويتين، بدأت كل مهمة مجدولة تنطلق مرتين في الدقيقة نفسها: مزامنتان للفواتير، ورسالتا ملخّص، وعمليتا تنظيف تتنافسان على الصفوف نفسها.
درسنا ثلاثة حلول. عامل (worker) مخصص بنسخة واحدة يصمد حتى يوسّعه أحدهم، أو حتى يشغّل نشر تدريجي (rolling deploy) النسختين القديمة والجديدة معًا لفترة قصيرة. والمشغّل الخارجي مثل Kubernetes CronJob الذي يستدعي endpoint يزيل المؤقّت الداخلي لكنه لا يمنع استدعاء ذلك الـ endpoint مرتين. أما القفل حول العمل نفسه فيحمي المهمة أيًّا كان من شغّلها، وبما أن الخدمة تستخدم Postgres أصلًا لم نحتج إلى إضافة Redis.
ما هو قفل Postgres الاستشاري، وأي دالة نستدعي؟
قفل Postgres الاستشاري قفل على رقم يختاره التطبيق وليس على جدول أو صف: تفرض Postgres الاستبعاد المتبادل لكنها لا تعطي المفتاح أي معنى. المفتاح قيمة bigint واحدة أو قيمتان integer، وكل التطبيقات المتصلة بقاعدة البيانات نفسها تتشارك مساحة المفاتيح، لذلك نضيف بادئة لأسماء الأقفال مثل billing:invoice-sync قبل تحويلها إلى مفتاح.
pg_advisory_lock(key): نطاق الجلسة، ينتظر إذا كان المفتاح محجوزًا، ويتحرر بـ pg_advisory_unlock(key) أو بانقطاع الاتصال.
pg_try_advisory_lock(key): نطاق الجلسة، يُرجع false إذا كان المفتاح محجوزًا، ويتحرر بـ pg_advisory_unlock(key) أو بانقطاع الاتصال.
pg_advisory_xact_lock(key): نطاق المعاملة، ينتظر إذا كان المفتاح محجوزًا، ويتحرر تلقائيًا عند COMMIT أو ROLLBACK.
pg_try_advisory_xact_lock(key): نطاق المعاملة، يُرجع false إذا كان المفتاح محجوزًا، ويتحرر تلقائيًا عند COMMIT أو ROLLBACK.
هناك سلوكان موثّقان يسهل تفويتهما. أقفال الجلسة قابلة لإعادة الدخول (reentrant)، فالجلسة التي تأخذ المفتاح نفسه مرتين يجب أن تحرره مرتين. كما أن أقفال الجلسة تتجاهل المعاملات: قفل الجلسة المأخوذ داخل معاملة تم التراجع عنها يبقى محجوزًا بعد التراجع.
في مهمة يجب أن تعمل مرة واحدة، المتغيّرات الحاجبة (blocking) اختيار خاطئ. تجعل pg_advisory_lock النسخة الثانية تنتظر الأولى ثم تشغّل المهمة نفسها مرة أخرى، وهذا بالضبط التكرار الذي أردنا إزالته.
كيف نغلّف مهمة بقفل استشاري على مستوى المعاملة باستخدام node-postgres؟
تأخذ الدالة المساعدة لدينا عميلًا واحدًا من Pool في node-postgres، وتنفّذ BEGIN، ثم تستدعي SELECT pg_try_advisory_xact_lock($1::bigint)، وتعود مبكرًا مع ROLLBACK إذا كانت النتيجة false. وإلا فإنها تشغّل المهمة على العميل نفسه ثم تنفّذ COMMIT. أي خطأ يؤدي إلى ROLLBACK، ويُعاد العميل إلى المجمّع دائمًا داخل كتلة finally.
نشتق المفتاح ذا الـ 64 بت في Node.js من أول 8 بايت من تجزئة SHA-256 لاسم القفل، باستخدام createHash('sha256') وBuffer.readBigInt64BE(0)، ونرسله نصًا مع تحويله إلى bigint. بهذا نتجنب الاعتماد على الدالة الداخلية hashtext() في Postgres، فهي ليست جزءًا من واجهة SQL الموثّقة.
في NestJS تصبح دالة @Cron(CronExpression.EVERY_10_MINUTES) غلافًا رفيعًا: تستدعي الدالة المساعدة باسم القفل والمهمة، وإذا أفادت بأن القفل محجوز تسجّل سطر debug وتعود.
التفصيل المهم هو تمرير عميل المعاملة إلى المهمة. عندما تكتب المهمة عبر ذلك العميل، تتشارك كتاباتها والقفل معاملة واحدة: إذا توقفت العملية في المنتصف، تتراجع Postgres عن الكتابات وتحرر القفل معًا.
المقابل هو معاملة مفتوحة تحجز اتصالًا واحدًا من المجمّع طوال المهمة. هذا مقبول للمهام التي تستغرق ثواني. أما المهام الطويلة فنستخدم لها قفل جلسة على اتصال مخصص، خاصة حيث يكون idle_in_transaction_session_timeout مضبوطًا.
لماذا تنكسر أقفال الجلسة الاستشارية خلف PgBouncer أو Neon أو Supabase؟
تنكسر أقفال الجلسة خلف مجمّع يعمل بوضع المعاملات لأن القفل ملك لجلسة خادم Postgres، والمجمّع في هذا الوضع يسلّم تلك الجلسة لعميل آخر بعد كل معاملة. يذكر توثيق PgBouncer أقفال الجلسة الاستشارية كميزة غير متوافقة مع transaction pooling، والأمر نفسه ينطبق على المجمّعات المُدارة بوضع المعاملات مثل نقطة pooler في Neon ومجمّع المعاملات في Supabase على المنفذ 6543.
ينتج عن ذلك عطلان. قد يصل استدعاء فك القفل إلى جلسة خادم مختلفة، فتُرجع pg_advisory_unlock القيمة false مع تحذير بينما يبقى القفل الحقيقي محجوزًا. أو تصل معاملة عميل آخر إلى الجلسة التي تحمل القفل، ولأن الأقفال الاستشارية قابلة لإعادة الدخول داخل الجلسة، تنجح pg_try_advisory_lock لذلك العميل رغم أن المفتاح محجوز بالفعل.
حتى بدون مجمّع خارجي، قد يسرّب node-postgres قفل جلسة: العميل الذي يُعاد إلى Pool يحتفظ بأقفاله حتى يُغلق اتصاله. لذلك تتصل دالة قفل الجلسة لدينا عبر رابط قاعدة البيانات المباشر، وتفك القفل داخل finally، وتستدعي client.release(true) بعد أي خطأ، ما يغلق الاتصال ويحرر كل ما يحمله.
لمعرفة من يحمل القفل، نستعلم من pg_locks مع ربطها بـ pg_stat_activity حيث locktype = 'advisory'. يُقسَم مفتاح bigint إلى classid (أعلى 32 بت) وobjid (أدنى 32 بت)، والتعبير (classid::bigint << 32) | objid::bigint يعيد بناءه. وضبط application_name على كل مجمّع يجعل حامل القفل واضحًا.
متى نستخدم قفل Redis بدلًا من ذلك، ولماذا نحتاج fencing tokens؟
نلجأ إلى قفل Redis عندما لا تكون هناك قاعدة Postgres مشتركة يرتكز عليها العمل. قفل Redis على نسخة واحدة هو SET key token NX PX 30000، ويتحرر بسكربت Lua يحذف المفتاح فقط إذا كان ما يزال يحمل الـ token الخاص بنا. نقطة ضعفه هي مدة الصلاحية (TTL): إذا طالت المهمة أكثر منها، تنتهي صلاحية المفتاح ويحصل عامل ثانٍ على القفل بينما الأول ما يزال يعمل.
أي قفل يناسب أي مهمة؟
قفل استشاري على مستوى المعاملة: للمهام القصيرة التي تعمل مرة واحدة؛ يتحرر عند انتهاء المعاملة؛ يعمل عبر مجمّعات وضع المعاملات؛ ذرّي مع كتابات المهمة في قاعدة البيانات.
قفل استشاري على مستوى الجلسة: للمهام الطويلة على اتصال مباشر؛ يتحرر بفك القفل أو انقطاع الاتصال؛ ينكسر خلف مجمّعات وضع المعاملات؛ غير ذرّي مع الكتابات.
Redis SET NX PX: قفل متبادل بين الخدمات؛ يتحرر بالمقارنة ثم الحذف أو بانتهاء TTL؛ إذا تعطّل الحامل يبقى القفل حتى تنتهي الـ TTL.
SELECT … FOR UPDATE SKIP LOCKED: لعدة عمّال يستهلكون جدول طابور ويأخذ كل منهم صفوفًا مختلفة؛ يتحرر عند انتهاء المعاملة. إنه أداة لطوابير العمل وليس لمهام التشغيل الفردي.
لا يحمي أي قفل أثرًا جانبيًا خارج نظامه. قد ينهي انقسام في الشبكة أو مهلة خمول أو استدعاء pg_terminate_backend من المسؤول جلسة Postgres الخاصة بحامل القفل بينما تستمر عملية Node.js في العمل، فتبدأ نسخة أخرى بينما الأولى ما تزال تستدعي واجهة الدفع. حل Martin Kleppmann هو fencing token: رقم يزداد مع كل منح للقفل ويتحقق منه النظام اللاحق ليرفض الحاملين القدامى. وعندما لا تستطيع الواجهة اللاحقة التحقق من هذه الأرقام، نرسل مفاتيح idempotency كي لا يضر الاستدعاء المكرر.
الأسئلة الشائعة
س: هل تعمل الأقفال الاستشارية في Postgres مع Prisma أو Drizzle؟
ج: نعم. استدعِ دالة القفل بـ SQL خام داخل معاملة تفاعلية، مثل tx.$queryRaw داخل $transaction في Prisma أو tx.execute داخل db.transaction() في Drizzle. متغيّرات try_ تُرجع قيمة boolean تقرؤها برامج التشغيل (drivers) بسهولة، بينما تُرجع pg_advisory_lock النوع void الذي تفشل بعض أدوات ORM في قراءته.
س: هل تُشارَك الأقفال الاستشارية بين قواعد البيانات على خادم Postgres نفسه؟
ج: لا. نطاق الأقفال الاستشارية هو قاعدة البيانات الحالية، لكن كل التطبيقات المتصلة بتلك القاعدة تتشارك مساحة مفاتيح واحدة، لذا أضف اسم الخدمة كبادئة لأسماء الأقفال قبل تجزئتها.
س: ماذا يحدث للقفل الاستشاري إذا تعطّلت النسخة التي تحمله؟
ج: تحرر Postgres أقفال الجلسة وأقفال المعاملة عند انتهاء الجلسة الحاملة. تعطّل العملية يغلق الاتصال ويحرر القفل بسرعة، أما اختفاء الجهاز بالكامل فلا يحرره إلا عندما تكتشف Postgres أن الاتصال ميت، وهذا يعتمد على إعدادات TCP keepalive.
س: هل يُغني Kubernetes CronJob مع concurrencyPolicy: Forbid عن القفل؟
ج: فقط بالنسبة للتشغيلات المتداخلة لذلك الـ CronJob. لا يمنع concurrencyPolicy: Forbid تشغيل العمل نفسه من endpoint إداري أو إعادة محاولة أو مجدول ثانٍ، بينما يحمي القفل الاستشاري العمل أينما استُدعي.
قراءات إضافية
هندسة الأنظمة الخلفية
التسجيل المنظّم في Node.js وNestJS باستخدام Pino 10: كيف نضيف معرّف الطلب ونخفي الأسرار ونحافظ على تتبّع الأخطاء
كانت سجلات Node.js لدينا نصوصًا يمكن البحث فيها عبر grep لكن لا يمكن الاستعلام عنها، وتختلط أسطر كل طلب بأسطر الطلبات الأخرى. نقلنا خدمات Node.js وNestJS إلى سجلات JSON منظّمة باستخدام Pino 10. نشرح هنا كيف نضيف معرّف الطلب إلى كل سطر عبر AsyncLocalStorage، ونخفي ترويسات الطلب التي يسجّلها pino-http افتراضيًا، ونتجنب خطأ ترتيب الوسائط الذي يُسقط تتبّع المكدس.
هندسة الأنظمة الخلفية
إدارة الموارد الصريحة في TypeScript وNode.js 24: كيف نستخدم using وawait using وDisposableStack
يأتي تسرب الاتصالات غالبًا من مسار خطأ واحد تخطّى استدعاء release(). يشغّل Node.js 24 التعليمتين using وawait using بشكل أصلي، ويترجمهما TypeScript منذ الإصدار 5.2. نشرح هنا كيف يجعل فريقنا عملاء قواعد البيانات والمعاملات والمجلدات المؤقتة وتجهيزات الاختبارات قابلة للتحرير، ومتى نستخدم DisposableStack، والفخين اللذين يجب تجنبهما: SuppressedError والبث الذي يعيش بعد نطاقه.