DEV Community

Cover image for دليل المطور الكامل لاستخدام سوباس (Supabase) CLI: إصدار 2026
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

دليل المطور الكامل لاستخدام سوباس (Supabase) CLI: إصدار 2026

#backend #cli #database #tutorial

ملخص سريع

Supabase CLI يشغل حزمة Supabase الكاملة على جهازك باستخدام Docker: PostgreSQL، المصادقة (Auth)، التخزين (Storage)، ودوال الحافة (Edge Functions). ثبّت الأداة عبر:

brew install supabase/tap/supabase
Enter fullscreen mode Exit fullscreen mode

ثم:

  • شغل supabase init داخل مجلد مشروعك
  • شغل supabase start لإعداد البيئة المحلية
  • استخدم supabase db push وsupabase functions deploy للنشر إلى الإنتاج

هذه الطريقة الأسرع لبناء واختبار الواجهات الخلفية لـ Supabase بدون الحاجة للسحابة.

جرّب Apidog اليوم

مقدمة

يتم اكتشاف 73% من أخطاء الواجهة الخلفية في بيئة الإنتاج لأن المطورين يتجاهلون الاختبارات المحلية. مع Supabase CLI، يمكنك تجهيز بيئة إنتاج مطابقة بالكامل على جهازك في أقل من 5 دقائق.

المشكلة: معظم المطورين إما يختبرون على الإنتاج (خطر)، أو يضيعون وقتًا في إعداد بيئات محلية غير مطابقة للسحابة. Supabase CLI يحل المشكلتين ويوفر لك بيئة Docker محلية تعكس بيئة الإنتاج بدقة.

💡 إذا كنت تبني APIs فوق Supabase، ستحتاج إلى أداة مثل Apidog لتصميم واختبار وتوثيق الـ endpoints مباشرة من جهازك. Apidog يدعم REST و GraphQL ويتكامل مع Supabase بسهولة.

اختبر واجهات Supabase API الخاصة بك باستخدام Apidog - مجانًا.

بنهاية هذا الدليل ستكون قادراً على:

  • إعداد بيئة Supabase محلية كاملة خلال دقائق
  • إدارة تغييرات المخطط عبر ترحيلات (migrations) متحكم فيها بالإصدارات
  • بناء واختبار Edge Functions محليًا
  • النشر إلى الإنتاج بأمر واحد

لماذا يفشل تطوير Supabase المحلي بدون CLI

إذا حاولت بناء تطبيق Supabase بدون CLI ستواجه غالبًا مشاكل مثل:

  • الاختبار على الإنتاج: تغييرات المخطط تتم في لوحة التحكم، وعند انضمام زميل جديد لا يجد الأعمدة الجديدة.
  • اختلاف البيئة: إعداد PostgreSQL يدويًا يؤدي لسلوك سياسات RLS غير متوقع.
  • "يعمل على جهازي": دوال الحافة تعمل محليًا وتفشل على الإنتاج بسبب متغيرات البيئة.

الحل:

  • الترحيلات (migrations) تحفظ تغييرات المخطط بشكل منظم وقابل للتكرار
  • Docker المحلي يحاكي الإنتاج (نفس إصدار PostgreSQL، RLS إلخ)
  • الدوال المحلية تتفاعل مع متغيرات بيئة حقيقية

كيف يعمل Supabase CLI

الحزمة المحلية

عند تشغيل supabase start، يتم تشغيل Docker Compose بهذه الخدمات:

الخدمة المنفذ الغرض
PostgreSQL 54322 قاعدة البيانات
PostgREST 54321 REST API تلقائي
GoTrue 54321/auth المصادقة
Realtime 54321/realtime اشتراكات WebSocket
Storage 54321/storage تخزين الملفات
Studio 54323 لوحة تحكم مرئية
Inbucket 54324 اختبار البريد الإلكتروني
Edge Runtime 54321/functions تشغيل دوال Deno

هذه نفس الحزمة المشغلة في Supabase Cloud.

التثبيت

macOS:

brew install supabase/tap/supabase
Enter fullscreen mode Exit fullscreen mode

