Upgrading APEXlang Source with a New APEX Release

Overview

This section explains why Oracle recommends importing and re-exporting APEXlang applications in your development environment after upgrading to a new major APEX release. With each APEX release, the APEXlang source code and file structure may change. An export of an unchanged application from the upgraded release can differ from an export from the previous release. For example, an APEX upgrade can result in the following source code changes when exporting an application in APEXlang:

• The APEXlang version in the hidden file .apex/apexlang.json always changes.
• Components that were previously stored together may be separated into individual files.
• Default, redundant, or obsolete content may be omitted to make the source more concise.
• Files or directories may be renamed, added, or removed as the file and directory structures evolve.

Many teams store their APEXlang files in a Git repository and treat them as the definitive copy of their applications. If you do this, import and re-export each application after upgrading APEX as described below. Do this even for applications you have not modified. If you do not follow these instructions, your files stay in an older APEXlang structure, and you cannot take advantage of newer features that depend on the most recent structure. By doing the re-export right after an APEX upgrade, the structural changes are tracked in a single commit, separate from any other changes.

Note: If you primarily develop applications in the App Builder and export in APEXlang format as a backup, you may not need to follow the instructions below. The next application export will use the latest APEXlang structure.

Upgrading ORDS, SQLcl, and Oracle SQL Developer Extension for VS Code to Support Importing APEXlang Applications

Importing APEXlang applications requires the most recent versions of ORDS, SQLcl, or Oracle SQL Developer for VS Code, depending on the method used to import the application. The following table describes the APEXlang import method and the specific product that needs to be upgraded.

Tip: Oracle recommends always keeping Oracle REST Data Services (ORDS), SQLcl, and the Oracle SQL Developer for VS Code extension updated.

APEXlang Import Method	Upgrade
App Builder	ORDS
Command line	SQLcl
VS Code	Oracle SQL Developer for VS Code

Upgrading APEXlang Source Code

If you permanently store APEXlang source files, you need to update the source for each application when upgrading APEX despite not having made any modifications to an application. The most common use case is when using a Git repository to store APEXlang applications.

To upgrade each application:

1. Create a new branch to handle the upgrade.

   • This helps ensure that all modifications made due to the APEX upgrade are contained within one Merge Request (MR) / Pull Request (PR), which simplifies the history in the repository.
2. Using SQLcl, import the application and export it.
   • Importing the application ensures that differences are isolated to the APEX upgrade only.
     • If you import using the same application ID, the import overwrites any changes on the APEX server. Oracle recommends backing up the current application.
   • Exporting using the -force deletes in the application source code directory. This is required to ensure any directory or file structural changes are upgraded correctly and no unnecessary files remain.
     • Since the contents of the application’s directory will be deleted, ensure that any non-committed files are backed up first. If your application folder contains content that is not part of an APEX export (for example, README.md), that content can be restored with git.
3. Commit all the changes, and then merge back into the main branch. Following the usual git workflow, all other branches need to be updated from main.

Example: Upgrading an APEXlang Application from APEX 26.1 to APEX 26.2

The example shows how to upgrade app 100 (alias demo) from APEX 26.1 to APEX 26.2.

-- Change directory to your git repository root directory

$ cd demo-project

-- Create a branch to work in (e.g. upgrade-apexlang-src branch)
demo-project $ git switch -c upgrade-apexlang-src
demo-project $ git push -u origin upgrade-apexlang-src

-- Connect to dev environment using named connection
demo-project $ sql -name dev

-- Import APEXlang app from app-alias ./demo directory to APEX
SQL> apex import -input demo

Importing application ID: 100 into workspace: DEMO_WORKSPACE
Import successful.
...

-- Export app to obtain new APEXlang changes
SQL> apex export -exptype apexlang -applicationid 100 -force

Exporting Workspace DEMO_WORKSPACE - application 100:demo

Caution: The -force option to apex export is important to ensure files get removed that are no longer part of the new APEXlang export. However, be aware that it removes the app alias directory before writing out a new one with the fresh contents. Therefore, your git repo root directory should be at least one directory level above this app alias directory.{: .infoboxcaution}

The following shows the changed files and directory structures after the export:

demo-project $ git status --untracked-files=all

Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   demo/.apex/apexlang.json
	modified:   demo/application.apx
	modified:   demo/deployments/default.json
	modified:   demo/pages/p00001-home.apx
	modified:   demo/pages/p09999-login.apx
	deleted:    demo/shared-components/breadcrumbs.apx
	modified:   demo/shared-components/component-settings.apx
	deleted:    demo/shared-components/lists.apx
	deleted:    demo/shared-components/lovs.apx

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	demo/shared-components/breadcrumbs/breadcrumb.apx
	demo/shared-components/lists/navigation-bar.apx
	demo/shared-components/lists/navigation-menu.apx
	demo/shared-components/lovs/boolean.apx
	demo/shared-components/lovs/low-to-high.apx