ترقية Oracle APEX 24.1 إلى 26.2

يشرح هذا الدليل ترقية نسخة Oracle APEX مُدارة ذاتيًا (خادمك الخاص أو جهاز افتراضي أو حاوية أو قاعدة سحابية مُدارة جزئيًا مثل Base Database Service) من APEX 24.1 إلى APEX 26.2، وهو الإصدار الحالي (أُتيح رسميًا في 6 أكتوبر 2026). الخطوات نفسها تصلح لأي إصدار من 18.1 فما بعده، ومنها 23.x و24.2 و26.1. أما على Autonomous AI Database وخدمة APEX Service فإن Oracle هي التي تُرقّي APEX، لذا لا ينطبق عليها هذا الدليل.

ترقية APEX تستخدم المثبّت نفسه الذي يُستخدم في التثبيت الجديد. يعثر المثبّت على مخطط APEX الحالي، وينسخ إعدادات النسخة ومساحات العمل والتطبيقات إلى مخطط جديد (APEX_260200) ثم يتحوّل إليه. يبقى المخطط القديم كما هو، وهذا ما يجعل التراجع ممكنًا.

1. تحقّق من المتطلبات

• قاعدة البيانات: Oracle Database 19c مع Release Update 19.18 (يناير 2023) أو أحدث، أو Oracle AI Database 26ai بالإصدار 23.26.0 أو أحدث. تعمل كل الإصدارات (Editions)، ومنها SE2 و26ai Free.
• ORDS 26.3.0 أو أحدث. إصدارات ORDS الأقدم غير مدعومة مع APEX 26.2.
• SQLcl 26.3.0 أو أحدث. يستخدم دليل Oracle أداة SQLcl لتشغيل سكربتات التثبيت.
• الذاكرة: SGA لا تقل عن 1200 ميغابايت، وPGA لا تقل عن 300 ميغابايت.
• القرص: نحو 762 ميغابايت لحزمة الإنجليزية فقط (apex_26.2_en.zip) أو 1.25 غيغابايت للحزمة الكاملة (apex_26.2.zip)، و320 ميغابايت مساحة حرة في tablespace الخاص بـ APEX، و133 ميغابايت حرة في SYSTEM.
• Oracle XML DB يجب أن يكون مثبّتًا لبيئة التطوير الكاملة. يتحقق المثبّت من وجوده ويتوقف إن لم يجده.
• يجب أن تكون قيمة WORKAREA_SIZE_POLICY هي AUTO في الجلسة التي تشغّل المثبّت، وتضبطها الخطوة 4. وإذا كان APEX مثبّتًا في CDB فاضبطها على مستوى النظام بدلًا من ذلك عبر ALTER SYSTEM SET WORKAREA_SIZE_POLICY=AUTO SCOPE=BOTH;.
• مسار الترقية: الترقية المباشرة إلى 26.2 مدعومة من APEX 18.1 أو أحدث.

تأكّد مما تشغّله حاليًا. اتصل بالمستخدم SYS في قاعدة PDB التي تحتوي APEX:

-- إصدار APEX الحالي وحالته ومخططه (شغّله داخل PDB)
SELECT comp_id, version, status, schema
  FROM dba_registry
 WHERE comp_id = 'APEX';

SELECT version_no FROM apex_release;

-- من CDB$ROOT: هل APEX مثبّت في كل PDB أم مرة واحدة في الجذر؟
-- وجود صف بقيمة CON_ID = 1 يعني أن APEX مثبّت في CDB$ROOT.
SELECT con_id, version, status, schema
  FROM cdb_registry
 WHERE comp_id = 'APEX'
 ORDER BY con_id;

2. خذ نسخة احتياطية وتدرّب

خذ نسخة احتياطية كاملة لقاعدة البيانات عبر RMAN أو استنسخ قاعدة PDB، ونفّذ الترقية كاملةً على النسخة أولًا. وكشبكة أمان إضافية، صدّر كل التطبيقات ومساحات العمل باستخدام SQLcl:

# اتصل بـ SYSTEM (أو حساب DBA آخر)، وليس SYS AS SYSDBA
sql system@//localhost:1521/FREEPDB1

-- داخل SQLcl: كل التطبيقات (f<id>.sql) ثم كل مساحات العمل (w<id>.sql)
apex export -instance -dir apex_backup
apex export -expworkspace -dir apex_backup

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

# احفظ صور 24.1 من أجل التراجع (مسار للمثال)
cp -r /opt/oracle/apex/images /opt/oracle/apex/images_24_1

واحتفظ أيضًا بـ حزمة تثبيت 24.1 (apex_24.1.zip أو مجلد apex المفكوك منها)، فالتراجع يشغّل apxdwngrd.sql من هذه الحزمة.

3. رقِّ ORDS وSQLcl أولًا

نزّل ORDS 26.3.0 أو أحدث وSQLcl 26.3.0 أو أحدث من oracle.com. بالنسبة إلى ORDS اتبع دليل ORDS Installation and Configuration Guide؛ فالأمر ords install يُرقّي مخطط ORDS في مجمّعات قواعد البيانات (database pools) الموجودة. وتأكّد أن ORDS يشغّل بوابة PL/SQL بوضع proxied:

ords config get plsql.gateway.mode
# إذا لم تكن القيمة "proxied":
ords config set plsql.gateway.mode proxied

بعد ذلك تأكّد أن لا أحد يستخدم APEX. الإجراء الافتراضي لدى Oracle هو إيقاف مثيل قاعدة البيانات الذي ستُرقّي فيه (بالأمر SHUTDOWN NORMAL أو SHUTDOWN IMMEDIATE؛ وفي RAC كل المثيلات على كل العُقد)، ثم أخذ النسخة الاحتياطية، ثم تشغيله من جديد قبل تشغيل المثبّت. أبقِ ORDS متوقفًا. ولا تقترح Oracle ترك قاعدة البيانات تعمل ومنع الوصول بإيقاف ORDS (أو خادم التطبيقات الذي يعمل فيه) إلا في بيئات الإنتاج عالية الإتاحة التي لا تتوفر فيها فترة توقف مخطط لها. وفي هذه الحالة افحص V$SESSION بالمستخدم SYS بحثًا عن جلسات طويلة. كما يتيح لك خيار المراحل المنفصلة في الخطوة 4 إبقاء ORDS يعمل حتى المرحلة 3.

4. شغّل مثبّت APEX 26.2

1. نزّل apex_26.2.zip (كل اللغات) أو apex_26.2_en.zip (الإنجليزية فقط).
2. فُكّ الضغط في مسار قصير بلا مسافات (على Windows مثلًا C:\TEMP).
3. ادخل إلى مجلد apex وشغّل SQLcl منه؛ فالسكربتات تستدعي ملفات أخرى بمسارات نسبية.
4. اتصل بالمستخدم SYS AS SYSDBA بقاعدة PDB التي تحتوي APEX، وليس بـ CDB$ROOT.
5. شغّل apexins.sql لبيئة التطوير الكاملة، أو apxrtins.sql إن كانت النسخة لوقت التشغيل فقط (runtime).

# المثال لنظام Linux؛ على Windows فُكّ الضغط في مجلد قصير مثل C:\TEMP
curl -LO https://download.oracle.com/otn_software/apex/apex_26.2.zip
unzip apex_26.2.zip
cd apex
sql /nolog

-- الخيار A: اتصل مباشرةً بخدمة PDB
CONNECT sys@//localhost:1521/FREEPDB1 AS SYSDBA

-- الخيار B (على خادم قاعدة البيانات):
-- CONNECT SYS AS SYSDBA
-- ALTER SESSION SET CONTAINER = FREEPDB1;

-- إلزامي: WORKAREA_SIZE_POLICY = AUTO في الجلسة نفسها
SHOW PARAMETER WORKAREA_SIZE_POLICY
ALTER SESSION SET WORKAREA_SIZE_POLICY = AUTO;

-- بيئة التطوير الكاملة
@apexins.sql SYSAUX SYSAUX TEMP /i/

-- نسخة لوقت التشغيل فقط: شغّل هذا بدلًا منه
-- @apxrtins.sql SYSAUX SYSAUX TEMP /i/

الوسائط الأربعة بالترتيب هي: tablespace مخطط APEX، وtablespace مخطط الملفات (FLOWS_FILES)، وtablespace المؤقت، وبادئة الصور (image prefix). ما زالت بادئة الصور وسيطًا إلزاميًا، وتوصي Oracle بالقيمة /i/ لتبقى الترقيات القادمة بسيطة. كما توصي Oracle بإنشاء tablespace جديد لكل إصدار APEX جديد، وSYSAUX هو المثال الذي تستخدمه وثائقها.

خيار المراحل المنفصلة (الملحق B "Maximizing Uptime During an APEX Upgrade"). مرّر الوسائط الأربعة نفسها إلى كل سكربت، وتجاوز الإيقاف الكامل المذكور في الخطوة 3. أما نسخة وقت التشغيل فقط فتستخدم بدلًا منها apxrtins1.sql وapxrtins2.sql وapxrtins3.sql. وإذا أعدت الاتصال بين المراحل، فنفّذ ALTER SESSION SET WORKAREA_SIZE_POLICY = AUTO; من جديد قبل كل سكربت:

1. شغّل apexins1.sql وORDS ما زال يعمل. لا يتأثر المستخدمون ولا المطوّرون.
2. شغّل apexins2.sql. يتعطّل التطوير، لكن التطبيقات تستمر في العمل.
3. امنع الوصول عبر الويب بإيقاف ORDS، ثم شغّل apexins3.sql. لا يمكن استخدام APEX خلال هذه المرحلة.
4. ثبّت الصور الجديدة (الخطوة 5)، ثم شغّل ORDS من جديد.

5. انسخ الصور الجديدة (أو استخدم CDN)

تتضمن حزمة 26.2 مجلد apex/images جديدًا. انسخه إلى المجلد الذي يقدّمه ORDS على المسار /i/ ليحلّ محلّ المجلد القديم. لقد حفظت نسخة 24.1 باسم images_24_1 في الخطوة 2. المسارات أدناه أمثلة، فاستخدم مساراتك.

# استبدل الصور الحالية بصور 26.2 (نسخة 24.1 محفوظة في الخطوة 2)
rm -rf /opt/oracle/apex/images
cp -r apex/images /opt/oracle/apex/images

# ORDS standalone: تأكّد من المجلد الذي يقدّمه على /i/
ords --config /etc/ords/config config get standalone.static.path

إن لم تُرِد استضافة الصور بنفسك، فوجّه APEX إلى شبكة CDN الخاصة بموارد Oracle الثابتة. تفعل ذلك مرة واحدة فقط، وتُحدِّث الترقيات اللاحقة مرجع CDN تلقائيًا. شغّل الكود بمستخدم لديه الدور APEX_ADMINISTRATOR_ROLE:

BEGIN
  FOR c1 IN (SELECT version_no FROM apex_release) LOOP
    apex_instance_admin.set_parameter(
      p_parameter => 'IMAGE_PREFIX',
      p_value     => 'https://static.oracle.com/cdn/apex/' || c1.version_no || '/');
  END LOOP;
  COMMIT;
END;
/

6. أعِد التشغيل وتحقّق

شغّل ORDS من جديد، ثم افحص النتيجة بالمستخدم SYS داخل PDB:

-- المتوقع: VERSION 26.2.x وSTATUS VALID وSCHEMA APEX_260200
SELECT comp_id, version, status, schema
  FROM dba_registry
 WHERE comp_id = 'APEX';

SELECT version_no FROM apex_release;

-- المرحلة 4 تعمل كمهمة في الخلفية: انتظر حتى تصبح STATUS = SUCCEEDED
SELECT log_date, status, additional_info
  FROM dba_scheduler_job_log
 WHERE owner    = 'APEX_260200'
   AND job_name = 'ORACLE_APEX_COPY_POST_METADATA'
 ORDER BY log_date DESC
 FETCH FIRST 1 ROWS ONLY;

• إذا فشلت مهمة المرحلة 4، فاتبع قسم "Restarting Phase 4 of an APEX Upgrade" في دليل التثبيت.
• اقرأ سجل الترقية من Administration Services ← Manage Instance ← Install / Upgrade Logs.
• لا تحتاج إلى apxchpwd.sql، لأن مديري النسخة ينتقلون كما هم. ولا تحتاج كذلك إلى إعادة تعيين كلمة مرور APEX_PUBLIC_USER إلا إذا كان ORDS يتصل بهذا المستخدم.
• إذا رقّيت ORDS مرة أخرى لاحقًا، فشغّل BEGIN sys.validate_apex; END; بالمستخدم SYS بعد كل ترقية لـ ORDS.
• إذا أصبحت استدعاءات خدمات الويب الخارجية تفشل بالخطأ ORA-24247، فامنح المخطط APEX_260200 صلاحية الوصول إلى الشبكة كما في قسم "Enabling Network Services in Oracle Database".
• اختبر تطبيقاتك الأساسية سريعًا: تسجيل الدخول ومخططات المصادقة، وREST Data Sources وبيانات اعتماد الويب، والإضافات (plug-ins)، ورفع الملفات، والبريد، والأتمتة (automations).

7. ما الذي يتغيّر في تطبيقاتك

تقول Oracle إن التطبيقات تستمر في العمل دون تعديل بعد ترقية النسخة. وهذه أكثر البنود في ملاحظات إصدار 26.2 احتمالًا للتأثير في تطبيقات بُنيت على 24.1:

• Universal Theme: يدعم APEX 26.2 الإصدارين 26.2 و26.1 من Universal Theme. التطبيقات التي تستخدم إصدارًا أقدم تظل تعمل، لكن Oracle توصي بشدة بتحديث الثيم (Refresh) بعد كل ترقية.
• غير مدعوم في 26.2: أداة Query Builder في SQL Workshop (تتحوّل الاستعلامات المحفوظة إلى استعلامات محفوظة في SQL Commands)، وتعريف واجهات REST عبر SQL Workshop ← RESTful Services (استخدم SQL Developer Web بدلًا منها)، وExport Repository.
• معالج التصدير: حُذف خيار Supporting Objects. إذا كان في التطبيق كائنات داعمة (supporting objects) فإنها تُضمَّن في التصدير دائمًا.
• OAuth لاستدعاءات REST: يفرض 26.2 إعادة استخدام الرموز (tokens) ومطابقة النطاقات (scopes). قد يفشل كود OAuth مخصّص يعالج استدعاءات REST بطريقة غير قياسية.
• OCI Generative AI: تُرحَّل النماذج المتقاعدة إلى cohere.command-a-03-2025 عند الترقية.
• بما أنك قادم من 24.1، فاقرأ أيضًا أقسام Changed Behavior في ملاحظات إصداري 24.2 و26.1.

8. جديد 26.1 و26.2 الذي يستحق التبنّي

• APEXlang (26.1): صيغة تطبيقات مقروءة قائمة على الملفات (ملفات .apx) تناسب Git والتحرير بمساعدة الذكاء الاصطناعي. ويضيف 26.2 ملفات نشر APEXlang، والاستيراد على مستوى الملف عبر SQLcl وامتداد SQL Developer لـ VS Code.
• الذكاء الاصطناعي (26.1): إنشاء الصفحات من لغة طبيعية، وتحوّلت AI Configurations إلى AI Agents التي يمكنها استخدام AI Tools. ويضيف 26.2 إعداد Reasoning Effort وإعداد Provider API لخدمات الذكاء الاصطناعي التوليدي.
• Interactive Reports (26.2): إنشاء أعمدة محسوبة من لغة طبيعية، وعبارات مفتاحية في شريط البحث تعمل دون نموذج لغوي (LLM).
• سير العمل (26.2): أنشطة المسودة (Draft)، ونتائج مخصّصة لـ Action Tasks، وتصدير المخطط.
• الأمان (26.2): التكامل مع Oracle Deep Data Security (في Oracle AI Database 26ai)، والتحكم في الوصول إلى الشبكة على مستوى مساحة العمل.

بعد وصولك إلى 26.x يمكنك تصدير تطبيق بصيغة APEXlang من أجل Git:

-- داخل SQLcl، متصلًا بـ SYSTEM أو بحساب DBA آخر
apex export -applicationid 100 -exptype APEXLANG -dir apexlang

9. احذف المخطط القديم (بعد بضعة أسابيع)

توصي Oracle بالاحتفاظ بمخطط APEX السابق بضعة أسابيع، فهو طريقك للعودة؛ إذ يعيد التراجع توجيه المرادفات العامة (public synonyms) والصلاحيات إلى المخطط القديم. كما يُلغي التراجع كل تغيير أُجري في نسخة APEX منذ الترقية (تعديلات التطبيقات، ومساحات العمل والمستخدمين الجدد، وغيرها من بيانات APEX الوصفية)، لذا تعامل معه كخطة بديلة لترقية فاشلة أو انتهت للتو، وليس كتراجع روتيني بعد أسابيع. وإذا احتجت يومًا إلى التراجع إلى 24.1 (قسم "Reverting to a Previous Release" في دليل التثبيت):

1. أعِد مجلد images_24_1 المحفوظ ليكون المجلد الذي يقدّمه ORDS.
2. ادخل إلى مجلد apex في حزمة 24.1، وشغّل SQLcl، واتصل بقاعدة PDB بالمستخدم SYS AS SYSDBA.
3. شغّل @apxdwngrd.sql.
4. احذف مخطط 26.2 بالأمر DROP USER APEX_260200 CASCADE;.
5. إذا كنت تستخدم REST Administration Interface قبل الترقية، فأعِد إنشاء APEX_INSTANCE_ADMIN_USER كما في قسم "Re-enabling the REST Administration Interface After Downgrading".

وحين تتأكد أنك لن تحتاج إلى العودة، ابحث عن المخطط القديم واحذفه:

-- المخططات المتبقية من إصدارات APEX السابقة
SELECT username
  FROM dba_users
 WHERE REGEXP_LIKE(username, '^(APEX|FLOWS)_[0-9]{6}$')
   AND username NOT IN (SELECT schema FROM dba_registry WHERE comp_id = 'APEX');

-- احذف فقط ما أعاده الاستعلام، مثلًا بعد الترقية من 24.1:
DROP USER APEX_240100 CASCADE;
DROP PACKAGE SYS.WWV_DBMS_SQL_APEX_240100;

اختبر فهمك