تخطّى إلى المحتوى الرئيسي
بثّ ملفات CSV الكبيرة من Postgres في Node.js و NestJS: الضغط العكسي و pipeline() والاتصال الذي يحتجزه التنزيل البطيء

بثّ ملفات CSV الكبيرة من Postgres في Node.js و NestJS: الضغط العكسي و pipeline() والاتصال الذي يحتجزه التنزيل البطيء

November 21, 2026
هندسة الأنظمة الخلفية
8 دقيقة قراءة

الخلاصة: تصدير CSV الذي يحمّل كل الصفوف في مصفوفة يستهلك ذاكرة تتناسب مع حجم الجدول، ولذلك يعمل في بيئة الاختبار وينهار في الإنتاج. في Devya نبثّ ملفات التصدير باستخدام pg-query-stream و pipeline() من node:stream/promises، وهذا يُبقي الذاكرة ثابتة بفضل الضغط العكسي، ونحسب حساب التكلفة التي يضيفها البثّ: اتصال واحد بـ Postgres ومعاملة واحدة مفتوحة طوال مدة تنزيل أبطأ عميل.

أول نقطة تصدير يكتبها أي فريق للوحة الإدارة تبدو دائماً بالشكل نفسه: استعلام يجلب كل شيء، ثم دمج الصفوف في نص واحد، ثم إرساله. هذه النسخة تجتاز المراجعة وكل الاختبارات لأن جدول الاختبار صغير. هذه الملاحظات تشرح النسخة التي نستبدلها بها، وما الذي تخطئ فيه نسخة البثّ إذا توقف الفريق عند المسار السليم فقط.

أهم النقاط

• التصدير المخزَّن في الذاكرة يكبر مع الجدول: تنفيذ SELECT إلى مصفوفة ثم دمجها في نص CSV يحتفظ بالنتيجة كاملة في ذاكرة Node.js مرتين على الأقل.

• الضغط العكسي يُبقي الذاكرة ثابتة: الدالة writable.write() تعيد false عندما يتجاوز المخزن المؤقت قيمة highWaterMark، وعلى المنتِج أن ينتظر حدث drain.

• pipeline() بديل pipe(): الدالة pipeline() من node:stream/promises تدير الضغط العكسي، وتُتلف كل التدفقات عند فشل أحدها، وتقبل AbortSignal؛ أما readable.pipe() فلا تنظّف ولا تنقل الأخطاء.

• التصدير بالبثّ يحتجز اتصال قاعدة بيانات: مكتبة pg-query-stream تقرأ عبر مؤشر (cursor) في Postgres، فيبقى اتصال واحد من المجمّع ومعاملة واحدة مفتوحين حتى ينتهي العميل أو ينقطع.

• الأخطاء بعد أول بايت لا تتحول إلى 500: بعد إرسال الترويسات تصبح الإشارة الصادقة الوحيدة للفشل هي تنزيل مقطوع.

لماذا تنفد الذاكرة في نقطة تصدير CSV في Node.js؟

تنفد الذاكرة في نقطة تصدير CSV عندما تبني النتيجة كاملة قبل إرسال أول بايت. في node-postgres تعيد الدالة pool.query() كل صف ككائن JavaScript داخل مصفوفة واحدة، ثم يبني تحويل الصفوف ودمجها نسخة ثانية كاملة على هيئة نص. استهلاك الذاكرة يزداد خطياً مع عدد الصفوف، وتصدير عدة مديرين في الوقت نفسه يضاعفه.

بعدها تصل العملية إلى حد ذاكرة V8 أو حد ذاكرة الحاوية فتُعاد تشغيلها، وتسقط معها كل الطلبات الجارية. رفع قيمة --max-old-space-size يؤجل المشكلة ولا يزيلها. الحل هو ألا نحتفظ أبداً بأكثر من نافذة صغيرة من الصفوف.

ما هو الضغط العكسي (backpressure) في تدفقات Node.js؟

