الدليل الكامل للنسخ الاحتياطي التلقائي لقاعدة بيانات Supabase (الخطة المجانية) باستخدام GitHub Actions

أصبحت Supabase بديلاً قوياً ومحبوباً لـ Firebase، حيث توفر للمطورين قاعدة بيانات Postgres جاهزة، ونظام مصادقة، وتخزين ملفات، وواجهات برمجية تلقائية. ولكن، مع روعة الخطة المجانية التي تقدمها، تأتي معها مسؤولية كبيرة: الحفاظ على بياناتك. الخطة المجانية لا توفر نسخاً احتياطياً تلقائياً، وفقدان البيانات قد يكون كارثياً لأي مشروع.

في هذا الدليل المفصل، سنتعلم خطوة بخطوة كيف نقوم بإعداد نظام نسخ احتياطي تلقائي ومجاني بالكامل لقاعدة بيانات Supabase، باستخدام أداة قوية ومدمجة مع نظام عمل كل المطورين: GitHub Actions. في نهاية هذا المقال، سيكون لديك workflow يعمل يومياً لأخذ نسخة كاملة من قاعدة بياناتك وحفظها بأمان في مستودع GitHub الخاص بك.

القسم الأول: لماذا نحتاج إلى هذا الحل؟

1. قيود الخطة المجانية: كما ذكرنا، لا توجد نسخ احتياطية مدمجة في الخطة المجانية لـ Supabase.
2. الأمان ضد الأخطاء البشرية: قد تقوم بحذف جدول أو بيانات مهمة عن طريق الخطأ. النسخة الاحتياطية هي شبكة الأمان الخاصة بك.
3. الأتمتة الكاملة: بمجرد إعداده، سيعمل النظام تلقائياً دون أي تدخل منك. “اضبطه وانسَه”.
4. حل مجاني ومتكامل: نعتمد على أدوات مجانية (خطة GitHub المجانية) ومتكاملة مع بيئة التطوير.

القسم الثاني: المتطلبات الأساسية

قبل أن نبدأ، تأكد من أن لديك التالي:

• مشروع Supabase فعال: لديك قاعدة بيانات وبيانات تريد الحفاظ عليها.
• مستودع (Repository) على GitHub: حيث سيتم حفظ الكود وملفات النسخ الاحتياطي.
  • 🔴 تنبيه هام جداً: يجب أن يكون هذا المستودع خاصاً (Private). حفظ نسخة من قاعدة بياناتك في مستودع عام يعرض جميع بياناتك للخطر.
• بيانات الاتصال بقاعدة البيانات: ستحتاج إلى معلومتين أساسيتين من لوحة تحكم Supabase:
  1. Project ID: تجده في Project Settings > General.
  2. Database Password: كلمة المرور التي قمت بتعيينها لقاعدة البيانات من Project Settings > Database.

القسم الثالث: إعداد أسرار المستودع (GitHub Secrets)

لأسباب أمنية، لا يجب أبداً كتابة كلمات المرور أو البيانات الحساسة مباشرة في ملفات الكود. سنستخدم ميزة GitHub Secrets لتخزين بيانات الاتصال بأمان.

1. اذهب إلى مستودعك على GitHub.
2. اضغط على تبويب Settings.

1. من القائمة الجانبية، اختر Secrets and variables > Actions.
2. اضغط على زر New repository secret وأنشئ السرين التاليين:

1. السر الأول:
   • Name: PROJECT_ID
   • Secret: الصق هنا الـ Project ID الخاص بمشروعك في Supabase.
2. السر الثاني:
   • Name: SUPABASE_DB_PASSWORD
   • Secret: الصق هنا كلمة مرور قاعدة البيانات الخاصة بك.

الآن أصبحت بياناتنا الحساسة مخزنة بأمان وجاهزة للاستخدام داخل الـ workflow.

القسم الرابع: إنشاء وإعداد ملف الـ Workflow

هذا هو قلب ومحرك نظامنا. سنقوم بإنشاء ملف يخبر GitHub بما يجب عليه فعله ومتى.

1. في المستودع الخاص بك، على جهازك المحلي أنشئ المجلدات والملف التالي: .github/workflows/supabase_backup.yml
   تأكد ان اسم المجلد .github يبدأ بنقطة والا لن يعمل التدفق
2. افتح ملف supabase_backup.yml والصق الكود التالي بالكامل بداخله. هذا هو الكود النهائي والكامل الذي يعمل بعد تخطي جميع المشاكل.

YAML

name: Supabase DB Backup

on:
  # يتيح لك تشغيل هذا الـ workflow يدوياً من صفحة Actions للاختبار
  workflow_dispatch:
  
  # جدولة للتشغيل التلقائي كل يوم الساعة 2 صباحاً بتوقيت UTC
  schedule:
    - cron: '0 2 * * *'

