ميزات PostgreSQL 19 الجديدة التي يجب أن يعرفها كل مطور واجهات برمجية

يضيف PostgreSQL 19 ميزة ON CONFLICT DO SELECT لنقاط النهاية من نوع get-or-create، وميزة WAIT FOR LSN لضمان قراءة بياناتك المحدّثة على النسخ المكررة (replicas)، إضافة إلى REPACK (CONCURRENTLY)، وإخراج JSON من COPY، وقائمة تغييرات افتراضية ينبغي مراجعتها قبل الترقية.

INEZA Felin-Michel

INEZA Felin-Michel

20 نوفمبر 2026

ميزات PostgreSQL 19 الجديدة التي يجب أن يعرفها كل مطور واجهات برمجية

Apidog للمؤسسات

النشر على الخوادم المحلية

SSO و RBAC

متوافق مع SOC 2

استكشف Apidog للمؤسسات

الميزات الجديدة في PostgreSQL 19 الأكثر أهمية لمطوّري واجهات برمجة التطبيقات: INSERT ... ON CONFLICT DO SELECT لإنشاء نقاط نهاية "احضر أو أنشئ" بعبارة واحدة، وWAIT FOR LSN لضمان قراءة كتاباتك الخاصة على النسخ المتماثلة، وREPACK (CONCURRENTLY) لتنظيف التضخم عبر الإنترنت، وإخراج JSON من COPY، ودوال سلاسل نصية جديدة في jsonpath، وفحوصات أسرع للمفاتيح الأجنبية عند الإدراج بالجملة.

يغطّي هذا الدليل ما يتغيّر في معالجاتك (handlers)، ونسخك المتماثلة، وخطة الترقية لديك. كل مثال من الأمثلة النحوية مأخوذ من ملاحظات إصدار PostgreSQL 19 ومن صفحات المرجع.

نظرة سريعة على الجديد في PostgreSQL 19

PostgreSQL 19 هو الإصدار الرئيسي السنوي لقاعدة البيانات مفتوحة المصدر، وقد أعلنت عنه مجموعة PostgreSQL للتطوير العالمي في 19 نوفمبر 2026. يضيف إدراجات من نوع "احضر أو أنشئ"، وانتظار النسخ المتماثلة لضمان قراءة كتاباتك الخاصة، وإعادة حزم الجداول عبر الإنترنت، وتوجيهات لخطط التنفيذ (plan advice) والنسخ المنطقي للتسلسلات (sequences)، كما يغيّر عدة قيم افتراضية يجب التحقق منها قبل الترقية.

الميزة ما تحل محله أين ستشعر بأثرها
ON CONFLICT DO SELECT حلقات إعادة المحاولة بأسلوب SELECT-then-INSERT نقاط نهاية POST وإنشاء الحسابات ذات السلوك الخالي من التكرار (idempotent)
WAIT FOR LSN التوجيه اللاصق (sticky routing) للقراءات إلى الخادم الأساسي النسخ المتماثلة للقراءة خلف واجهة API
REPACK (CONCURRENTLY) VACUUM FULL وCLUSTER وpg_repack الجداول الساخنة المتضخمة، دون توقف للخدمة
COPY ... (FORMAT json) تحويل الصفوف إلى JSON داخل كود التطبيق نقاط نهاية التصدير والتنزيل بالجملة
دوال السلاسل النصية في jsonpath المعالجة اللاحقة لـ JSONB داخل كود التطبيق تصفية أعمدة JSON وتطبيعها (normalizing)
pg_plan_advice + pg_stash_advice إعادة صياغة الاستعلامات لتوجيه المخطِّط (planner) تراجع أداء خطط التنفيذ في الإنتاج
المنشورات FOR ALL SEQUENCES إعادة ضبط التسلسلات يدويًا بعد التحويل (cutover) الترقيات بالأسلوب الأزرق-الأخضر عبر النسخ المنطقي

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

ON CONFLICT DO SELECT: احضر أو أنشئ بعبارة واحدة

كل واجهة API لديها نقطة نهاية يجب أن تعيد صفًا سواء وُجد من قبل أم لا: تسجيل جهاز، أو إنشاء وسم، أو بدء عملية دفع خالية من التكرار. قبل الإصدار 19 كنت تنفّذ SELECT ثم INSERT (وكنت تخسر حالات التزامن تحت الضغط)، أو تكتب ON CONFLICT DO UPDATE وهمية فقط لتُشغّل RETURNING، مما يكتب نسخة جديدة من الصف دون فائدة.