الضغط العكسي هو الإشارة التي يرسلها المستهلك البطيء إلى المصدر ليجعل المنتِج السريع يتوقف مؤقتاً. في Node.js تعيد writable.write(chunk) القيمة false عندما يتجاوز المخزن الداخلي للتدفق قيمة highWaterMark، ويُطلق التدفق حدث drain عندما يفرغ المخزن. القيمة الافتراضية لـ highWaterMark هي 16 كائناً في تدفقات وضع الكائنات و 64 KiB في تدفقات البايتات في Node.js 22 وما بعده (كانت 16 KiB قبل Node.js 22).

قاعدة Postgres على شبكة محلية تنتج الصفوف أسرع بكثير مما ينزّلها متصفح على اتصال ضعيف. الحلقة التي تتجاهل القيمة المعادة من res.write() لا تتعطل؛ بل تضع كل قطعة غير مرسلة في طابور داخل الذاكرة، وهذا هو فشل نفاد الذاكرة نفسه بخطوات إضافية.

الحلقة المكتوبة يدوياً التي تنتظر once(res, 'drain') بعد كتابة أعادت false فيها خلل. الانتظار once(res, 'drain') لا ينتهي أبداً إذا انقطع العميل أثناء الانتظار، لأن المقبس المغلق يُطلق حدث close وليس drain. يتعلق معالج الطلب، ولا يعود اتصال قاعدة البيانات إلى المجمّع.

لماذا نستخدم pipeline() بدلاً من pipe()؟

الدالة pipeline() من node:stream/promises تدير الضغط العكسي ونقل الأخطاء والتنظيف في استدعاء واحد. أما readable.pipe(writable) فتدير الضغط العكسي فقط: عندما تفشل الوجهة أو تُغلق تترك pipe() تدفق المصدر مفتوحاً، ولا تنتقل الأخطاء بين التدفقين. في تصدير يعتمد على قاعدة بيانات، المصدر المتروك مفتوحاً يعني اتصالاً مسرَّباً.

• الدالة pipeline() تعيد وعداً (promise) يُرفض عند فشل أي تدفق، ومن ذلك انقطاع العميل الذي يظهر بالرمز ERR_STREAM_PREMATURE_CLOSE.

• الدالة pipeline() تُتلف كل تدفقات السلسلة عند الفشل، فيُغلق مؤشر Postgres عندما يُغلق تبويب المتصفح.

• الدالة pipeline() تقبل دوال المولّدات غير المتزامنة كخطوات تحويل، وتقبل { signal } كآخر وسيط، فيصبح تحويل الصف إلى CSV دالة async function* عادية، وتصبح المهلة القصوى AbortSignal.timeout().

كيف نبثّ الصفوف من Postgres إلى استجابة HTTP في NestJS؟

نبثّ الصفوف باستخدام pg-query-stream، وهي الحزمة المرافقة لـ node-postgres التي تعرض الاستعلام كتدفق Readable في وضع الكائنات يعتمد على مؤشر في Postgres. يجلب المؤشر عدداً من الصفوف يساوي batchSize في كل مرة، وفقط عندما يطلب التدفق المزيد.

التحويل عندنا مولّد غير متزامن اسمه toCsv. يُخرج toCsv أولاً علامة ترتيب البايتات لـ UTF-8 وسطر العناوين، ثم يُخرج سطر CSV واحداً لكل صف. دالة مساعدة اسمها csvCell تحوّل null إلى خلية فارغة، وتنسّق قيم Date باستخدام toISOString()، وتضاعف علامات الاقتباس الداخلية، وتحيط بعلامات اقتباس أي قيمة تحتوي على فاصلة أو علامة اقتباس أو سطر جديد.

المتحكّم (controller) في NestJS يحجز عميلاً واحداً عبر pool.connect()، وينشئ QueryStream بقيمة batchSize تساوي 500، ويضبط ترويستي Content-Type و Content-Disposition، ثم ينتظر pipeline(rows, toCsv, res, { signal: AbortSignal.timeout(120_000) }). وكتلة finally تستدعي client.release() دائماً.