Windows (Scoop):

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
Enter fullscreen mode Exit fullscreen mode

Linux / npm:

npm install -g supabase
Enter fullscreen mode Exit fullscreen mode

تحقق من التثبيت:

supabase --version
Enter fullscreen mode Exit fullscreen mode

إعداد المشروع 

mkdir my-project && cd my-project
supabase init
Enter fullscreen mode Exit fullscreen mode

ينشئ المسار:

supabase/
├── config.toml       # إعدادات المنافذ والمصادقة والتخزين
├── seed.sql          # بيانات التطوير
└── migrations/       # ترحيلات المخطط
Enter fullscreen mode Exit fullscreen mode

بدء تشغيل الحزمة المحلية 

supabase start
Enter fullscreen mode Exit fullscreen mode

أول تشغيل ينزل صور Docker (~1GB)، ثم التشغيل التالي خلال ثوانٍ.

انسخ anon key من المخرجات إلى .env.local لواجهتك الأمامية.

إدارة قاعدة البيانات باستخدام الترحيلات (migrations)

إنشاء أول ترحيل 

supabase migration new create_posts_table
# ينشئ: supabase/migrations/20260324120000_create_posts_table.sql
Enter fullscreen mode Exit fullscreen mode

ثم عدّل الملف ليحتوي على:

-- إنشاء جدول posts مع RLS من البداية
CREATE TABLE posts (
  id          UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id     UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  title       TEXT NOT NULL,
  content     TEXT,
  published   BOOLEAN DEFAULT false,
  created_at  TIMESTAMPTZ DEFAULT NOW(),
  updated_at  TIMESTAMPTZ DEFAULT NOW()
);

ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Anyone can read published posts"
  ON posts FOR SELECT
  USING (published = true);

CREATE POLICY "Users manage own posts"
  ON posts FOR ALL
  USING (auth.uid() = user_id);

CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER posts_updated_at
  BEFORE UPDATE ON posts
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
Enter fullscreen mode Exit fullscreen mode

لتطبيق التغييرات:

supabase migration up
Enter fullscreen mode Exit fullscreen mode

توليد أنواع TypeScript

بعد كل تغيير مخطط:

supabase gen types typescript --local > src/types/database.ts
Enter fullscreen mode Exit fullscreen mode

الآن لديك أمان للأنواع في الواجهة الأمامية:

import { Database } from '@/types/database'

type Post = Database['public']['Tables']['posts']['Row']
type NewPost = Database['public']['Tables']['posts']['Insert']

const createPost = async (post: NewPost) => {
  const { data, error } = await supabase
    .from('posts')
    .insert(post)
    .select()
    .single()
  return data
}
Enter fullscreen mode Exit fullscreen mode

تغذية بيانات التطوير

عدّل supabase/seed.sql:

INSERT INTO auth.users (id, email) VALUES
  ('00000000-0000-0000-0000-000000000001', 'alice@example.com'),
  ('00000000-0000-0000-0000-000000000002', 'bob@example.com');

INSERT INTO posts (user_id, title, content, published) VALUES
  ('00000000-0000-0000-0000-000000000001', 'Getting started with Supabase', 'Here is what I learned...', true),
  ('00000000-0000-0000-0000-000000000002', 'Draft: API design patterns', 'Work in progress...', false);
Enter fullscreen mode Exit fullscreen mode

لإعادة الضبط والتغذية:

supabase db reset
Enter fullscreen mode Exit fullscreen mode

اختبار واجهات Supabase API باستخدام Apidog

بعد تشغيل Supabase محليًا، لديك REST API على http://localhost:54321. نقاط النهاية يتم توليدها تلقائيًا لكل جدول.

Apidog يتصل مباشرة بنسختك المحلية ويتيح لك:

  • حفظ الطلبات كمجموعات
  • اختبار نفس الـ endpoint كمستخدمين مختلفين عبر البيئات
  • إضافة تأكيدات تلقائية وتشغيلها كاختبارات
  • مشاركة توثيق API مع الفريق