jobs:
  backup:
    runs-on: ubuntu-latest

    # 🔴 الخطوة 1: منح صلاحيات الكتابة
    # بشكل افتراضي، لا يمكن للـ workflow الدفع (push) إلى المستودع.
    # هذا السطر يمنحه الإذن اللازم.
    permissions:
      contents: write

    steps:
      # الخطوة 2: سحب الكود من المستودع
      - name: Checkout repository
        uses: actions/checkout@v4

      # الخطوة 3: تثبيت الأدوات اللازمة
      # نحتاج إلى postgresql-client لتشغيل أمر pg_dump
      - name: Install PostgreSQL Client
        run: |
          sudo apt-get update
          sudo apt-get install -y postgresql-client

      # الخطوة 4: إنشاء مجلد مخصص لحفظ النسخ الاحتياطية
      - name: Create backup directory
        run: mkdir -p supabase_backups

      # الخطوة 5: أخذ نسخة احتياطية من قاعدة البيانات
      # هذه هي الخطوة الأساسية في العملية
      - name: Run Supabase DB Backup
        env:
          PGPASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
        run: |
          pg_dump \
            --host "aws-0-eu-central-1.pooler.supabase.com" \
            --port "6543" \
            --username "postgres.${{ secrets.PROJECT_ID }}" \
            --dbname "postgres" \
            --file "supabase_backups/backup-$(date +%Y-%m-%d).sql" \
            --verbose

      # الخطوة 6: رفع النسخة الاحتياطية إلى المستودع
      - name: Commit and Push Backup
        run: |
          git config --global user.name "GitHub Action"
          git config --global user.email "action@github.com"
          # استخدام -f لإجبار git على إضافة الملف حتى لو كان في .gitignore
          git add -f supabase_backups/backup-*.sql
          if git diff-index --quiet HEAD; then
            echo "No changes to commit."
          else
            git commit -m "chore: Add Supabase DB backup for $(date +%Y-%m-%d)"
            git push
          fi

القسم الخامس: تشخيص المشاكل الشائعة (شرح الأخطاء التي واجهناها)

أثناء إعداد هذا النوع من الـ workflows، من الشائع مواجهة بعض العقبات. إليك شرح للمشاكل التي تغلبنا عليها وكيفية حلها، لتكون على دراية بها:

1. المشكلة الأولى: “Network is unreachable”
   • السبب: خوادم GitHub Actions قد تواجه صعوبة في الاتصال بخوادم Supabase عبر بروتوكول الإنترنت IPv6 (الاتصال المباشر).
   • الحل: استخدمنا Connection Pooler الذي يوفره Supabase، لأنه يعمل عبر بروتوكول IPv4 المتوافق مع GitHub Actions. لهذا السبب تجد في الكود أن host و port و username تختلف عن بيانات الاتصال المباشر.
2. المشكلة الثانية: “File is ignored by .gitignore”
   • السبب: العديد من المطورين يضعون قاعدة في ملف .gitignore لتجاهل ملفات .sql لمنع رفعها عن طريق الخطأ.
   • الحل: أضفنا علامة -f (force) إلى أمر git add. هذا يخبر Git بأننا نريد إضافة هذا الملف تحديداً في هذه العملية الآلية، متجاوزين قواعد التجاهل.
3. المشكلة الثالثة: “Write access to repository not granted (Error 403)”
   • السبب: كإجراء أمني، GitHub Actions تمتلك صلاحيات القراءة فقط بشكل افتراضي. لا يمكنها تعديل الكود أو دفع تغييرات جديدة.
   • الحل: أضفنا قسم permissions: contents: write في ملف الـ workflow، والذي يمنح هذا الإجراء الإذن الصريح للكتابة في المستودع.

القسم السادس: التحقق من النجاح وماذا بعد؟

بعد رفع الملف، يمكنك الذهاب إلى تبويب Actions في مستودعك وتشغيل الـ workflow يدوياً عبر workflow_dispatch للتأكد من أنه يعمل. إذا نجحت جميع الخطوات، ستجد مجلداً جديداً اسمه supabase_backups في مستودعك، وبداخله ملف .sql يحمل تاريخ اليوم.

هذا الملف هو كنزك. إنه يحتوي على نسخة نصية من قاعدة بياناتك بالكامل، هيكلاً وبيانات. إذا حدث أي طارئ، يمكنك استخدام هذا الملف لاستعادة قاعدة بياناتك إلى حالتها السابقة باستخدام أداة psql القياسية في PostgreSQL.

خاتمة

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