خطأ في تسلسل PostgreSQL لـ TypeScript: "العلاقة 'customers_sq' غير موجودة"

فهم أخطاء تسلسل PostgreSQL في Upserts

قد يؤدي العمل مع PostgreSQL وTypeScript، خصوصًا أثناء عملية upsert، أحيانًا إلى أخطاء تسلسلية غير متوقعة. أحد هذه الأخطاء الشائعة يتضمن عدم تعرف قاعدة البيانات على التسلسل، مما يؤدي إلى ظهور رسائل مثل "العلاقة 'customers_sq' غير موجودة". يحدث هذا الخطأ عادةً عند الإشارة إلى التسلسلات بشكل غير صحيح ضمن استعلامات SQL.

في هذه المقالة، سوف نستكشف سيناريو حقيقي حيث يواجه المطور هذه المشكلة أثناء إجراء عملية تحديث. سنناقش كيفية عمل التسلسلات في PostgreSQL ونحدد الأخطاء الشائعة عند الرجوع إليها، خاصة في TypeScript.

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

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

يأمر	مثال للاستخدام
NEXTVAL('sequence_name')	تقوم وظيفة PostgreSQL هذه باسترداد القيمة التالية من تسلسل محدد. يعد أمرًا بالغ الأهمية في إنشاء معرفات فريدة للصفوف أثناء عمليات الإدراج. مثال: NEXTVAL('db.customers_sq') يجلب القيمة التالية من ملف تسلسل في مخطط "ديسيبل".
ON CONFLICT ("column") DO UPDATE	يستخدم هذا الأمر في عمليات PostgreSQL، ويتعامل مع الحالات التي يؤدي فيها الإدراج إلى تعارض في عمود فريد. بدلاً من الفشل، يقوم بتحديث الصف المتعارض. مثال: في حالة الصراع ("المعرف")، قم بتحديث "الاسم" = $1.
pg_sequences	عرض كتالوج PostgreSQL الذي يوفر معلومات حول كافة التسلسلات في قاعدة البيانات. يُستخدم هذا للاستعلام عن البيانات التعريفية حول التسلسلات، مثل وجودها في مخطط محدد. مثال: SELECT * FROM pg_sequences حيث اسم التسلسل = 'customers_sq'؛
pool.query()	طريقة من وحدة عقدة PostgreSQL ، يستخدم لتنفيذ استعلامات SQL. فهو يتعامل مع اتصالات قاعدة البيانات بكفاءة، ويجمعها لإعادة استخدامها. مثال: يقوم Pool.query(SAVE_CUSTOMER, [name]) بتنفيذ إدراج/تحديث SQL للعميل.
mockResolvedValueOnce()	طريقة Jest المستخدمة في الاختبار. إنه يسخر من استجابة الدالة لإرجاع قيمة محددة مرة واحدة. في هذه الحالة، فإنه يحاكي التنفيذ الناجح لاستعلام قاعدة البيانات. مثال: Pool.query.mockResolvedValueOnce({}).
mockRejectedValueOnce()	تسخر وظيفة Jest هذه من الخطأ الذي يتم طرحه بواسطة الوعد، ومحاكاة استعلام فاشل. مثال: Pool.query.mockRejectedValueOnce(new Error('Sequence not Found')) يكرر خطأ حيث يكون التسلسل مفقودًا.
expect.toThrow()	تأكيد Jest يتحقق مما إذا كانت الوظيفة تلقي خطأً محددًا. يعد هذا ضروريًا لاختبار كيفية تصرف الوظيفة عند حدوث خطأ. مثال: توقع(saveCustomer('John')).rejects.toThrow('لم يتم العثور على التسلسل');.
schemaname	عمود في يشير إلى المخطط حيث يتم تعريف التسلسل. فهو يساعد على التمييز بين التسلسلات التي تحمل نفس الاسم ولكن في مخططات مختلفة. مثال: SELECT * FROM pg_sequences WHERE schemaname = 'db';.

كيفية التعامل مع أخطاء تسلسل PostgreSQL في Upserts

تم تصميم البرامج النصية المقدمة في الأمثلة السابقة لمعالجة مشكلة شائعة تنشأ عند الرجوع إلى التسلسلات في PostgreSQL، خاصة أثناء عملية العملية في TypeScript. تقوم عملية upsert إما بإدراج سجلات جديدة أو تحديث السجلات الموجودة، مما يجعل الاستخدام الصحيح للتسلسلات أمرًا حيويًا للحفاظ على المفاتيح الأساسية الفريدة. تنبع المشكلة الرئيسية هنا من مرجع التسلسل غير الصحيح، مما يؤدي إلى الخطأ: "relation"

يعمل البرنامج النصي الأول على حل هذه المشكلة عن طريق التأكد من الإشارة إلى التسلسل بشكل صحيح مع التعرف على المخطط. عندما نستخدم ، نحدد كلا من المخطط ("db") والتسلسل ("customers_sq")، مما يضمن أن يبحث PostgreSQL عن التسلسل في السياق الصحيح. إذا تم حذف المخطط أو الإشارة إليه بشكل غير صحيح، فقد لا يتمكن PostgreSQL من العثور على التسلسل، مما يؤدي إلى حدوث الخطأ. يعمل هذا الأمر داخل ملف في TypeScript، التأكد من تمرير إدخال المستخدم بشكل آمن إلى الاستعلام لمنع هجمات حقن SQL.

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

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

// TypeScript - Upsert solution using parameterized query with correct sequence reference
import { Pool } from 'pg';
const pool = new Pool();
const SAVE_CUSTOMER = `
  INSERT INTO "db"."customers" ("id", "name")
  VALUES (NEXTVAL('db.customers_sq'), $1)
  ON CONFLICT ("id") DO UPDATE SET "name" = $1`;