خطوات إعداد Apidog مع Supabase المحلي:

  1. أنشئ مشروعًا جديدًا في Apidog
  2. اجعل عنوان الـ base URL: http://localhost:54321
  3. أضف متغير بيئة: anon_key = مفتاحك المجهول
  4. أضف Header: Authorization: Bearer {{anon_key}}

اختبار نقطة posts: 

GET http://localhost:54321/rest/v1/posts?published=eq.true
Authorization: Bearer {{anon_key}}
apikey: {{anon_key}}
Enter fullscreen mode Exit fullscreen mode

احفظ الطلب وأضف تأكيدًا للاستجابة، وشغله عند تحديث سياسات RLS.

ابدأ اختبار واجهات Supabase API مع Apidog - مجانًا.

دوال الحافة (Edge functions): البناء والاختبار محليًا

دوال الحافة تعمل على Deno وقريبة من المستخدمين – مناسبة للويب هوك والمهام الخلفية.

إنشاء دالة 

supabase functions new send-welcome-email
Enter fullscreen mode Exit fullscreen mode

سينشئ: supabase/functions/send-welcome-email/index.ts:

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  const { user_id } = await req.json()

  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
  )

  const { data: profile } = await supabase
    .from('profiles')
    .select('email, full_name')
    .eq('id', user_id)
    .single()

  console.log(`إرسال بريد ترحيب إلى ${profile?.email}`)

  return new Response(
    JSON.stringify({ success: true }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})
Enter fullscreen mode Exit fullscreen mode

الاختبار محليًا مع إعادة التحميل السريع 

supabase functions serve
Enter fullscreen mode Exit fullscreen mode

اختبر بالدالة عبر:

curl -X POST http://localhost:54321/functions/v1/send-welcome-email \
  -H "Authorization: Bearer YOUR_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "00000000-0000-0000-0000-000000000001"}'
Enter fullscreen mode Exit fullscreen mode

النشر إلى الإنتاج 

# نشر دالة واحدة
supabase functions deploy send-welcome-email

# نشر جميع الدوال
supabase functions deploy
Enter fullscreen mode Exit fullscreen mode

تقنيات متقدمة وممارسات مثبتة

إدارة الأسرار

لا تضع المفاتيح مباشرة في الكود. استخدم:

supabase secrets set RESEND_API_KEY=re_xxx STRIPE_KEY=sk_live_xxx
supabase secrets list
supabase secrets unset STRIPE_KEY
Enter fullscreen mode Exit fullscreen mode

داخل الدوال:

const resendKey = Deno.env.get('RESEND_API_KEY')
Enter fullscreen mode Exit fullscreen mode

تفريعات قاعدة البيانات

لتجربة تغييرات كبيرة:

supabase branches create feature-payments
supabase branches switch feature-payments

# بعد الاختبار:
supabase branches merge feature-payments
Enter fullscreen mode Exit fullscreen mode

الأخطاء الشائعة:

  • تحرير قاعدة البيانات مباشرة في Studio: استخدم الترحيلات دائمًا.
  • التزام ملفات .env: استخدم supabase secrets set للإنتاج.
  • تخطي supabase db reset بعد السحب: شغل الترحيلات بعد كل تحديث.
  • عدم توليد الأنواع بعد تعديل المخطط.
  • نشر دوال بدون اختبار محلي.
  • استخدام مفتاح الخدمة في الواجهة الأمامية (خطر أمني).

نصائح الأداء 

# استثنِ الخدمات غير الضرورية
supabase start --exclude-studio --exclude-inbucket

# راقب استهلاك الموارد
docker stats
Enter fullscreen mode Exit fullscreen mode

البدائل والمقارنات

الميزة Supabase CLI Firebase CLI PlanetScale CLI
قاعدة بيانات محلية PostgreSQL محاكي فقط سحابي فقط
الترحيلات SQL في Git لا يوجد التفريعات
دوال الحافة Deno دوال سحابية غير متضمن
المصادقة محليًا GoTrue محاكي غير متضمن
مفتوح المصدر نعم لا لا
توليد الأنواع مدمج يدوي يدوي

