دليل حل تعارضات ترحيل Prisma
لا تقم بتشغيل prisma migrate reset على قاعدة بيانات الإنتاج (production).
إذا ظهرت لك رسالة تفيد بأن عملية ترحيل قد تم تعديلها أو أنك بحاجة إلى إعادة ضبط المخطط (schema)، فتوقف فوراً. إعادة الضبط ستؤدي إلى حذف جميع بياناتك. يمكنك حل هذه التعارضات يدوياً دون فقدان أي شيء.
أخطاء Prisma الشائعة وكيفية إصلاحها
خطأ: فشلت عملية الترحيل أثناء التشغيل (P3018)
• قم بإصلاح ملف SQL.
• قم بتشغيل: npx prisma migrate resolve --rolled-back [migration_name]
• قم بتشغيل: npx prisma db execute --file [path_to_sql_file]
• قم بتشغيل: npx prisma migrate resolve --applied [migration_name]
خطأ: تم تعديل عملية الترحيل بعد تطبيقها (عدم تطابق Checksum)
• احسب هاش SHA-256 لملف الترحيل الحالي الخاص بك.
• قم بتحديث الـ checksum في جدول _prisma_migrations.
• هام: قم بتحديث جميع الصفوف الخاصة باسم عملية الترحيل تلك. لا تقم بالتصفية باستخدام rolled_back_at.
خطأ: عمود قاعدة بيانات الظل (Shadow database) مفقود (P3006) • يحدث هذا عندما تشير عملية ترحيل إلى عمود تقوم عملية ترحيل لاحقة بإنشائه. • تقوم Prisma بإعادة تشغيل عمليات الترحيل بترتيب الطابع الزمني (timestamp). • الحل: انقل كود SQL إلى عملية الترحيل التي يتم فيها إنشاء العمود لأول مرة.
خطأ: عملية DROP COLUMN محظورة بواسطة سياسة RLS
• تقوم خاصية Row Level Security في PostgreSQL بربط السياسات بالأعمدة.
• الحل: استخدم CASCADE عند حذف الأعمدة.
• مثال: ALTER TABLE "my_table" DROP COLUMN IF EXISTS "tenant_id" CASCADE;
أفضل الممارسات لعمليات ترحيل آمنة
- استعلم من قاعدة البيانات أولاً. لا تخمن ما إذا كان العمود أو الفهرس (index) موجوداً أم لا. استخدم استعلامات SQL مباشرة للتحقق من مخطط قاعدة البيانات الفعلي قبل كتابة كود الترحيل.
- استخدم
IF EXISTSوIF NOT EXISTS. هذا يجعل عمليات الترحيل الخاصة بك "idempotent" (متماثلة النتائج). عملية الترحيل الـ idempotent يمكن تشغيلها عدة مرات دون التسبب في أخطاء. - استخدم كتل
DOللقيود (constraints). قم بتغليف عمليات إضافة المفتاح الأجنبي (Foreign Key) في فحص للتأكد مما إذا كان اسم القيد موجوداً بالفعل. - استخدم دائماً
CASCADEعند الحذف إذا كنت تستخدم Row Level Security.
جدول ملخص
• P3018 (فشلت أثناء التشغيل): أصلح SQL، ثم استخدم resolve --rolled-back و resolve --applied.
• عدم تطابق Checksum: احسب هاش جديد وحدث جميع الصفوف في _prisma_migrations.
• خطأ Shadow DB: تحقق من ترتيب الطابع الزمني وانقل منطق SQL.
• خطأ RLS: أضف CASCADE إلى جمل DROP الخاصة بك.