يضيف PostgreSQL 19 إجراء تعارض رابعًا. تسمّيه صفحة مرجع INSERT "إدراج خالي من التكرار أو احضر أو أنشئ":

INSERT INTO distributors (did, dname) VALUES (11, 'Global Electronics')
    ON CONFLICT (did) DO SELECT
    RETURNING *;

إذا كانت القيمة did = 11 متاحة، يُدرج الصف ويُعاد. أما إذا كانت مستخدمة، فيعود الصف الموجود ولا يُعدَّل أي شيء. ثلاث قواعد من التوثيق:

Flowchart of a POST /users request using INSERT ON CONFLICT (email) DO SELECT RETURNING: no conflict inserts and returns the row (201), a conflict returns the existing row unmodified (200)

غالبًا ما يحتاج مُعالِج طلبك (handler) إلى معرفة أي المسارين نُفِّذ، حتى يجيب بـ 201 Created أو 200 OK. تلاحظ الوثائق أن قيم RETURNING القديمة تكون غير NULL عند حدوث تعارض، فعمود واحد يخبرك بالأمر:

INSERT INTO users (email, name) VALUES ($1, $2)
    ON CONFLICT (email) DO SELECT
    RETURNING *, (old.id IS NULL) AS created;

هل تحتاج إلى قفل الصف الموجود قبل تعديل جداول مرتبطة؟ أضف عبارة قفل: ON CONFLICT (did) DO SELECT FOR UPDATE RETURNING *. يمكنك أيضًا التصفية باستخدام WHERE، مثل DO SELECT WHERE d.dname != EXCLUDED.dname، وعندها تعود فقط الصفوف التي تجتاز التصفية.

الصلاحيات: يحتاج DO SELECT إلى صلاحية SELECT على الجدول، أما الصيغتان FOR UPDATE وFOR SHARE فتحتاجان أيضًا إلى صلاحية UPDATE على عمود واحد على الأقل.

WAIT FOR LSN: قراءة كتاباتك الخاصة على النسخ المتماثلة

الخطأ الكلاسيكي في النسخ المتماثلة: يحفظ المستخدم ملفه الشخصي، ثم تصادف عملية GET التالية نسخة متماثلة غير متزامنة لم تعيد تشغيل التغيير بعد، فتعود بيانات قديمة. معظم الفرق تُثبّت القراءات على الخادم الأساسي بعد الكتابة، مما يجعل النسخة المتماثلة عديمة الفائدة.

يضيف PostgreSQL 19 أمر WAIT FOR. بعد الكتابة، خُذ موضع WAL في الخادم الأساسي:

UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama';
SELECT pg_current_wal_insert_lsn();   -- returns 0/0306EE20

خزّن قيمة LSN هذه في جلسة المستخدم (يقترح Simon Willison ملف تعريف ارتباط موقّع في شرحه). في الطلب التالي، نفّذ هذا الأمر على النسخة المتماثلة قبل القراءة:

WAIT FOR LSN '0/0306EE20' WITH (TIMEOUT '100ms', NO_THROW);
SELECT * FROM movie WHERE genre = 'Drama';
Sequence diagram: API server commits an UPDATE on the primary, reads pg_current_wal_insert_lsn 0/0306EE20, stores it in the session, then on the next request sends WAIT FOR LSN to the read replica, gets success, and SELECTs the fresh row

التفاصيل المهمة في سياق واجهات API:

  1. الأنماط. النمط الافتراضي MODE 'standby_replay' ينتظر حتى يُطبَّق التغيير، وهو ما تحتاجه ميزة قراءة كتاباتك الخاصة. أما standby_write وstandby_flush وprimary_flush فهي موجودة للتحقق من المتانة (durability).
  2. المهل الزمنية. بدون TIMEOUT، أو مع TIMEOUT '0'، ينتظر إلى الأبد. اضبط قيمة دائمًا في مسارات الطلبات.
  3. NO_THROW. بدونه، تُطلق مهلة زمنية خطأً وتُجهض معاملتك. معه، تحصل على حالة success أو timeout أو not in recovery، ويمكنك حينها الرجوع إلى الخادم الأساسي.
  4. الموضع. يجب أن يكون WAIT أمرًا من المستوى الأعلى، لا داخل دالة أو كتلة DO. نفّذه خارج معاملة أو كأول عبارة فيها، قبل أي شيء يأخذ قفلًا، وإلا فسيُرفض.