محاكي Firebase جيد للنماذج الأولية لكنه لا يوفر PostgreSQL حقيقي. PlanetScale جيد للتفريعات لكنك تعمل دائمًا ضد السحابة. Supabase CLI هو الخيار الأمثل لتجربة تطوير محلية مفتوحة المصدر بالكامل.

حالات استخدام واقعية

  • تطبيق SaaS متعدد المستأجرين: إدارة 47 ترحيل عبر 3 بيئات دون مشاكل إنتاج متعلقة بالمخطط.
  • معالجة التجارة الإلكترونية: اختبار webhooks Stripe بدوال الحافة محليًا، تقليل وقت النشر من ساعتين إلى 15 دقيقة.
  • واجهة خلفية لتطبيق جوال: توليد أنواع TypeScript بعد كل ترحيل ومشاركتها كحزمة npm داخلية، مزامنة تلقائية بين الواجهة الأمامية والخلفية.

الخلاصة

يمكنك الآن:

  • إعداد بيئة Supabase محلية كاملة خلال دقائق
  • توثيق كل تغيير بالمخطط عبر الترحيلات
  • اختبار Edge Functions محليًا مع hot reload
  • توليد أنواع TypeScript تلقائيًا
  • النشر بـ supabase db push وsupabase functions deploy
  • اختبار واجهاتك مع Apidog قبل النشر

سير العمل هذا يوفر الوقت ويقلل الأخطاء ويمنع انحراف المخطط.

خطواتك التالية:

  1. التثبيت: brew install supabase/tap/supabase
  2. شغل supabase init في مشروعك
  3. أنشئ أول ترحيل
  4. أعد ضبط Apidog لاختبار نقاط النهاية المحلية
  5. انشر بثقة

اختبر واجهات Supabase API الخاصة بك باستخدام Apidog - مجانًا

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

هل أحتاج إلى Docker لاستخدام Supabase CLI؟

نعم. يجب أن يكون Docker Desktop قيد التشغيل عند استخدام supabase start. إذا لم يكن Docker يعمل، ستحصل على خطأ "لا يمكن الاتصال بـ Docker".

كيف أقوم بمزامنة قاعدة بياناتي المحلية مع الإنتاج؟

استخدم supabase db pull لجلب المخطط من الإنتاج، ثم supabase db push لتطبيق الترحيلات. بعد السحب شغل supabase db reset لضمان التطابق.

هل يمكنني استخدام Supabase CLI بدون حساب Supabase Cloud؟

نعم. يمكنك العمل محليًا بالكامل. تحتاج إلى supabase login وsupabase link فقط عند النشر للإنتاج.

كيف أتعامل مع تعارضات الترحيلات في الفريق؟

اسحب آخر تغييرات Git، ثم شغل supabase db reset قبل إنشاء ترحيلات جديدة. استخدم أسماء وصفية وتواصل مع فريقك عند التغييرات الكبيرة.

ما الفرق بين supabase db push وsupabase migration up؟

supabase migration up يطبق الترحيلات على البيئة المحلية.

supabase db push يطبق الترحيلات على الإنتاج. اختبر محليًا دائمًا أولًا.

هل يمكنني استخدام Supabase CLI مع مشروع قائم؟

نعم. اربط بمشروعك عبر

supabase link --project-ref YOUR_PROJECT_ID
Enter fullscreen mode Exit fullscreen mode

ثم

supabase db pull
Enter fullscreen mode Exit fullscreen mode

لتوليد الترحيلات.

كيف أختبر سياسات RLS محليًا؟

استخدم Supabase Studio على http://localhost:54323 أو اختبر من خلال API برموز JWT مختلفة. Apidog يسهل ذلك بإنشاء بيئات متعددة برموز مستخدم مختلفة.

هل Supabase CLI مجاني؟

نعم، CLI مجاني ومفتوح المصدر. التطوير المحلي مجاني بالكامل، وتدفع فقط مقابل موارد Supabase Cloud عند النشر.

Top comments (0)