كيفية استيراد CSV إلى Supabase

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

للملفات التي يرفعها العملاء باستمرار، استخدم قائمة مراجعة بنية أداة استيراد CSV. وتفترض بقية هذه الصفحة أن مهندسًا يجهز عملية استيراد محددة.

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

في جدول جهات اتصال، قد يحتوي المصدر المعتمد على هذين الحقلين فقط:

email,display_name
first@example.test,First Contact
second@example.test,"Second, Contact"

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

راجع العناوين المكررة وروابط الحقول قبل الاستيراد. وجود عمودين في المصدر باسم «Email» يتطلب اختيارًا صريحًا. ينبغي استبعاد الأعمدة الزائدة عن قصد. لا تستنتج أن حقول id أو tenant_id أو created_at في الملف يجب أن تكون قابلة للكتابة لمجرد تطابق أسمائها.

صدّر ورقة العمل المقصودة بصيغة CSV بترميز UTF-8، ثم استخدم مسار الاستيراد نفسه. في Google Sheets، استخدم ملف ← تنزيل ← قيم مفصولة بفواصل (File → Download → Comma-separated values) للورقة الحالية. في Excel، احفظ نسخة بتنسيق CSV UTF-8. قد يضم المصنف عدة أوراق؛ أما CSV فيمثل جدولًا مسطحًا واحدًا. تغيير امتداد ملف XLSX إلى CSV لا يحوّل تنسيقه.

افحص النص المصدّر قبل رفعه. تحقق من معرّف يبدأ بأصفار، وتاريخ، وعدد عشري، وأي خلية ناتجة عن صيغة. إذا كان برنامج الجداول قد حوّل 00042 بالفعل إلى 42، فلن يعيد التصدير بترميز UTF-8 الأصفار المفقودة. ارجع إلى المصدر أو احصل على تصحيح معتمد.

احسم تفسير تواريخ مثل 04/05/2026 مع مالك البيانات. لا تخمّن إن كان المقصود 5 أبريل أم 4 مايو. سجّل المنطقة الزمنية المقصودة للطوابع الزمنية؛ ويجب ألا يخضع تاريخ ذكرى سنوية بلا وقت لتحويل منطقة زمنية عن غير قصد. المزامنة المستمرة مع ورقة نشطة متطلب مختلف عن هذا التصدير لمرة واحدة.

أعدّ قائمة قصيرة تحدد الجهة المسؤولة عن قيم كل حقل قبل أول عملية كتابة. مثلًا: يأتي البريد الإلكتروني واسم العرض من المصدر المعتمد؛ ويأتي المستأجر من سياق تطبيق مخوّل؛ وتأتي الهوية من PostgreSQL؛ ويتبع الطابع الزمني للتدقيق القاعدة التي اختارها التطبيق.

القيمة الافتراضية العادية لا تمنع تقديم قيم من المصدر. أما التعبير المولّد فله سلوك مختلف. كذلك قد يؤدي غياب عمود، أو تقديم NULL صراحةً، أو تقديم سلسلة فارغة إلى نتائج مختلفة. يوضح دليل القيم الافتراضية والمولّدة هذه الفروق.

تحقق مما يتوقعه جدولك المستهدف باستخدام PG Import Check إذا كانت لديك أوامر SQL للترحيل أو أوامر DDL. تعرض الأداة التصريحات البنيوية المدعومة محليًا في متصفحك. وهي لا تفحص الصفوف الفعلية، ولا تتحقق من CSV، ولا تحسم سياسات RLS الفعلية، ولا تعتمد عملية استيراد إلى بيئة الإنتاج. طابق مدخلاتها بنفسك مع مخطط قاعدة البيانات المنشور فعليًا.

يستخدم هذا الاختبار المسبق الصغير جدولًا مؤقتًا في قاعدة بيانات PostgreSQL 17 قابلة للتخلص منها. وهو يختبر آليات CSV دون المساس بجدول في التطبيق. أنشئ الجدول داخل جلسة psql متصلة:

CREATE TEMP TABLE import_contacts_demo (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  email text NOT NULL UNIQUE,
  display_name text,
  created_at timestamptz NOT NULL DEFAULT now()
);

احفظ ملف CSV أعلاه باسم contacts.csv في مجلد العمل لدى العميل، ثم نفّذ الأمر التالي في سطر واحد داخل psql:

\copy import_contacts_demo (email, display_name) FROM 'contacts.csv' WITH (FORMAT csv, HEADER MATCH, ENCODING 'UTF8')

SELECT id, email, display_name, created_at
FROM import_contacts_demo
ORDER BY id;

توقّع صفين، ومعرّفات مولّدة متميزة، وبقاء الفاصلة في الاسم الثاني، وطوابع زمنية من قاعدة البيانات. تترك قائمة الأعمدة الصريحة توليد المعرّف والطابع الزمني لقاعدة البيانات. في PostgreSQL 17، يتحقق HEADER MATCH من الأسماء وترتيبها. أما HEADER true وحده فيتجاوز صف العناوين؛ ولا يربط القيم بحسب الأسماء.

يقرأ أمر النسخ ذي الشرطة المائلة العكسية في psql ملفًا من جهاز العميل ويرسله عبر اتصال قاعدة البيانات. أما COPY FROM '/path' الذي ينفذه الخادم فيقرأ نظام ملفات خادم قاعدة البيانات. لا يستطيع Supabase قراءة مسار على حاسوبك بهذه الطريقة.

لاتصال فعلي بـSupabase، احصل على نقطة الاتصال وإعدادات SSL الصحيحة من تعليمات الاتصال الخاصة بالمشروع. أبقِ كلمات المرور خارج الأوامر المحفوظة وGit ولقطات الشاشة. اطلب من مالك قاعدة البيانات اختيار دور التنفيذ ونمط الاتصال؛ فمثال الجدول المؤقت هذا لا يحدد صلاحيات بيئة الإنتاج.

قد يحتوي ملف العميل على تسمية مثل «حساب نشط»، بينما يتوقع نوع التعداد لديك active. يتيح لك التمثيل الوسيط في منطقة التجهيز الاحتفاظ بالقيمة الأصلية بجانب القيمة المقترحة وسبب التغيير. يعتمد صاحب القرار في العمل هذا التحويل، ثم تطبقه أداة الاستيراد باتساق.

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

يتوقف سلوك COPY الافتراضي في PostgreSQL عند حدوث خطأ. المعاملة التي يجري التراجع عنها لا تترك صفوفها المدرجة مثبتة، لكن الدفعات السابقة التي ثُبّتت كل منها على حدة تبقى. البرنامج النصي الذي ينفذ عشرة طلبات بنجاح ويفشل في الطلب الحادي عشر يترك نتيجة جزئية. لا تُعد تشغيل الملف كله اعتمادًا على الخطأ الأخير وحده.

أبقِ القيود والمشغلات ضمن المراجعة. يحتاج المفتاح الأجنبي إلى سجل مرجعي في الوجهة، ولا يكفي رقم من النوع الصحيح. قد يرفض المشغّل صفًا أو يغيّره، وقد يبدأ أعمالًا أخرى. لا تعطّل فحوص سلامة البيانات بوصف ذلك حلًا معتادًا لملف مرفوض. راجع دليل استيراد المفاتيح الأجنبية عندما تختلف معرّفات المصدر عن معرّفات الوجهة.

للملفات الكبيرة، قِس مدة التنفيذ، واستخدام القرص، ونمو WAL، والأقفال، وزمن استجابة التطبيق في اختبار مسبق ممثل للحالة الفعلية. اختر دفعات محدودة أو نافذة صيانة استنادًا إلى هذه الأدلة. الحد الأقصى لحجم الملف في لوحة التحكم ليس ضمانًا للأداء في أي مسار آخر.

احسب سجلات المصدر بعد تحليلها، وسجّل الاستبعادات المعتمدة، وقارن المجموعة المقبولة الناتجة بالوجهة. إذا قُبلت 200 جهة اتصال، فإن إدراج 200 صف دليل مفيد. ومع ذلك، قد تكون جهات الاتصال المئتان خاطئة، أو تكون صحيحة لكنها مسندة إلى المستأجر الخطأ.

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

يقدم دليل التحقق بعد الاستيراد أمثلة قابلة للتنفيذ تكشف المفاتيح المفقودة والقيم غير المتطابقة. احتفظ بالمصدر المعتمد وروابط الحقول والنتيجة معًا وفق سياسة احتفاظ متفق عليها. تجعل هذه السجلات معالجة محاولة فاشلة أو تصحيح يطلبه العميل أسهل كثيرًا.