المزخرف @Res() ينقل معالج NestJS إلى الوضع الخاص بالمكتبة، فلا تعود معترضات NestJS (interceptors) تشكّل تلك الاستجابة، ويصبح المعالج مسؤولاً عن الترويسات وإنهاء الاستجابة. يوفر NestJS أيضاً StreamableFile، وهو أبسط لإرسال ملف موجود مسبقاً؛ لكننا نستدعي pipeline() مباشرة لأننا نريد الرفض والتنظيف وإشارة الإلغاء في مكان واحد. تمرير خطأ إلى client.release() يجعل node-postgres يُتلف الاتصال بدلاً من إعادته إلى المجمّع، وهذا ما نفضّله بعد مؤشر أُلغي في منتصفه.

ما الذي يبقى معرّضاً للخطأ في تصدير CSV بالبثّ؟

تصدير CSV بالبثّ يفشل في أربعة مواضع لم تكن النسخة المخزَّنة في الذاكرة تصل إليها أصلاً.

• الأخطاء بعد أول بايت: سطر حالة HTTP يُرسل مع أول قطعة، ولذلك لا يمكن أن يتحول فشل الاستعلام في منتصف الجدول إلى استجابة 500. الدالة pipeline() تُتلف الاستجابة فيُظهر المتصفح تنزيلاً فاشلاً. التنزيل الفاشل هو النتيجة الصحيحة، لأن إنهاء الاستجابة بهدوء يسلّم ملفاً مبتوراً يبدو كاملاً. نتحقق من الصلاحيات والمعاملات قبل بدء pipeline، ما دام إرجاع 4xx ممكناً.

• الاتصال الذي يحتجزه التنزيل البطيء: مؤشر Postgres يُبقي اتصالاً واحداً من المجمّع ومعاملة واحدة مفتوحين طوال التنزيل. العميل البطيء يجعل التصدير بطيئاً، والمعاملة المفتوحة طويلاً تعطّل تنظيف vacuum للصفوف الميتة في Postgres. نحدّ المدة باستخدام AbortSignal.timeout() ونقيّد عدد عمليات التصدير المتزامنة حتى لا تستنزف المجمّع الذي تحتاجه بقية الـ API.

• التخزين المؤقت في الوسيط: خادم nginx يخزّن الاستجابات الممرَّرة مؤقتاً بشكل افتراضي، وهذا يحجب الضغط العكسي عن Node.js وقد يكتب الاستجابات الكبيرة في ملفات مؤقتة على القرص. إرسال الترويسة X-Accel-Buffering: no مع استجابة التصدير يوقف تخزين nginx المؤقت لتلك الاستجابة.

• سلوك برامج الجداول: برنامج Excel يفتح ملف CSV بترميز UTF-8 الخالي من علامة ترتيب البايتات بصفحة ترميز قديمة، فيفسد النص العربي وغيره من النصوص غير اللاتينية؛ وإضافة U+FEFF في بداية الملف تحل ذلك. كذلك ينفّذ Excel و Google Sheets الخلايا التي تبدأ بـ = أو + أو - أو @ كصيغ، وهو هجوم يُعرف بحقن CSV. دالتنا csvCell تضيف علامة اقتباس مفردة قبل القيم النصية التي تبدأ بهذه الرموز وتترك الأرقام كما هي، فتبقى المجاميع السالبة أرقاماً.

متى نبثّ، ومتى نقسّم إلى صفحات، ومتى ننقل التصدير إلى مهمة خلفية؟

نختار استراتيجية التصدير بحسب الحجم الذي قد تبلغه النتيجة والمدة التي قد يستغرقها العميل في تنزيلها.

• تخزين النتيجة كاملة في الذاكرة: الذاكرة تكبر مع عدد الصفوف والاستعلام قصير. نستخدم هذا الأسلوب فقط عندما يكون للتصدير حد أقصى صغير وثابت لعدد الصفوف.

• حلقة ترقيم بالمفتاح (keyset pagination): الذاكرة تبقى بحجم صفحة واحدة والاتصال يُحرَّر بين الصفحات، لكن كل صفحة ترى لقطة أحدث من البيانات. نستخدم هذا الأسلوب عندما لا يتحمل مجمّع الاتصالات أو طبيعة الحمل المعاملات الطويلة.