REPACK (CONCURRENTLY) يحل محل VACUUM FULL للجداول النشطة

الجداول الموجودة خلف نقاط نهاية مزدحمة، مثل sessions أو webhook_deliveries، تتضخم بسرعة. أوامر VACUUM FULL وCLUSTER تعالج ذلك لكنها تقفل الجدول. يضيف PostgreSQL 19 خيارًا عبر الإنترنت:

REPACK (CONCURRENTLY) webhook_deliveries;
REPACK (CONCURRENTLY, ANALYZE) orders USING INDEX orders_created_at_idx;

تقول ملاحظات الإصدار إن REPACK (CONCURRENTLY) يستعيد المساحة ويمكنه إعادة ترتيب الجدول وفق فهرس دون حجب القراءات أو الكتابات. يبقى VACUUM FULL وCLUSTER متاحين لأغراض التوافق. راقب التقدّم في العرض الجديد pg_stat_progress_repack، وابحث عن الإعداد الجديد للخادم max_repack_replication_slots عند ضبط عنقود قاعدة البيانات.

إخراج JSON من COPY ودوال السلاسل النصية الجديدة في jsonpath

غالبًا ما تمرّر نقاط نهاية التصدير الصفوف عبر كود التطبيق فقط لتحويلها إلى JSON. أصبح بإمكان COPY TO الآن تنفيذ ذلك داخل قاعدة البيانات، وفق مرجع COPY:

COPY (SELECT * FROM (VALUES(1),(2)) val(id)) TO STDOUT (FORMAT JSON, FORCE_ARRAY);

يطبع هذا [ ثم {"id":1} ثم ,{"id":2} ثم ]، كلٌّ على سطر منفصل، فيكون الناتج مصفوفة JSON صالحة واحدة. بدون FORCE_ARRAY تحصل على كائن JSON واحد في كل سطر، وهو تنسيق مناسب لـ NDJSON. تتحول قيمة SQL NULL إلى JSON null، ويعمل تنسيق json فقط مع COPY TO.

أما لأعمدة JSONB، فقد أضيفت إلى jsonpath دوال للسلاسل النصية: lower() وupper() وinitcap() وltrim() وrtrim() وbtrim() وreplace() وsplit_part(). تُظهر الوثائق:

jsonb_path_query('"TOM"', '$.lower()')                  -- "tom"
jsonb_path_query('" hello "', '$.btrim()')              -- "hello"
jsonb_path_query('"abc,def,ghi,jkl"', '$.split_part(",", 3)')  -- "ghi"

تصنّفها ملاحظات الإصدار كدوال غير قابلة للتغيير (immutable)، وهي تتيح لك تطبيع حقل JSONB (تقصيته، وتحويله إلى أحرف صغيرة، وتقسيمه) داخل الاستعلام بدلًا من داخل معالِجك.

أيضًا، أصبحت json_array() عند عدم وجود صفوف تعيد [] بدلًا من NULL، وقد يؤدي ذلك إلى كسر عميل يتحقق من قيمة null.

تغييرات أخرى في PostgreSQL 19 يجب أن تعرفها فرق API

تغييرات كاسرة يجب التحقق منها قبل الترقية

يسرد قسم الترحيل في ملاحظات الإصدار تغييرات قد تضرب واجهتك دون أن يفشل استعلام واحد في بيئة الاختبار:

التغيير في PostgreSQL 19 ما يجب التحقق منه
القيمة الافتراضية لـ max_locks_per_transaction من 64 إلى 128، ويجب مضاعفة الإعدادات الحالية القيم المخصصة في ملف الإعداد أو في مجموعة معاملات الخدمة المُدارة
تعطيل JIT افتراضيًا نقاط نهاية التحليلات التي اعتمدت على JIT للاستعلامات الطويلة
ضغط TOAST الافتراضي من pglz إلى lz4 لا شيء ينكسر، لكن ملفات التخزين ومعالج CPU يتغيّر أداؤهما
فرض standard_conforming_strings إلى الوضع on النسخ الاحتياطية القديمة المأخوذة والوضع off لن تُستعاد
مصادقة كلمات المرور MD5 تسجّل تحذيرًا؛ وإزالة RADIUS انقل أدوار التطبيق إلى SCRAM-SHA-256
الدالة json_array() عند عدم وجود صفوف تعيد [] العملاء الذين يتحققون من قيمة null
تمرير READ ONLY إلى postgres_fdw المعاملات للقراءة فقط التي كتبت عبر جدول خارجي
تشغيل log_lock_waits افتراضيًا حجم السجلات وضجيج التنبيهات

