Upgrade Oracle APEX 24.1 to 26.2

This guide upgrades a self-managed Oracle APEX instance (your own server, a VM, a container, or a co-managed cloud database such as Base Database Service) from APEX 24.1 to APEX 26.2, the current release (GA 6 October 2026). The same steps apply to any release from 18.1 onward, including 23.x, 24.2 and 26.1. On Autonomous AI Database and the APEX Service, Oracle upgrades APEX for you, so this guide does not apply there.

An APEX upgrade runs the same installer as a fresh install. The installer finds your current APEX schema, copies the instance settings, workspaces and applications into a new schema (APEX_260200), and switches over. The old schema stays as it was, which is what makes a rollback possible.

1. Check the prerequisites

• Database: Oracle Database 19c with Release Update 19.18 (January 2023) or newer, or Oracle AI Database 26ai at version 23.26.0 or newer. All editions work, including SE2 and 26ai Free.
• ORDS 26.3.0 or later. Older ORDS releases are not supported with APEX 26.2.
• SQLcl 26.3.0 or later. Oracle's guide uses SQLcl to run the installation scripts.
• Memory: SGA of at least 1200 MB and PGA of at least 300 MB.
• Disk: about 762 MB for the English-only kit (apex_26.2_en.zip) or 1.25 GB for the full kit (apex_26.2.zip), 320 MB free in the APEX tablespace, and 133 MB free in SYSTEM.
• Oracle XML DB must be installed for a full development environment. The installer checks for it and stops if it is missing.
• WORKAREA_SIZE_POLICY must be AUTO in the session that runs the installer. Step 4 sets it. If APEX is installed in a CDB, set it system-wide instead with ALTER SYSTEM SET WORKAREA_SIZE_POLICY=AUTO SCOPE=BOTH;.
• Upgrade path: direct upgrades to 26.2 are supported from APEX 18.1 or later.

Confirm what you are running now. Connect as SYS to the PDB that holds APEX:

-- Current APEX version, status and schema (run in the PDB)
SELECT comp_id, version, status, schema
  FROM dba_registry
 WHERE comp_id = 'APEX';

SELECT version_no FROM apex_release;

-- From CDB$ROOT: is APEX installed in each PDB, or once in the root?
-- A row with CON_ID = 1 means APEX is installed in CDB$ROOT.
SELECT con_id, version, status, schema
  FROM cdb_registry
 WHERE comp_id = 'APEX'
 ORDER BY con_id;

2. Back up and rehearse

Take a full database backup with RMAN, or clone the PDB, and run the whole upgrade on the copy first. As an extra safety net, export every application and workspace with SQLcl:

# Connect as SYSTEM (or another DBA account), not SYS AS SYSDBA
sql system@//localhost:1521/FREEPDB1

-- Inside SQLcl: every application (f<id>.sql), then every workspace (w<id>.sql)
apex export -instance -dir apex_backup
apex export -expworkspace -dir apex_backup

Also copy the images folder that ORDS serves today and name it after its release. The upgrade replaces the images, and you need the old copy if you roll back. The path is an example, so use your own:

# Save the 24.1 images for rollback (example path)
cp -r /opt/oracle/apex/images /opt/oracle/apex/images_24_1

Keep the 24.1 install kit too (apex_24.1.zip or its unzipped apex folder). A rollback runs apxdwngrd.sql from that kit.

3. Upgrade ORDS and SQLcl first

Download ORDS 26.3.0 or later and SQLcl 26.3.0 or later from oracle.com. For ORDS, follow the ORDS Installation and Configuration Guide: ords install upgrades the ORDS schema in your existing database pools. Make sure ORDS runs the PL/SQL gateway in proxied mode:

ords config get plsql.gateway.mode
# If it is not "proxied":
ords config set plsql.gateway.mode proxied

Next, make sure nobody is using APEX. Oracle's default is to shut down the database instance where you will upgrade (with SHUTDOWN NORMAL or SHUTDOWN IMMEDIATE; on RAC, every instance on every node), take your backup, and start it again before you run the installer. Keep ORDS stopped. Only in high-availability production with no planned outage window does Oracle suggest leaving the database up and blocking access by stopping ORDS (or its application server) instead. In that case, check V$SESSION for long-running sessions as SYS. The split-phase option in step 4 also lets ORDS keep running until phase 3.

4. Run the APEX 26.2 installer

1. Download apex_26.2.zip (all languages) or apex_26.2_en.zip (English only).
2. Unzip it into a short path with no spaces (on Windows, for example C:\TEMP).
3. Change into the apex folder and start SQLcl from there. The scripts call other files by relative path.
4. Connect as SYS AS SYSDBA to the PDB that holds APEX, not to CDB$ROOT.
5. Run apexins.sql for a full development environment, or apxrtins.sql if this instance is runtime-only.

# Linux shown; on Windows unzip to a short folder such as C:\TEMP
curl -LO https://download.oracle.com/otn_software/apex/apex_26.2.zip
unzip apex_26.2.zip
cd apex
sql /nolog

-- Option A: connect straight to the PDB service
CONNECT sys@//localhost:1521/FREEPDB1 AS SYSDBA

-- Option B (on the database server):
-- CONNECT SYS AS SYSDBA
-- ALTER SESSION SET CONTAINER = FREEPDB1;

-- Required: WORKAREA_SIZE_POLICY = AUTO in this same session
SHOW PARAMETER WORKAREA_SIZE_POLICY
ALTER SESSION SET WORKAREA_SIZE_POLICY = AUTO;

-- Full development environment
@apexins.sql SYSAUX SYSAUX TEMP /i/

-- Runtime-only instance: run this instead
-- @apxrtins.sql SYSAUX SYSAUX TEMP /i/

The four arguments are, in order: the tablespace for the APEX schema, the tablespace for the files schema (FLOWS_FILES), the temporary tablespace, and the image prefix. The image prefix is still a required argument. Oracle recommends /i/ to keep future upgrades simple. Oracle also recommends a new tablespace for each new APEX release. SYSAUX is the example its own documentation uses.

Split-phase option (Appendix B, "Maximizing Uptime During an APEX Upgrade"). Pass the same four arguments to each script, and skip the full shutdown from step 3. A runtime-only instance uses apxrtins1.sql, apxrtins2.sql and apxrtins3.sql instead. If you reconnect between phases, run ALTER SESSION SET WORKAREA_SIZE_POLICY = AUTO; again before each script:

1. Run apexins1.sql with ORDS still up. Users and developers are not affected.
2. Run apexins2.sql. Development is disabled, but apps keep running.
3. Block web access by stopping ORDS, then run apexins3.sql. APEX can't be used during this phase.
4. Install the new images (step 5), then start ORDS again.

5. Copy the new images (or use the CDN)

The 26.2 kit includes a new apex/images folder. Copy it to the folder ORDS serves as /i/, replacing the old one. You already saved the 24.1 copy as images_24_1 in step 2. The paths below are examples, so use your own.

# Replace the live images with the 26.2 ones (24.1 copy saved in step 2)
rm -rf /opt/oracle/apex/images
cp -r apex/images /opt/oracle/apex/images

# ORDS standalone: confirm which folder it serves as /i/
ords --config /etc/ords/config config get standalone.static.path

If you don't want to host the images yourself, point APEX at Oracle's static-resources CDN. You only do this once, and later upgrades update the CDN reference for you. Run it as a user with 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. Restart and verify

Start ORDS again, then check the result as SYS in the PDB:

-- Expect 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;

-- Phase 4 runs as a background job: wait for 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;

• If the phase 4 job failed, follow "Restarting Phase 4 of an APEX Upgrade" in the Installation Guide.
• Read the upgrade log in Administration Services → Manage Instance → Install / Upgrade Logs.
• You do not need apxchpwd.sql, because instance administrators carry over. You also don't need to reset the APEX_PUBLIC_USER password unless ORDS connects as that user.
• If you upgrade ORDS again later, run BEGIN sys.validate_apex; END; as SYS after each ORDS upgrade.
• If outbound web service calls now fail with ORA-24247, grant network access to APEX_260200 as described in "Enabling Network Services in Oracle Database".
• Smoke-test your key apps: sign-in and authentication schemes, REST Data Sources and web credentials, plug-ins, file uploads, email, and automations.

7. What changes for your applications

Oracle states that applications keep working without modification after an instance upgrade. These are the items from the 26.2 release notes most likely to affect apps that were built on 24.1:

• Universal Theme: APEX 26.2 supports Universal Theme 26.2 and 26.1. Apps on an older theme version keep running, but Oracle strongly recommends that you refresh the theme after every upgrade.
• Desupported in 26.2: SQL Workshop Query Builder (saved queries become SQL Commands saved queries), defining REST APIs through SQL Workshop → RESTful Services (use SQL Developer Web instead), and the Export Repository.
• Export wizard: the Supporting Objects option is gone. If an app has supporting objects, they are always included in the export.
• OAuth for REST calls: 26.2 enforces token reuse and scope matching. Custom OAuth code that handles REST calls in a non-standard way may fail.
• OCI Generative AI: retired models are migrated to cohere.command-a-03-2025 on upgrade.
• Coming from 24.1, also read the Changed Behavior sections of the 24.2 and 26.1 release notes.

8. New in 26.1 and 26.2 worth adopting

• APEXlang (26.1): a readable, file-based application format (.apx files) for Git and AI-assisted editing. 26.2 adds APEXlang deployment files and file-level import through SQLcl and the SQL Developer extension for VS Code.
• AI (26.1): create pages from natural language, and AI Configurations become AI Agents that can use AI Tools. 26.2 adds a Reasoning Effort setting and a Provider API setting for Generative AI services.
• Interactive Reports (26.2): create computed columns from natural language, and use key phrases in the search bar that run without an LLM.
• Workflow (26.2): Draft activities, custom outcomes for Action Tasks, and diagram export.
• Security (26.2): integration with Oracle Deep Data Security (Oracle AI Database 26ai), and network access control per workspace.

Once you are on 26.x, you can export an app as APEXlang files for Git:

-- In SQLcl, connected as SYSTEM or another DBA account
apex export -applicationid 100 -exptype APEXLANG -dir apexlang

9. Remove the old schema (after a few weeks)

Oracle recommends keeping the previous APEX schema for a few weeks, because it is your way back. Reverting points the public synonyms and grants at the old schema again. It also discards every change made in the APEX instance since the upgrade (application edits, new workspaces and users, and other APEX metadata), so treat it as a fallback for a failed or just-completed upgrade, not as a routine undo weeks later. If you ever need to revert to 24.1 ("Reverting to a Previous Release" in the Installation Guide):

1. Put the saved images_24_1 folder back as the folder ORDS serves.
2. Change into the apex folder of the 24.1 kit, start SQLcl, and connect as SYS AS SYSDBA to the PDB.
3. Run @apxdwngrd.sql.
4. Drop the 26.2 schema with DROP USER APEX_260200 CASCADE;.
5. If you used the REST Administration Interface before the upgrade, re-create APEX_INSTANCE_ADMIN_USER as described in "Re-enabling the REST Administration Interface After Downgrading".

When you are sure you won't need to go back, find and drop the old schema:

-- Schemas left from earlier APEX releases
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');

-- Drop only what the query returned, for example after a 24.1 upgrade:
DROP USER APEX_240100 CASCADE;
DROP PACKAGE SYS.WWV_DBMS_SQL_APEX_240100;

Check your understanding