async function saveCustomer(name: string) {
  try {
    await pool.query(SAVE_CUSTOMER, [name]);
    console.log('Customer saved successfully');
  } catch (error) {
    console.error('Error saving customer:', error.message);
  }
}

// TypeScript - Dynamic sequence referencing with schema awareness
import { Pool } from 'pg';
const pool = new Pool();
async function saveCustomer(name: string) {
  try {
    const checkSequence = `SELECT EXISTS (
      SELECT 1 FROM pg_sequences WHERE schemaname = 'db' AND sequencename = 'customers_sq');`;
    const sequenceExists = await pool.query(checkSequence);
    if (!sequenceExists.rows[0].exists) {
      throw new Error('Sequence not found');
    }
    const SAVE_CUSTOMER = `
      INSERT INTO "db"."customers" ("id", "name")
      VALUES (NEXTVAL('db.customers_sq'), $1)
      ON CONFLICT ("id") DO UPDATE SET "name" = $1`;
    await pool.query(SAVE_CUSTOMER, [name]);
    console.log('Customer saved successfully');
  } catch (error) {
    console.error('Error saving customer:', error.message);
  }
}

// Jest - Unit test for saveCustomer function
import { saveCustomer } from './saveCustomer';
import { pool } from 'pg';
jest.mock('pg');
describe('saveCustomer', () => {
  it('should insert new customer if no conflict', async () => {
    pool.query.mockResolvedValueOnce({});
    await saveCustomer('John Doe');
    expect(pool.query).toHaveBeenCalledWith(expect.any(String), ['John Doe']);
  });
  it('should throw error if sequence does not exist', async () => {
    pool.query.mockRejectedValueOnce(new Error('Sequence not found'));
    await expect(saveCustomer('John Doe')).rejects.toThrow('Sequence not found');
  });
});

العوامل الرئيسية وراء أخطاء تسلسل PostgreSQL

أحد الجوانب التي لم تتم تغطيتها مسبقًا هو كيفية تعامل PostgreSQL عندما يتعلق الأمر بكائنات قاعدة البيانات مثل التسلسلات. يتعامل PostgreSQL افتراضيًا مع المعرفات غير المقتبسة كأحرف صغيرة. هذا يعني أنه إذا تم إنشاء اسم تسلسل بأحرف كبيرة ولكن تمت الإشارة إليه بدون علامات اقتباس، فسوف يبحث PostgreSQL تلقائيًا عن الإصدار الصغير. على سبيل المثال، إذا تم إنشاء التسلسل كـ "Customers_SQ" ولكن تمت الإشارة إليه كـ قد يؤدي ذلك إلى الخطأ "العلاقة غير موجودة". استخدام علامات الاقتباس المزدوجة حول اسم التسلسل، مثل ، يضمن أن PostgreSQL يستخدم الحالة الدقيقة كما هو محدد.

جانب آخر مهم هو رؤية المخطط في PostgreSQL. افتراضيًا، يبحث PostgreSQL عن التسلسلات في المخطط الذي يظهر أولاً في مسار البحث ما لم يتم تعريف المخطط بشكل صريح. إذا كان التسلسل موجودًا في مخطط مختلف، فيمكنك الرجوع إليه دون تحديد المخطط (على سبيل المثال، ) يمكن أن يؤدي إلى خطأ لم يتم العثور على تسلسل. يحتاج المطورون إما إلى ضبط مسار البحث أو الإشارة إلى المخطط بشكل صريح لتجنب هذه المشكلة، خاصة في هياكل قواعد البيانات المعقدة ذات المخططات المتعددة.

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

1. ماذا يعني الخطأ "العلاقة غير موجودة" في PostgreSQL؟
2. يعني هذا الخطأ عادةً أن PostgreSQL لا يمكنه العثور على التسلسل أو الجدول الذي تشير إليه، وغالبًا ما يكون ذلك بسبب تسمية التسلسل غير الصحيحة، أو رؤية المخطط، أو حساسية حالة الأحرف.
3. كيف يمكنني إصلاح مشكلات حساسية الحالة في مراجع تسلسل PostgreSQL؟
4. استخدم علامات الاقتباس المزدوجة حول اسم التسلسل مثل للتأكد من أن PostgreSQL يستخدم الحالة الصحيحة كما هو محدد أثناء الإنشاء.
5. ما هو دور المخططات في أخطاء التسلسل؟
6. إذا لم يكن التسلسل موجودًا في المخطط الافتراضي، فيجب عليك الإشارة بوضوح إلى المخطط في الأمر الخاص بك، مثل .
7. كيف يمكنني التحقق من وجود تسلسل في PostgreSQL؟
8. يمكنك الاستعلام عن الجدول للتحقق من وجود تسلسل. مثال:
9. ماذا علي أن أفعل إذا كنت أفتقر إلى أذونات الوصول إلى التسلسل؟
10. تأكد من أن دور المستخدم يتمتع بالامتيازات المناسبة. يمكنك منح حق الوصول باستخدام الأمر .

لحل الخطأ، "العلاقة 'customers_sq' غير موجودة"، تأكد من الإشارة إلى المخطط الصحيح، وأن اسم التسلسل يطابق قواعد حساسية حالة الأحرف في PostgreSQL. تحقق جيدًا من أذونات التسلسل لتجنب مشكلات الوصول أثناء عمليات الصعود.

استخدم دائما بعناية وتحقق من وجود التسلسل في قاعدة بيانات PostgreSQL الخاصة بك عن طريق الاستعلام عن الكتالوج. يضمن اتباع خطوات تصحيح الأخطاء هذه تشغيل عمليات قاعدة البيانات الخاصة بك بسلاسة وكفاءة دون أخطاء متعلقة بالتسلسل.