• البثّ بالمؤشر عبر pg-query-stream: الذاكرة تبقى بحجم دفعة واحدة والملف كله يأتي من لقطة واحدة، مقابل اتصال واحد ومعاملة واحدة طوال التنزيل. نستخدم البثّ بالمؤشر للتصدير التفاعلي المحدود المدة.

• مهمة خلفية تكتب إلى تخزين الكائنات: الذاكرة تبقى بحجم دفعة واحدة ولا يبقى أي طلب HTTP مفتوحاً. نستخدم المهمة الخلفية للتصدير الكبير جداً أو للعملاء البطيئين وغير المستقرين.

البثّ بالمؤشر هو خيارنا الافتراضي لتصدير لوحات الإدارة. ننقل التصدير إلى مهمة خلفية تكتب إلى تخزين الكائنات وترسل رابط تنزيل عندما يصطدم التصدير بمهلة pipeline بشكل متكرر.

الأسئلة الشائعة

س: هل يجعل البثّ تصدير CSV أسرع؟

ج: البثّ يجعل أول بايت يصل أبكر ويُبقي الذاكرة ثابتة. لكن الزمن الكلي للتصدير يبقى محكوماً باستعلام Postgres وسرعة تنزيل العميل.

س: هل يمكن استخدام StreamableFile في NestJS بدلاً من @Res() و pipeline()؟

ج: نعم. يقبل StreamableFile تدفق Readable ويُبقي المعالج في وضع NestJS القياسي. نحن نستدعي pipeline() مباشرة عندما يحتجز المصدر اتصال قاعدة بيانات، لأننا نريد تنظيفاً صريحاً ومهلة قصوى.

س: كيف نبثّ ملف CSV من Route Handler في Next.js؟

ج: نحوّل تدفق Node.js باستخدام Readable.toWeb() ونعيده كجسم لكائن Response. معالج Route Handler في Next.js على بيئة تشغيل Node.js يبثّ جسم ReadableStream إلى العميل.

س: لماذا يظهر النص العربي مشوّهاً في ملف CSV عند فتحه في Excel؟

ج: برنامج Excel لا يفترض ترميز UTF-8 لملف CSV الخالي من علامة ترتيب البايتات. كتابة U+FEFF كأول محرف في الملف تجعل Excel يقرأ الملف بترميز UTF-8.

س: كم عدد الصفوف الذي يستدعي بثّ التصدير؟

ج: لا يوجد عدد ثابت، لأن الحد يعتمد على عرض الصف والذاكرة المتاحة للعملية. نحن نبثّ أي تصدير يزداد عدد صفوفه مع بيانات العملاء وليس له حد أقصى ثابت.

قراءات إضافية

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

هندسة الأنظمة الخلفية

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

عندما تتوسّع واجهة NestJS إلى نسختين، تعمل كل مهمة @Cron مرتين. نستخدم قفل Postgres استشاريًا بدل Redis لإبقاء المهام المجدولة على نسخة واحدة: نمط pg_try_advisory_xact_lock الذي نستخدمه مع node-postgres، ولماذا تنكسر أقفال الجلسة خلف مجمّعات PgBouncer وNeon وSupabase، وأين تبقى fencing tokens ضرورية.

التسجيل المنظّم في Node.js وNestJS باستخدام Pino 10: كيف نضيف معرّف الطلب ونخفي الأسرار ونحافظ على تتبّع الأخطاء
اقرأ المقال

هندسة الأنظمة الخلفية

التسجيل المنظّم في Node.js وNestJS باستخدام Pino 10: كيف نضيف معرّف الطلب ونخفي الأسرار ونحافظ على تتبّع الأخطاء

كانت سجلات Node.js لدينا نصوصًا يمكن البحث فيها عبر grep لكن لا يمكن الاستعلام عنها، وتختلط أسطر كل طلب بأسطر الطلبات الأخرى. نقلنا خدمات Node.js وNestJS إلى سجلات JSON منظّمة باستخدام Pino 10. نشرح هنا كيف نضيف معرّف الطلب إلى كل سطر عبر AsyncLocalStorage، ونخفي ترويسات الطلب التي يسجّلها pino-http افتراضيًا، ونتجنب خطأ ترتيب الوسائط الذي يُسقط تتبّع المكدس.