أداة Safe / Not Safe تفحص ترحيلات Postgres قبل تشغيلها

حكم قبل النشر

‏Safe / Not Safe ‏(safenotsafe.dev) أداة لفحص ترحيلات PostgreSQL تعمل بالكامل داخل المتصفح. يلصق المطور ملف الترحيل في المحرر، ويحلَّل SQL داخل Web Worker باستخدام محلل libpg_query المصرَّف إلى WebAssembly، ثم تعيد الأداة واحدًا من ثلاثة أحكام: SAFE أو NOT SAFE أو NEEDS CONTEXT. والهدف، بحسب ملف README للمشروع، ضيق عن قصد: التقاط المزالق المعروفة في تغييرات المخطط قبل وصولها إلى الإنتاج.

قبل إصدار الحكم يطرح التطبيق سؤالين للسياق: كم عدد الصفوف في الجدول المستهدف (أقل من 50 ألفًا، بين 50 ألفًا و5 ملايين، أكثر من 5 ملايين)، وهل تغلّف أداة النشر تعليمات DDL داخل معاملة. ولهذا يوجد الحكم الثالث: بعض الأوامر خطرة فقط عند حجم جدول معين أو داخل كتلة معاملة.

ما يبحث عنه كتالوج القواعد

القواعد مكتوبة بلغة TypeScript، ويسرد المستودع اثني عشر فحصًا: CREATE INDEX العادي مقابل CREATE INDEX CONCURRENTLY، واستخدام CONCURRENTLY داخل غلاف معاملة، والأعمدة المضافة مع default، وإعادة كتابة الجدول بسبب ALTER COLUMN TYPE، والمفاتيح الأجنبية بدون NOT VALID، و VALIDATE CONSTRAINT، و SET NOT NULL، و DROP COLUMN، وإعادة التسمية، وبناء unique constraint مباشرة، و TRUNCATE، وأوامر إعادة الكتابة مثل VACUUM FULL و CLUSTER.

لكل واحد منها ثمن حقيقي. فـ CREATE INDEX العادي يمنع الكتابة طوال مدة البناء، بينما يتجنب CREATE INDEX CONCURRENTLY ذلك لكنه لا يعمل داخل معاملة. وإضافة عمود بقيمة default ثابتة رخيصة في PostgreSQL الحديث، لكن default من نوع expression أو volatile يعيد كتابة الجدول كاملًا. و ALTER COLUMN TYPE يعيد كتابة الجدول عادة ويحتفظ بقفل صارم أثناء ذلك. والمفتاح الأجنبي المضاف بدون NOT VALID يتحقق فورًا من كل الصفوف القائمة؛ أما إضافته بـ NOT VALID ثم تشغيل VALIDATE CONSTRAINT لاحقًا فيقسّم العمل إلى مرحلتين. وإعادة التسمية و DROP COLUMN خطرهما من نوع آخر: أثناء النشر التدريجي لا تزال نسخ التطبيق القديمة تعمل وتستعلم بالاسم القديم.

العمل محليًا وسطر الأوامر

يجري التحليل كله في تبويب المتصفح. لا تُكتب المخازن المؤقتة على القرص، ولا يُرسل شيء إلى الخادم، وبحسب قسم الخصوصية في المشروع لا يوجد مسار API يستقبل SQL الملصق، ولا روابط قاعدة بيانات، ولا قياسات عن بعد. المحرك نفسه متاح أيضًا كأداة سطر أوامر: الأمر npx safe-not-safe check migration.sql يطبع نتيجة التحليل في الطرفية.

البنية واجهة React مبنية بـ Vite؛ ويعمل المحلل داخل Web Worker مهيأ مسبقًا حتى لا تتجمد الواجهة أثناء ترجمة WASM. هدف الإنتاج هو Cloudflare Workers، وتهيئته لا تتضمن عن قصد روابط D1 أو R2 أو KV. الشيفرة مفتوحة على GitHub في مستودع viggy28/safe-not-safe.