تظل الترقية من أي إصدار رئيسي سابق تتطلب pg_upgrade، أو نسخًا احتياطيًا واستعادة عبر pg_dumpall، أو النسخ المنطقي. خطّط للانتقال الآن إذا كنت على PostgreSQL 14: فوفق سياسة الإصدارات، كان إصدارها النهائي في 12 نوفمبر 2026.

دَع وكيل البرمجة يختبر واجهتك من أجل الانحدار بعد الترقية باستخدام Apidog CLI

ترقية Postgres الرئيسية نادرًا ما تكسر صيغة SQL، لكنها تكسر السلوك: دالة json_array() تعيد []، أو حد أقفال، أو خطة تنفيذ أبطأ. اكتشف ذلك بتشغيل سيناريوهات اختبار واجهتك على قاعدة بيانات PostgreSQL 19 في بيئة الاختبار (staging)، مع التحقق من استجابة HTTP والصفوف التي تقف خلفها. دَع وكيل البرمجة يقوم بذلك باستخدام Apidog CLI.

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

ثم أعطِ وكيلك تعليمات واحدة:

In Apidog project <projectId>, add a test case for POST /users that sends the same
email twice and asserts the first call returns 201 and the second returns 200 with the
same id. Then run test scenario <scenarioId> against the pg19-staging environment with
database assertions, and summarize every failure next to the PostgreSQL 19 change
that could explain it.

يقرأ الوكيل مخطط الحمولة (payload schema)، ويتحقق من صحته، وينشئ حالة الاختبار، ثم يشغّل السيناريو باستخدام ملف اتصال قاعدة البيانات لديك لتصيب خطوات قاعدة البيانات العنقود الجديد:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run -t <scenarioId> --project <projectId> -e <envId> \
  --database-connection ./database-connections.json -r cli,junit

تدعم عمليات قواعد البيانات في Apidog خادم PostgreSQL في الخطة المجانية، فيمكنك الاستعلام عن الجدول بعد كل طلب والتأكد من أن نقطة نهاية "احضر أو أنشئ" كتبت صفًا واحدًا بالضبط. تشرح الوثائق استعلامات قواعد البيانات في اختبارات API وتشغيل السيناريوهات باتصالات قواعد البيانات من واجهة الأوامر. ضع الأمر نفسه apidog run ... -r junit في خط أنابيب CI لديك، وسيحصل كل إصدار ثانوي لاحق على الفحص نفسه. وإذا فضّلت أن يستعلم وكيلك عن Postgres مباشرة، فراجع دليل خادم PostgreSQL MCP.

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

متى صدر PostgreSQL 19؟ في 19 نوفمبر 2026. يدعم مشروع PostgreSQL كل إصدار رئيسي لمدة 5 سنوات، لذا سيحصل الإصدار 19 على الإصلاحات حتى 19 نوفمبر 2031.

هل ON CONFLICT DO SELECT هو نفسه upsert؟ لا. يعدّل DO UPDATE الصف الموجود، بينما يعيده DO SELECT دون أي تغيير. استخدمه لعمليات "احضر أو أنشئ" وطلبات POST الخالية من التكرار. يتطلب عبارة RETURNING وهدف تعارض (conflict target).

هل يعمل WAIT FOR LSN على الخادم الأساسي؟ النمط الافتراضي standby_replay يعمل فقط على نسخة احتياطية أثناء الاستعادة (recovery). على الخادم الأساسي ستحصل على خطأ، أو على not in recovery مع NO_THROW. استخدم MODE 'primary_flush' إذا احتجت إلى الانتظار على الخادم الأساسي نفسه.

هل يمكنني الترقية من PostgreSQL 18 إلى 19 في مكانه؟ نعم، باستخدام pg_upgrade. يمكنك أيضًا النسخ والاستعادة أو استخدام النسخ المنطقي، الذي ينسخ التسلسلات الآن عبر FOR ALL SEQUENCES. راجع جدول التغييرات الكاسرة أعلاه أولًا.

هل يحل PostgreSQL 19 محل pg_repack؟ في معظم الحالات، نعم. يستعيد REPACK (CONCURRENTLY) المساحة المتضخمة ويعيد ترتيب الجداول وفق الفهرس دون حجب القراءات أو الكتابات، ويأتي مدمجًا في النواة.

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات