4 Upgrading from a Previous Oracle APEX Release

Upgrading Oracle APEX creates new database objects in a new schema and migrates the application metadata to the new release.

If you have Oracle APEX release 20.x or earlier, following any of the installation scenarios in this guide upgrades your APEX instance to the current release, creates Oracle APEX 21.2 database objects in a new schema, and migrates the application metadata to the new release.

4.1 About Release Numbering Conventions

New releases of Oracle APEX correlate to the calendar year.

In 2018 and starting with release 18.1 and 18.2, Oracle APEX introduced correlating the release number to the calendar year.

In addition, APEX now only offers full releases and no longer provides patch set releases (such as 5.1.1). Eliminating patch set releases reduces downtime when updating existing installations. APEX architecture also enables developers to revert releases if necessary.

Patch set exceptions (PSEs) may still be delivered for major defects. To learn more about PSEs, visit the Oracle APEX 21.2 Known Issues page or the Prior Release Archives for earlier releases.

4.2 Sample Upgrade Scenarios

Common upgrade scenarios include upgrading from prior release and installing an Oracle Database release which include Oracle APEX.

Table 4-1 lists common upgrade scenarios.

Table 4-1 Sample Upgrade Scenarios

Upgrade Scenarios Action

Upgrade from a prior Oracle APEX release

Download the latest files from the Downloads page.

You install Oracle Database which include Oracle APEX.

Download the latest files from the Downloads page.

4.3 Viewing the Oracle APEX Release Number

View your Oracle APEX release number on the Workspace home page or on the About Oracle APEX page.

You can view the Oracle APEX release number on the Workspace home page or on the About Oracle APEX page:
  • Workspace home page:
    • Sign in to Oracle APEX.

      On the Workspace home page, the current release number displays in the bottom right corner.

  • About APEX page:
    • Sign in to Oracle APEX.

    • Click the Help menu in the upper right and select About.

      On the About APEX pag, the release number appears next to Product Build.

4.4 Viewing the Oracle REST Data Services Release Number

View the Oracle REST Data Services release number on the About Oracle APEX page.

Oracle APEX requires access to the Web listener, Oracle REST Data Services (ORDS) 19.x or later.

To view the Oracle REST Data Services release number:

  1. Sign in to Oracle APEX.
  2. Click the Help menu in the upper right and select About.
  3. Under the CGI Environment section, find APEX_LISTENER_VERSION.

4.5 About Installing the Oracle APEX Release Included with the Oracle Database

Learn about the Oracle APEX releases included with Oracle Database releases.

Oracle APEX is included with the following Oracle Database releases:

  • Oracle Database 19c - Oracle Application Express Release 18.1.

  • Oracle Database 18c - Oracle Application Express Release 5.1.

  • Oracle Database 12c Release 2 (12.2)- Oracle Application Express Release 5.0.

  • Oracle Database 12c Release 1 (12.1) - Oracle Application Express Release 4.2.

  • Oracle Database 11g Release 2 (11.2) - Oracle Application Express Release 3.2.

  • Oracle Database 11g Release 1 (11.1) - Oracle Application Express Release 3.0.

The Oracle Database releases less frequently than APEX. Therefore, Oracle recommends updating to the latest APEX release available on Oracle Technology Network. To learn more, see the installation instructions for the appropriate Web Listener in your environment.


If upgrading Oracle APEX from a release that ships with the database, do not alter any APEX files in the Oracle home directory (for example, /u01/app/oracle/product/18.0.0/dbhome_1/apex) .

4.6 About Upgrading Existing Applications

Installing a new release of Oracle APEX, updates existing applications to the latest release, but does not alter application user interface or application components.

Once you upgrade an Oracle APEX instance from a previous release, existing applications will work without modification. However, to keep applications maintainable, up-to-date, and to leverage new functionality, developers should perform the steps outlined in Upgrading Application Express Applications in Oracle APEX App Builder User’s Guide.

4.7 About Testing Requirements

Determining the appropriate amount of regression testing when upgrading Oracle APEX depends upon the complexity, size, and number of applications you are upgrading.

You should include the majority of complex pages, particularly those that incorporate significant JavaScript or extensive PL/SQL computations or processes. Developers should ensure pages which they manually update based on the Upgrade Application or Advisor are also included in regression tests. Not all remaining pages have to be included in regression testing. Oracle recommends you include a good representation of different page types includes reports, charts, and forms. An application should always be included in regression testing if its compatibility mode was modified post-upgrade.

While regression testing of upgraded applications is imperative to minimize risk of disrupting the end users, it is important that testing is not drawn out for an extended period. As a general rule:

  • Step 1: Upgrade your development environment first. Allow developers to review the applications and make initial updates as needed.

  • Step 2: Upgrade your QA/Test environment.

  • Step 3: Upgrade applications from development are built into this environment.

  • Step 4: Upgrade your production environment.

  • Step 5: Build upgraded applications into this environment.

4.8 About Cleaning Up Your Environment

Following the successful upgrade of all of the environments to the latest release of Oracle APEX, you should clean-up the environments.

Once you start developing with the newer release, the Oracle APEX schema associated with the prior release can be deleted. If you installed the prior release into a separate tablespace, you can simply drop the specific tablespace. Oracle recommends leaving the older Oracle APEX schema(s) for a few weeks and then remove them from the development, test, and production environments. This cleanup process releases disk space and ensures that no one accesses an outdated schema using tools such as SQL Developer or SQL*Plus.

4.9 About Reverting to a Previous Release

You can revert to a previous release of Oracle APEX.

Because Oracle APEX creates a new schema for each major release, reverting back to a prior release is a relatively simple process. If you revert to a prior release, any modifications made in the current Oracle APEX instance are lost. The main task is to switch the public synonyms and grants to point at the previous schema instead of the new schema.