Two cats today

In my last post, I introduced a simple rule: every post gets a cat photo, and a particularly important post gets two cats. Both are here today, so you know how I feel about this one.

That second cat points to a question I think matters: When deploying an APEX application, should we import APEXlang files or run the conventional SQL export? SQLcl Project 26.2.2 now gives us both options in a Project deployment. I call them the APEXlang import and the SQL import throughout this post. To find out what makes one faster, I timed the direct SQLcl import commands and wrote a rather detailed technical article about the tests.

I also installed Google Analytics on this site. Sorry if you did not want to be tracked, but it was for your own good, okay? It tells me the average engagement time on this blog is 29 seconds. If that sounds like you, here is the short version.

TL;DR

• To find out what was going on, I traced both imports in the database and examined them with TKPROF. They create much the same APEX components, but APEXlang made about five times fewer trips between SQLcl and the database while making about three times as many database calls and spending about twice as much time on database SQL work. That made me suspect the network might decide which one was faster, while database load might matter for a very large or parallel deployment.

• It did. When I connected from my workstation over a VPN to an OCI database, APEXlang won at every application size I tested. When I ran SQLcl from an OCI compute node close to that same database, SQL was significantly faster for the larger applications. At 314 pages, the nearby SQL and APEXlang imports took 5.5 and 14.5 seconds; over the VPN, they took 56 and 35 seconds. The route from SQLcl to the database mattered more in these tests than the database’s size.

• I also checked whether SQLcl needs ORDS to import APEXlang. It does not: SQLcl includes the APEXlang compiler and imports over its database connection even when ORDS is stopped. SQLcl also appears to reuse APEXlang compiler work within the same SQLcl session. In a separate validation test, running smaller applications before larger ones saved 22% against the reverse order. For SQLcl Project, I would put smaller applications first in dist/releases/apex/apex.changelog.xml, the file that controls their deployment order.

• I built a downloadable test kit with the scripts and logs, so you can try this in your own environment. I enjoyed building it almost as much as running the tests.

If you want to see how I arrived here, including the charts, tables, and a few surprises, stay with me. If you have only 29 seconds, jump to Conclusions and recommendations for the choices I would make from these tests.

Table of Contents

• The small toolkit behind the numbers
  • One timer for the whole import
  • Changing the application’s size in both directions
  • The benchmark runner
  • The trace helper
• Looking under the hood: what the database trace showed
• Does an APEXlang import need ORDS?
• When the network changed the winner
  • How I ran the comparison
  • The timing results
  • What changed the winner
• Finding the price of APEXlang compilation
• Acknowledgements
• Conclusions and recommendations
  • Recommendations based on the tests
• Sources

The small toolkit behind the numbers

All the scripts below are in the APEXlang versus SQL test project. Its zip/ folder also contains a complete ZIP to download to your workstation.

Before I could compare imports, I needed two things: a way to time a whole import and a way to change the same application’s size without building or deleting hundreds of pages by hand. Both turned out to be more interesting than I expected.

One timer for the whole import

My first thought was SET TIMING ON. It was not quite the tool for this job. SQLcl printed no total time after apex import, and when I imported the SQL export file, it printed a separate time for each statement. That is useful when investigating one statement, but it does not answer, “How long did the application take to import?”

I wrote two SQLcl aliases instead: test_al_load for the APEXlang import and test_sql_load for the SQL import. Each asks the database for the time before and after the import and prints one elapsed time. The aliases also make the test script shorter: the runner can call the same named commands for every application size.

Here is the complete test_al_load definition from the alias file. The SQL import alias uses the same timing pattern around its @ command:

<alias name="test_al_load">
    <description>Import an APEXlang application folder and report elapsed time.</description>
    <queries>
        <query minversion="19">
            <sql><![CDATA[set define on
set verify off
set timing off
column apexlang_path new_value apexlang_path noprint
select :apexlang_path apexlang_path from dual;
column started_at new_value started_at noprint
select (sysdate - date '2026-01-01') * 86400 as started_at from dual;
prompt Importing APEXlang application from &apexlang_path. ...
apex import -input &apexlang_path.
set verify off
set define on
select 'Elapsed time: ' || to_char(
                     (sysdate - date '2026-01-01') * 86400 - &started_at
                 , 'FM999999990D000') || ' seconds' as elapsed_time
    from dual;
set define off
]]></sql>
            <binds>
                <bind id="apexlang_path">
                    <tooltip><![CDATA[Path to the APEXlang application folder.]]></tooltip>
                </bind>
            </binds>
        </query>
    </queries>
</alias>

The path arrives as the bind variable :apexlang_path. The first SELECT copies it into SQLcl’s &apexlang_path substitution variable, which the apex import command can use. The two SYSDATE queries then bracket the import.

From the extracted test kit, I loaded the aliases in a connected SQLcl session. Here is the APEXlang command with selected output; I have omitted SQLcl’s blank lines and row-count messages:

SQL> alias load scripts/xml/stel-timing-aliases.xml
Aliases Loaded
SQL> test_al_load  src/database/demo1/apex_apps/f106/demo1
Importing APEXlang application from src/database/demo1/apex_apps/f106/demo1 ...
Importing application ID: 106 into workspace: DEMO1
Import successful.
ELAPSED_TIME
------------------------------------
Elapsed time: 2.000 seconds

The SQL import alias takes the exported script’s path with or without its .sql extension. Here is its command and selected output; I have omitted the middle application-component lines, plus SQLcl’s blank lines and row-count messages:

SQL> test_sql_load  src/database/demo1/apex_apps/f106/f106
Running SQL script src/database/demo1/apex_apps/f106/f106 ...
--application/set_environment
APPLICATION 106 - EMP & DEPT Mini Hub
[application-component lines omitted]
--application/end_environment
...done
ELAPSED_TIME
------------------------------------
Elapsed time: 3.000 seconds

These timers include time spent in SQLcl and between SQLcl and the database, which is exactly the elapsed time I wanted to compare. They use SYSDATE, so the result is accurate only to whole seconds; the .000 is formatting, not millisecond precision.

I also wanted to time apex validate while SQLcl was running as sql -nolog, with no database connection. That ruled out the import aliases.

No database, no timing alias

SQLcl passes a parameterized alias argument as a bind variable. My alias needs SELECT ... FROM dual to copy that bind into a defined substitution variable (&apexlang_path) that the apex command can use. With no database connection, I cannot run that SELECT or ask the database for a timestamp. So I cannot use these timing aliases here, although apex validate itself still works.

Instead, I used a SQL script with a positional &1 argument for the path and operating-system commands for the clock. This is the timing fragment from the step script; the page-count adjustment runs before the first timestamp and appears in the next section:

define apexlang_path=&1
! bash -c "date +%s >/tmp/start_time"
apex validate -input &apexlang_path.
! bash -c "echo \"Elapsed $(($(date +%s) - $(cat /tmp/start_time))) seconds\"; rm /tmp/start_time"

From the extracted test kit, I ran the validation runner with 0, 300, and 600 extra pages. This is its command and selected output from the first validation; the page-file messages and blank lines are omitted:

$ scripts/run_apex_validate_nolog.sh 0 300 600
Validation 3 times for 0 pages
Validating APEXlang application from src/database/demo1/apex_apps/f106/demo1 ...
Validation successful.
Elapsed 12 seconds

The shell commands surround only apex validate; page cloning happens before the first timestamp. Like the alias, this timer counts whole seconds. It let me measure part of SQLcl’s local APEXlang work separately from a complete import.

Changing the application’s size in both directions

The starting application had 14 pages. To find out whether the answer changed with page count, I wrote a Python script with help from my AI coding assistant. It copies one APEXlang page, giving each copy a new page number, alias, and report ID. Here is the command for keeping ten generated copies of page 6, followed by selected output; the middle file lines are omitted:

$ python scripts/apex/clone_apex_page.py 6 10
Created demo1\pages\p02001-departments-2001.apx
Created demo1\pages\p02002-departments-2002.apx
[seven file lines omitted]
Created demo1\pages\p02010-departments-2010.apx

That 10 is the number of copies to keep, not ten more copies every time the command runs. If I already have 300 generated pages and run it with 10, the script removes 290 of those page files from disk; the application goes from 314 pages back to 24. I could move in either direction, testing 14, 24, 64, 114, 214, and 314 pages without rebuilding the application by hand. I have to admit, directly editing APEXlang files with a script was part of the fun.

A bigger win than the stopwatch

Editable APEXlang pages make tests like this practical. A small script can clone a page, update its identifiers, and grow or shrink an application whenever I need another size to test. I can extend the script for more involved pages, too. That gives me an easy way to automate repeatable scalability tests that I could not manage nearly as easily with a generated SQL export. It is a valuable APEXlang feature regardless of which deployment format imports faster.

The benchmark runner

I did not want to repeat the same sequence by hand at six application sizes. The Bash runner starts SQLcl, connects to a saved connection, selects the APEX workspace, loads the timing aliases, and starts the SQL test script. This is the part that ties those pieces together:

sql -nolog 2>&1 <<EOF | tee "$log_file"
conn -n $conn_name
exec apex_application_install.set_workspace('$workspace');
alias load scripts/xml/stel-timing-aliases.xml
@scripts/sql/apex_timing_test.sql
exit
EOF

The SQL test script asks for 0, 10, 50, 100, 200, and 300 extra pages. At each size, its step script warms up the APEXlang import, exports the installed application as SQL so both formats have the same pages, warms up the SQL import, and then measures both methods twice in reversed order. I average those two measured runs. You may wonder why I did not just use SQLcl’s spool command. It misses output from OS commands called through ! or host, including the Python page-cloning command. To preserve that output alongside SQLcl’s, the runner redirects the whole process through tee into a log file.

From the extracted project’s root, I ran the local VM test with a saved connection named demo_vm26 and workspace demo1. Here is its command and selected opening output; I have omitted the banner, blank lines, and other variable lines:

$ scripts/run_apex_timing_test.sh demo_vm26 demo1
SQLcl: Release 26.2 Production on Thu Sep 10 22:01:48 2026
Connected.
Aliases Loaded
Confirming test variables
test_app_id    = 106
test_al_dir    = src/database/demo1/apex_apps/f106/demo1

The runner repeatedly replaces application 106. It also runs git clean -fd in the generated APEX paths before starting, so I use an isolated copy of the test project rather than a working tree with changes I want to keep.

The trace helper

Timing told me which import finished first. I also wanted to see what each method asked the database to do. The trace helper accepts APEXLANG or SQL, chooses the matching timing alias, enables session tracing, imports the application, disables tracing, and prints the trace-file path. These are the important lines from scripts/sql/apex_import_trace.sql; the variable setup and command selection are above this excerpt in the full script:

alter session set tracefile_identifier = '&trace_identifier';

begin
    dbms_monitor.session_trace_enable(
        waits => true,
        binds => false
    );
end;
/

&import_command

set define on
begin
    dbms_monitor.session_trace_disable;
end;
/

select value as trace_file
  from v$diag_info
 where name = 'Default Trace File';

The account running that script needs permission to call DBMS_MONITOR. I connected as DEMO1; for this test, a DBA granted it access:

grant execute on dbms_monitor to demo1;

I ran the APEXlang trace from a connected SQLcl session after loading the timing aliases. This is the command and selected output from a later 214-page run; SQLcl’s blank lines and row-count messages are omitted:

SQL> @scripts/sql/apex_import_trace.sql APEXLANG
Trace identifier: APEX106_APEXLANG_214P_20260917_150317
Session altered.
PL/SQL procedure successfully completed.
Importing APEXlang application from src/database/demo1/apex_apps/f106/demo1 ...
Importing application ID: 106 into workspace: DEMO1
Import successful.
ELAPSED_TIME
------------------------------------
Elapsed time: 8.000 seconds
PL/SQL procedure successfully completed.
TRACE_FILE
----------------------------------------------------------------------------------------------------------------------------------------------------------------
/opt/oracle/diag/rdbms/free/FREE/trace/FREE_ora_51445_APEX106_APEXLANG_214P_20260917_150317.trc

The path is on the database host, where I used TKPROF to turn the trace into a readable report. I reconnected before tracing the SQL import so each method had its own database session. The 8-second run above illustrates the helper; the comparison in the next section uses a different pair of trace reports.

Run the tests yourself

The repository linked at the start of this section has the scripts, logs, and a complete ZIP. On Windows, I used Git Bash; the tools also ran on Oracle Linux 9. You will need Git, Bash, Python 3.9 or later, and SQLcl 26.2. Import tests need a saved SQLcl connection, APEX 26.1 or later installed in a compatible database, and access to the test workspace. For APEX 26.1, Oracle specifies Database 19c with release update 19.18 or later, or Oracle AI Database 26ai version 23.26.0 or later. To repeat the trace test, you also need TKPROF and access to the database host’s trace files. Run the import tests in an isolated copy: they replace the test application and clean generated files.

With the kit ready, I could compare what the two imports actually did in the database.

Looking under the hood: what the database trace showed

This is probably the most interesting finding in the article, and it was the hardest test to run. I needed access to the database server and its trace files. Most developers do not have that access, often for very good reasons. 😊 My local VM is perfect for this sort of experiment: it gives me a database and the access I need without asking anyone for the keys to a shared server.

I started with the 14-page application and used the page-cloning script to add 200 copies of page 6. From the test project’s root, the command and selected output looked like this (middle file lines omitted):

$ python scripts/apex/clone_apex_page.py 6 200
Created demo1\pages\p02001-departments-2001.apx
Created demo1\pages\p02002-departments-2002.apx
[196 file lines omitted]
Created demo1\pages\p02199-departments-2199.apx
Created demo1\pages\p02200-departments-2200.apx

That gave me 214 pages. I traced the APEXlang import first, exported the installed application as SQL so the SQL file contained those same pages, then reconnected and traced the SQL import in a fresh database session. The SQLcl sequence was:

alias load scripts/xml/stel-timing-aliases.xml
conn -n demo_vm26
@scripts/sql/apex_import_trace.sql APEXLANG
apex export -applicationid 106 -exptype SQL -dir src/database/demo1/apex_apps/f106 -overwrite-files -force
disconnect
conn -n demo_vm26
@scripts/sql/apex_import_trace.sql SQL

A piece of advice from an Oracle 7.3-certified DBA

There are other ways to investigate performance and look under the hood of an Oracle session, but I still reach for TKPROF. We have been working together since my Oracle 7.3 certification days, nearly 30 years ago. 🙂

The trace helper printed the path to each trace file on the database host, under /opt/oracle/diag/rdbms/free/FREE/trace/ in my VM. Oracle can split a trace into multiple files; this APEXlang trace came in two pieces. The _1.trc file was written first, so I combined the pieces in that order with cat before running TKPROF:

[oracle@vbox ~]$ cd /opt/oracle/diag/rdbms/free/FREE/trace/
[oracle@vbox trace]$ cat FREE_ora_6727_APEX106_APEXLANG_600P_20260914_1.trc FREE_ora_6727_APEX106_APEXLANG_600P_20260914.trc > APEX106_APEXLANG_COMPLETE.trc
[oracle@vbox trace]$ tkprof APEX106_APEXLANG_COMPLETE.trc apex106_apexlang_complete.prf sys=no aggregate=yes waits=yes
TKPROF: Release 23.0.0.0.0 - Development on Thu Sep 17 15:45:37 2026
[oracle@vbox trace]$ ls -lt apex106_apexlang_complete.prf
-rw-rw-r--. 1 oracle oracle 4611424 Sep 17 15:45 apex106_apexlang_complete.prf

aggregate=yes groups repeated executions of the same statement, and waits=yes retains wait information. The generated .prf file is much easier to read than the raw trace. You can inspect the saved APEXlang TKPROF report and SQL TKPROF report yourself; the local VM import log shows the broader timing runs. The full technical article has longer report excerpts.

One naming wrinkle: the saved trace filenames contain a 600P label, but I counted 214 page-creation statements in each report. The comparison below uses the contents of those reports, not the old filename label.

TKPROF separates the commands SQLcl sent to the database from the extra SQL the database ran while handling them. I call the first group foreground and the second recursive in this shortened comparison of the 214-page traces:

The first contrast is on the wire. During the SQL import, SQLcl runs the exported file’s application-component statements one by one. For the APEXlang import, SQLcl compiles APEXlang source into larger SQL statements and sends fewer, larger pieces of work. The trace recorded 52 versus 265 server-to-client message events: about 5.1 times fewer for APEXlang. That gives network delay fewer chances to add to the total. It is a strong clue, although this local trace alone cannot tell us how much time a particular VPN adds.

The second contrast is inside the database. Both imports call familiar proprietary APEX routines that create pages and components. APEXlang also has to create component IDs and resolve references that the generated SQL export already contains. In its TKPROF report, I found wwv_imp_util.create_id 2,225 times and wwv_imp_util.get_reference_id 3,966 times; neither appears in the SQL import report. That helps explain the many extra recursive calls. The overall database call total was about 3.2 times higher for APEXlang.

That extra work matters when SQLcl is close to the database and network trips are relatively cheap. In these traces, APEXlang used about 3.3 times the database SQL CPU and roughly twice the database-accounted SQL elapsed time. The complete traced imports took 37 seconds for APEXlang and 12 for SQL on my local VM. Those are single traced runs, separate from the repeated benchmarks later in this post; TKPROF’s SQL elapsed totals are also not whole-import times. Still, the load profiles explain why SQL can win locally even though APEXlang sends fewer requests.

Does an APEXlang import need ORDS?

A little deployment urban legend came up with colleagues: because ORDS handles APEXlang in App Builder, SQLcl must need ORDS for an APEXlang import too. The SQLcl documentation says that apex import compiles APEXlang input and executes the resulting PL/SQL through the current database connection. ORDS is not in that path. But with all this going on, who can trust documentation alone? 😊

So I checked on my local VM. I imported the same 214-page application once with ORDS running and once with it stopped. Both imports succeeded. The database traces showed the same 69 top-level PL/SQL blocks and the same 2,225 appearances of wwv_imp_util.create_id. The import work visible in those traces looked much the same with ORDS on or off.

Deployment note: If you want to be sure nobody can access an application through ORDS while it is changing, you can stop the ORDS service that serves it and still import its APEXlang files with SQLcl. Keep the database connection available to SQLcl, and handle any other access paths separately.

When the network changed the winner

The database trace was probably the most interesting test for me. This one is the most practical: it brings the pieces together and tells me which import I would try for a real deployment. I ran both imports as the application grew, first near a database and then across a VPN. The answer changed.

How I ran the comparison

I used three paths from SQLcl to a database:

That last pair is especially useful: I could change where SQLcl ran while keeping the destination database the same. The local VM gave me another point of comparison. It had two CPUs and 3.82 GiB of memory, while the OCI database had four CPUs and 31.06 GiB. Those resource figures describe the systems; I did not measure their resource use during each import.

I started with the same 14-page application for every path. My page-cloning script then set the number of extra copies of page 6 to 0, 10, 50, 100, 200, or 300, giving me applications of 14, 24, 64, 114, 214, and 314 pages. At each size, the runner imported APEXlang once to warm it up, then exported the installed application as a SQL file so the two formats contained the same pages. It warmed up the SQL import as well. Each import replaced the same application in the workspace; pages did not pile up in the database from one run to the next.

After those warm-ups, I measured APEXlang then SQL, and then reversed the order: SQL then APEXlang. I averaged those two measured imports for each method and page count. Reversing the order meant neither format always went first. The diagram shows the cycle:

From the extracted test project’s root, my local VM run started with this command:

$ scripts/run_apex_timing_test.sh demo_vm26 demo1

The runner connects with the saved SQLcl connection, selects the APEX workspace, loads the timing aliases, and calls the main SQL script. That script runs the same step at each target number of cloned pages:

@@apex_timing_test_step.sql 0
@@apex_timing_test_step.sql 10
@@apex_timing_test_step.sql 50
@@apex_timing_test_step.sql 100
@@apex_timing_test_step.sql 200
@@apex_timing_test_step.sql 300

I kept the full SQLcl and page-cloning output from each setup. You can inspect the local VM log, VPN log, and OCI workstation log. The averages below come from the second and third import of each method at every size; the first was the warm-up.

The timing results

Here are the mean import times in seconds. Lower is faster. I use these short labels in the column names:

• VM: SQLcl on my workstation connecting to the local VM.

• VPN: SQLcl on the same workstation connecting to the OCI database through the VPN.

• Near OCI: SQLcl on the OCI workstation connecting to that same OCI database.

The 314-page rows show exactly how those means arose. Over the VPN, the two measured APEXlang imports took 35 and 35 seconds; SQL took 52 and 60, averaging 56. Near the same OCI database, APEXlang took 18 and 11 seconds, averaging 14.5; SQL took 6 and 5, averaging 5.5. These are small samples, but the reversal between the two client paths is hard to miss.

The chart makes the change across application sizes easier to see. Colour identifies the client path; solid lines are APEXlang imports, dashed lines are SQL imports.

Average of two measured imports per method and application size. Lower is faster.

What changed the winner

Over the VPN, APEXlang was faster at all six application sizes. At 314 pages, it took 35 seconds, compared with 56 seconds for the SQL import. The trace result now makes practical sense: APEXlang’s fewer exchanges give the network fewer opportunities to slow it down.

And the Oscar goes to…

Network path. Both imports slowed when I moved SQLcl from the OCI workstation near the database to my workstation across the VPN. At 314 pages, SQL import went from 5.5 to 56 seconds; APEXlang went from 14.5 to 35 seconds. Moving the client made the largest difference I observed.

Database capacity. With SQLcl close to each database, my small local VM kept up surprisingly well with the much more powerful OCI database. At 214 pages, APEXlang took 8 seconds on the VM and 9 near OCI; SQL took 5.5 and 4 seconds. Across the application sizes I tested, the difference in database resources had far less impact than the client path.

APEXlang or SQL? SQL import sends more separate requests, while APEXlang groups work into fewer, larger requests. Over the VPN, APEXlang won at every size I tested. Its largest saving was 21 seconds at 314 pages. If SQLcl must deploy over a slow path, APEXlang is the option I would test first.

Finding the price of APEXlang compilation

The import timing logs left me with a small mystery. The first APEXlang import at a given application size was often slower than the next two. SQL import sometimes showed a bump too, but it was usually smaller. Here are the 14-page and 314-page cycles from the three client paths, with the first run followed by the two repeats. The 14-page cycle started in a fresh SQLcl session; the 314-page cycle came after all the smaller sizes in that same session. All times are in seconds, and a negative change means the next run was faster.

APEXlang import

SQL import

Across all six sizes and three client paths, the first APEXlang import was slower than both repeats in 16 of 18 cycles. For SQL import, that happened in 11 of 18; the 314-page VPN SQL run even got slower on repeat. The size of the bump differed too: SQL’s first-to-second gain was usually only a few seconds and never more than 5 seconds, while APEXlang’s was 11 to 16 seconds in the three 14-page rows and still 9 seconds at 314 pages on the VM. That stronger APEXlang pattern made me suspect work in SQLcl’s compiler, rather than a warm-up cost shared by both imports. But the imports run different database work, so these timings alone could not tell me where the bump occurred.

To investigate that bump, I tried to break the elapsed import time into parts I could reason about: compilation and validation in SQLcl, time across the network, and work in the database. That gave me the rough formula below. It is not a stopwatch breakdown, but the test with 200 cloned pages (214 pages total) later gave it a surprisingly useful reality check: the two parts I could measure came close to the full import time.

My very approximate timing formula ©

APEXlang import time ≈
SQLcl compilation and validation
+ network time
+ database time

No, it is not E = mc², but for an APEX developer planning a deployment, it might be more useful. 😊

TKPROF had already given me an approximate database SQL time. Network time was harder to measure independently, so I went after the local SQLcl part. Fortunately, SQLcl has apex validate. It compiles and checks APEXlang files even when I start SQLcl with sql -nolog, without a database connection. That let me time compilation and validation without database work or network exchanges. It does not isolate compiler CPU time alone, but it makes the comparison much cleaner. The toolkit section above shows the shell timer I used around that command.

I ran two orders in separate, fresh SQLcl processes. One went from 14 to 314 to 614 total pages; the other visited the same sizes in reverse. Within each process, I validated each size three times before moving to the next, keeping SQLcl open for all nine validations. From the extracted test project’s root, these were the commands:

$ scripts/run_apex_validate_nolog.sh 0 300 600
$ scripts/run_apex_validate_nolog.sh 600 300 0

The arguments are the numbers of cloned pages added to the 14-page base application. The runner captured the smallest-first log and largest-first log. Here are their elapsed times in seconds:

The 0 s entry means two whole-second timestamps fell in the same second, not that validation took no time. The chart plots the nine validations in the order they actually ran, so you can see when each new size arrived:

Each line covers three validations at each of the same three application sizes. The sizes arrive in opposite orders.

The first validation in a fresh process took 12 seconds for 14 pages or 59 seconds for 614 pages. Repeats were faster. Growing to the next size brought another bump; shrinking did not. A third run, from 214 to 114 to 314 pages, showed the same pattern: 23, 5, and 5 seconds at 214 pages, then 3, 3, and 2 at 114, then 12, 7, and 7 after growing to 314. SQLcl appears to retain and reuse resources for APEXlang compilation within a process, adding more when it meets a larger application. I did not measure memory allocation directly, so that is an explanation suggested by the timing pattern rather than a measurement of how SQLcl manages memory.

The 214-page run also gives my rough formula a reality check. Its first disconnected validation took 23 seconds; the database trace of a separate APEXlang import recorded about 15.96 seconds of database SQL elapsed time; the whole traced import took 37 seconds. The first two figures add to roughly 39 seconds, close to the observed import time. They come from separate runs, and validation is not pure compiler time, so this is a useful mental model rather than a way to calculate an import down to the second.

What the compiler test taught me

My rough formula passed a useful reality check on the local VM, where SQLcl and the database were close. Validation time plus database SQL time came close to the complete import time. It is an approximation, but it shows that work inside SQLcl can be a significant part of an APEXlang import. If deployment is slow despite a good network and a healthy database, the computer running SQLcl deserves attention. I have not tested whether CPU, memory, or I/O is the limiting factor.

The disconnected test made the first-run penalty much clearer. Every increase in application size we tested brought a bump on its first validation; decreasing the size brought no comparable bump. SQLcl appears to build up and reuse compiler resources within a process, though I did not measure those allocations directly. Validating the applications smallest first took 120 seconds versus 154 seconds largest first, a 22% saving.

In a SQLcl Project deployment, dist/releases/apex/apex.changelog.xml sets the APEX application order within one SQLcl run. I do not know of a parallel-degree setting for APEXlang imports inside that deployment, so I would put the smaller applications first in that file. Outside SQLcl Project, parallel SQLcl sessions can be a good choice for total elapsed time. Each process still has to establish its own compiler state and pay the first-run cost, so weigh that against the reuse you can get in one session.

Acknowledgements

Thank you to my colleague Fekrat El Wehedi for helping with this investigation by arranging access to the OCI workstation I used in these tests.

Conclusions and recommendations

An APEXlang import has three parts: compilation and validation in SQLcl, network exchanges, and database work. SQL import has two: network exchanges and database work. It runs the SQL export without an APEXlang compilation and validation step. SQL import sends more separate requests, while APEXlang shifts more work into the database. That balance lets the network path change the winner, and it makes the computer running SQLcl an important part of APEXlang deployment time.

Recommendations based on the tests

• If SQLcl runs close to the database, consider importing the SQL export file, especially for a larger application. At 314 pages, the SQL import took 5.5 seconds near the OCI database, versus 14.5 seconds for the APEXlang import.
• If SQLcl must connect over a slower route, try APEXlang. Across my VPN, it won at every tested size; at 314 pages, it took 35 seconds versus 56 seconds for SQL.
• If database load matters, consider SQL import for a very large application or several imports running in parallel. In the 214-page trace, APEXlang made about 3.2 times as many database calls and used about 3.3 times as much SQL CPU. Its report shows thousands of ID-generation and reference lookups absent from the SQL import report.
• If SQLcl Project deploys several APEXlang applications, put smaller ones first in dist/releases/apex/apex.changelog.xml. The deployment runs in one SQLcl invocation, where compiler work can be reused. Smallest first saved 22% in my validation test. Outside Project, parallel sessions may shorten the batch, but each process pays its own first-run cost.
• If you need the application unavailable through ORDS during deployment, you can stop ORDS. SQLcl’s APEXlang import still works through its database connection.

Try it with your application

These are choices to test in your environment; there is no universal network threshold. The test kit lets you repeat the comparison with your application and network path. Please feel free to download it from the links in Sources below, use it, and modify it to suit your needs. If you get different results, contact me or share them through the discussion link below.

Sources

My repository and test material

• Full APEXlang versus SQL deployment performance investigation
• APEXlang versus SQL test project, scripts, and logs
• Downloadable APEXlang versus SQL test kit
• APEXlang import TKPROF report
• SQL import TKPROF report
• Local VM import timing log
• VPN import timing log
• OCI workstation import timing log
• Smallest-first disconnected validation log
• Largest-first disconnected validation log
• Intermediate-size disconnected validation log

Oracle documentation

• Oracle APEX 26.1 installation requirements
• Oracle SQLcl 26.2 release notes
• Oracle SQLcl documentation: APEXlang commands overview
• Oracle SQLcl 26.2 documentation: PROJECT command and deploy options
• Oracle Database documentation: Performing Application Tracing with TKPROF

Before getting into SQLcl, I have also made an important editorial decision. Starting with this article, I will try to put a fresh photo of one or both of my beloved cats, Mister and Frisbee, at the top of every post. Why? Because it is my blog, and I can do whatever I want.

SQLcl 26.2 contains several improvements I genuinely want to adopt: SQLcl 26.2.2 fixes the binary/static-file corruption during APEXlang export, multi-operation DDL scripts are split into separate Liquibase changesets, and SQLcl Project can deploy an application directly from APEXlang source. Unfortunately, SQLcl Project 26.2.2 retains other APEXlang export defects from 26.1, introduces new structural problems, and removes the documented directory arrangement that made those defects manageable with a standalone apex export. For my existing project, that combination is a migration blocker.

TL;DR

• SQLcl Project 26.1 and 26.2.2 both have APEXlang export defects. project export lowercases APEXlang file and directory names and can retain page files deleted from the application. For static files, the case change can make the export fail APEXlang validation because the .apx reference and physical filename no longer match. For deleted pages, the stale file can remain part of the exported application and bring the deleted page back during a later APEXlang deployment.
• The documented f<appId>/<app-alias>/ structure used in 26.1 gave me a safe workaround: remove the defective Project-generated APEXlang tree and replace it with a clean standalone apex export. In 26.2.2, legacy mode flattens the APEXlang files into f<appId>/, while APEXlang mode makes the mutable application alias the source root. Neither preserves the previous application-ID-scoped workaround.
• Testing also exposed additional problems: a targeted application export unexpectedly attempts ALL_USERS; staging removes existing APEX deployment properties and can retain both the legacy SQL controller and the new APEXlang controller; the APEXlang export guard can report Git changes when the working tree is clean; and project config -list does not reveal user-settable options until they have been explicitly set.
• SQLcl 26.2.2 fixes the serious binary/static-file corruption defect, the new apex.apexlang option is a good idea, and APEXlang deployment can be faster than SQL deployment in some circumstances. It should select what SQLcl Project places in dist, not reorganise src, override a requested export.apex.exptype, or rewrite Git history. SQLcl 26.2 also delivers an important changeset-splitting improvement, but I am staying on 26.1 until the APEX source and deployment structures become predictable again.

Table of Contents

• TL;DR
• Table of Contents
• Test scope and the two modes
• What the SQLcl documentation promises
• Why the 26.1 structure mattered
• Mode 1: readable output
  • A hybrid source layout replaces the documented structure
  • The old export defects remain
  • Staging changes the controller and removes deployment properties
  • Unexpected exports and undiscoverable configuration
• Mode 2: APEXlang enabled
  • A useful deployment option also reorganises the source
  • A mutable alias is not a stable application identity
  • Git protection becomes an export blocker
  • APEXlang mode: export and stage deep dive
• Oracle’s clarification: regressions and intended design
  • Syme’s independent export tests
  • Neil’s explanation of the intended modes
  • What the clarification resolves
  • What remains unresolved
• What did we gain, and what did we lose?
  • What we gained
  • What we lost
  • Additional regressions and migration friction
• What I want from SQLcl Project
  • APEXlang source and deployment
  • Other SQLcl Project fixes
• Conclusion
• Sources

Test scope and the two modes

I tested with SQLcl 26.2.2.0, build 26.2.2.233.1901. This was not a newly generated sample project. I took an existing SQLcl Project repository that had been working with SQLcl 26.1 and tested the upgrade on separate Git branches.

The test application was application 106 in workspace DEMO1, using parsing schema DEMO1 and application alias demo1. The existing Project configuration requested both READABLE_YAML and APPLICATION_SOURCE through export.apex.exptype.

SQLcl 26.2.2 effectively gave me two models to test:

I ran the same basic workflow in both modes: export application 106, inspect the resulting tree and Git changes, validate or import the APEXlang source, stage the project, and repeat operations after changing or deleting application components. The test included a static file with mixed-case characters in its name and pages that were subsequently deleted in APEX Builder. Repeating the export was important: an initial export can look correct while still failing to remove files that disappeared from the database later.

This article is about the correctness and operability of those two models, not their relative deployment performance. I have tested SQL and APEXlang deployment performance as well, and each can be faster in different circumstances. That comparison deserves its own article. Here, the important point is that both are useful deployment options, so switching between them should be a normal and inexpensive project operation.

What the SQLcl documentation promises

The starting point is not my preferred directory convention. It is Oracle’s published SQLcl 26.2 APEXlang Project Structure documentation.

For an APEX application inside SQLcl Project, the documentation specifies this structure:

src/database/<schema>/apex_apps/
`-- f<appId>/
    |-- f<appId>.sql
    `-- <app-alias>/
        |-- application.apx
        |-- pages/
        |-- shared_components/
        |-- deployments/
        `-- .apex/

The documentation explains that this arrangement maintains consistency between the SQLcl apex and project commands. It also says that, as part of the change, database export removes the previous directory structure automatically.

Oracle’s SQLcl 26.2 documentation specifies f<appId>/<app-alias>/ and describes automatic removal of the previous directory structure during database export.

That is a meaningful product contract. Once Oracle documents a filesystem layout, users build export aliases, validation commands, CI/CD jobs, cleanup scripts, Git review practices, and deployment tooling around it. A documented layout cannot reasonably be treated as an internal implementation detail that may change without notice.

The wording about automatic removal is specifically about the previous directory structure; it does not explicitly promise that every obsolete component file will be removed on every export. I will test stale component cleanup separately. The structural promise itself, however, is unambiguous: the application ID is the stable outer directory, the application alias is below it, and the SQL export can coexist beside the APEXlang source.

Observed structure mismatch

Neither directory layout I observed in SQLcl 26.2.2 matches that documented model. In readable mode, the APEXlang files are flattened directly into f106. With apex.apexlang=true, the application alias becomes the root and the f106 boundary disappears. The forum discussion later explained an intended distinction between two modes, but that distinction is not present on this documentation page. A forum explanation is useful context; it should not be required to discover the fundamental storage model of a documented product feature.

Why the 26.1 structure mattered

The f<appId>/<app-alias>/ layout was not merely tidy. It gave every application a stable, application-ID-scoped boundary and kept two useful representations together: the fNNN.sql file used by SQLcl Project for SQL deployment, and the APEXlang source used for review, validation, and development.

That mattered because SQLcl Project 26.1 had several APEXlang export defects. SQLcl 26.2.2 fixes one of the most serious ones: exported binary and static files are no longer corrupted. That is an important fix. Two other defects remain in my tests:

1. SQLcl Project lowercases APEXlang file and directory names. For a mixed-case static filename, the .apx source can retain the original case while the physical file is written in lowercase. apex validate then fails with REFERENCE_NOT_FOUND because the referenced file does not exist under that exact name.
2. Re-exporting can leave obsolete APEXlang files in place. If a page is exported, then deleted in APEX Builder, its page file may survive the next Project export. An APEXlang import or deployment can consequently include the stale file and bring back a page that was deliberately deleted from the application.

The documented 26.1 structure gave me a practical way to compensate. My prj_exp_app SQLcl alias performed two exports for one application:

1. It ran project export -o APEX.<appId> so SQLcl Project still generated the fNNN.sql source required by the normal staging and SQL deployment workflow.
2. It then ran a standalone apex export with -exptype APEXLANG and -force, replacing the defective APEXlang subdirectory with a clean export from the database.

Conceptually, the result remained simple:

f106/
|-- f106.sql       # generated by project export
`-- demo1/         # replaced by apex export -exptype APEXLANG -force

Because f106 was the stable application boundary, the alias knew exactly where application 106 belonged. The mutable alias remained below that boundary. A changed alias or a stale APEXlang tree could be cleaned without confusing one application with another, and the standalone export could repair the readable source without removing the Project-generated SQL file.

This was admittedly a workaround, but it was safe, deterministic, and aligned with the published directory structure. Most importantly, it meant that outstanding APEXlang export bugs did not block the rest of SQLcl Project. I could continue using SQL deployment while retaining clean APEXlang source, and I could change deployment strategy later without reorganising src or rewriting the application’s Git history.

That is why the 26.2.2 directory change is more than an inconvenience. The old bugs have not all disappeared, but the directory structure that allowed me to work around them has.

The next two sections deliberately stay close to the evidence. I will describe only what I ran and what SQLcl produced in each mode: the directory trees, validation and import results, Git changes, and staging output. I will return to the consequences, design trade-offs, and changes I would like Oracle to make after both sets of observations are on the table. For now, stay with me through the facts.

Mode 1: readable output

In the first mode, apex.apexlang was absent from project.config.json. According to Oracle’s later clarification in the forum, this is the legacy or readable-output mode: f106.sql remains the source of truth and APEXlang is supplemental readable source.

A hybrid source layout replaces the documented structure

Before running the export, I followed the SQLcl Project migration guidance and removed the existing APEX application source directory. This ensured that the test started without files left behind by the 26.1 layout:

rm -rf src/database/demo1/apex_apps

From inside SQLcl, I exported only application 106:

project export -o apex.106

The new APEXlang files were written directly into f106, alongside f106.sql. There was no application-alias directory and no readable directory:

src/database/demo1/apex_apps/f106/
|-- .apex/
|-- deployments/
|-- pages/
|-- shared-components/
|-- application.apx
|-- f106.sql
`-- page-groups.apx

Git consequently saw the files under the previous f106/demo1/ tree as deletions and the flattened files as new, untracked files. An abbreviated git status captured the structural change:

git status

The relevant output looked like this:

deleted:    src/database/demo1/apex_apps/f106/demo1/application.apx
deleted:    src/database/demo1/apex_apps/f106/demo1/pages/...
deleted:    src/database/demo1/apex_apps/f106/demo1/shared-components/...
modified:   src/database/demo1/apex_apps/f106/f106.sql

Untracked files:
  src/database/demo1/apex_apps/f106/.apex/
  src/database/demo1/apex_apps/f106/application.apx
  src/database/demo1/apex_apps/f106/deployments/
  src/database/demo1/apex_apps/f106/page-groups.apx
  src/database/demo1/apex_apps/f106/pages/
  src/database/demo1/apex_apps/f106/shared-components/

This is the hybrid layout Oracle later identified in the forum as a SQLcl 26.2.2 regression.

The old export defects remain

I then tested two defects already present in SQLcl Project 26.1. In APEX Builder, I created page 5, named Drop Me Salary Dashboard Copy, and uploaded a static file named mixedCaseImageName.webp. I exported the application, deleted page 5 in APEX Builder, and exported it again.

After the second export, the file for page 5 was still present. The physical static filename had also been converted to lowercase:

pages/p00005-dropme-salary-dashboard-copy.apx
shared-components/static-files/mixedcaseimagename.webp

After page 5 was deleted in APEX Builder and the application was exported again, its .apx file remained. The physical mixed-case static filename was written entirely in lowercase.

The lowercasing is not only cosmetic. The reference inside shared-components/static-files.apx retained the original filename, mixedCaseImageName.webp, while the physical file was named mixedcaseimagename.webp. Validating the flattened application root reproduced the mismatch:

apex validate -input src/database/demo1/apex_apps/f106

The result was an APEXlang compiler error:

APEXlang Compile Errors:
File: shared-components/static-files.apx
Line: 26
Column: 0
Type: REFERENCE_NOT_FOUND
Error: referenced file shared-components/static-files/mixedCaseImageName.webp
       in the fileName property is not found

The binary contents of the static file were no longer corrupted in SQLcl 26.2.2. That earlier defect is fixed. Filename casing and stale page cleanup are separate defects, and both remained in this mode.

To test the consequence of the stale page independently, I manually removed the mixed-case static file and its reference from the exported source so that the unrelated validation error would no longer block the import. I then imported the flattened APEXlang application:

apex import -input src/database/demo1/apex_apps/f106

SQLcl reported a successful import:

Importing application ID: 106 into workspace: DEMO1
Import successful.

When I opened application 106 in APEX Builder, page 5 was present again. It had been deleted in APEX Builder before the second export, but its stale .apx file remained in the source tree and the subsequent apex import recreated it. This confirms that stale page files are not merely repository noise: they can change the deployed application.

Staging changes the controller and removes deployment properties

The first project stage run did not overwrite the application controller generated by SQLcl 26.1:

project stage

It stopped with this error:

Stage is Comparing:
Old Branch      refs/heads/main
New Branch      refs/heads/26.2-readable

ERROR: An error has occurred processing your request:
The generated APEX install file dist\releases\apex\f106\f106.xml has been
edited and stage will not overwrite it automatically.
Restore the generated file, remove it, or merge your edits manually before
running stage again.

The controller had not been manually edited; it was the generated file retained from SQLcl 26.1. I removed that file and ran staging again:

rm -f dist/releases/apex/f106/f106.xml

project stage

This time staging completed and generated a new controller. Compared with the 26.1 file, the new version contained additional offset-handling logic and changed from a numeric checksum to a longer hexadecimal checksum:

SQLcl 26.2.2 regenerated f106.xml with new offset logic and a different checksum format.

The new checksum was deterministic in this test. After rolling back the staged changes and running project stage again against the same source, SQLcl generated the same value:

-- sqlcl_checksum  a3021add4b68564e09161286a87d58c068df948d

The same staging operation also removed four existing APEX properties from dist/env/default.properties:

 parameter.demo1=demo1
-parameter.apex.106.workspace=DEMO1
-parameter.apex.106.schema=DEMO1
-parameter.apex.106.alias=DEMO1
-parameter.apex.106.appId=106

After staging, only parameter.demo1=demo1 remained; the application workspace, schema, alias, and application-ID properties were removed.

Unexpected exports and undiscoverable configuration

The targeted application export also attempted to process database users. The command was limited to APEX application 106:

project export -o apex.106

However, the debug output contained ORA-31603 errors for multiple users outside the configured project schema. This is an excerpt:

Errors:
============================================================
ORA-31603: object "CLA_PUBLIC" of type USER not found in schema "DEMO1"
ORA-31603: object "CO" of type USER not found in schema "DEMO1"
ORA-31603: object "HR" of type USER not found in schema "DEMO1"
ORA-31603: object "ORDS_METADATA" of type USER not found in schema "DEMO1"
ORA-31603: object "CLA_UTILITIES" of type USER not found in schema "DEMO1"
ORA-31603: object "CLA_APEX" of type USER not found in schema "DEMO1"
ORA-31603: object "CLA_DEPLOYER" of type USER not found in schema "DEMO1"
ORA-31603: object "HRREST" of type USER not found in schema "DEMO1"
ORA-31603: object "ORDS_PUBLIC_USER" of type USER not found in schema "DEMO1"
ORA-31603: object "PDBADMIN" of type USER not found in schema "DEMO1"
ORA-31603: object "DEMO2" of type USER not found in schema "DEMO1"
ORA-31603: object "DEMO1" of type USER not found in schema "DEMO1"
ORA-31603: object "SH" of type USER not found in schema "DEMO1"
ORA-31603: object "AV" of type USER not found in schema "DEMO1"
============================================================
-------------------------------
APEX_APPLICATION              1
-------------------------------
Exported 1 objects

Adding this condition to .dbtools/filters/project.filters stopped the unwanted user export attempts:

export_type not in ('ALL_USERS'),

Finally, project config -list reported only settings already stored in project.config.json. Because apex.apexlang had not yet been set, the command did not show that the setting existed or that its effective value was false:

project config -list

The output ended with the explicitly stored staging options and contained no apex.apexlang row:

 +---------------------------------------------------------------------------------+
 | git.defaultBranch                      | main                                   |
 +---------------------------------------------------------------------------------+
 | stage.excludeObjects                   | ["ALL.user"]                           |
 +---------------------------------------------------------------------------------+
 | stage.generatedFormat                  | liquibase                              |
 +---------------------------------------------------------------------------------+
 | stage.softObjectIsolation              | change                                 |
 +---------------------------------------------------------------------------------+
 | stage.substituteSchemas                | true                                   |
 +---------------------------------------------------------------------------------+
SQL>

After apex.apexlang was explicitly added to the configuration, it appeared in this list. That observation belongs to the second mode.

Mode 2: APEXlang enabled

A useful deployment option also reorganises the source

For the second mode, I created a separate branch and enabled the new Project setting:

project config set -name apex.apexlang -value true

The command added this object to .dbtools/project.config.json:

"apex" : {
  "apexlang" : true
}

The new setting appears in project.config.json only after it is explicitly enabled.

It also became visible at the end of project config -list:

 +---------------------------------------------------------------------------------+
 | stage.substituteSchemas               | true                                   |
 +---------------------------------------------------------------------------------+
 | apex.apexlang                         | true                                   |
 +---------------------------------------------------------------------------------+

As in the first mode, I removed the existing APEX source before testing the new layout:

rm -rf src/database/demo1/apex_apps

I then exported application 106:

project export -o apex.106

SQLcl detected the old staged SQL payload, warned that APEXlang mode was enabled, and completed the export:

*** APEX_APPLICATIONS ***
WARN: apex.apexlang=true, but legacy APEX SQL source or stage content remains.
Remove legacy src/database/<schema>/apex_apps/f<app_id> directories,
remove legacy dist/releases/apex/f<app_id> directories, then run project
export and project stage again.
Found: dist\releases\apex\f106\f106.sql
Exporting Workspace DEMO1 - application 106:EMP & DEPT Mini Hub
-------------------------------
APEX_APPLICATION              1
-------------------------------
Exported 1 objects
Elapsed 16 sec

The source layout was now different from both the documented structure and the readable-mode structure. The application alias became the directory root directly below apex_apps:

src/database/demo1/apex_apps/
`-- demo1/
    |-- .apex/
    |-- deployments/
    |-- pages/
    |-- shared-components/
    |-- application.apx
    `-- page-groups.apx

There was no f106 parent and no f106.sql in the newly generated source. Although export.apex.exptype still requested READABLE_YAML and APPLICATION_SOURCE, enabling apex.apexlang selected this APEXlang-only source model.

A mutable alias is not a stable application identity

The application ID remained 106 throughout the test, but the application alias was editable in APEX Builder. I first exported the application with alias demo1. I then changed the alias to demo1-1 in APEX Builder and exported again.

The resulting source tree contained two application roots:

src/database/demo1/apex_apps/
|-- demo1/
|   |-- .apex/
|   |-- deployments/
|   |-- pages/
|   `-- shared-components/
`-- demo1-1/
    |-- .apex/
    |-- deployments/
    |-- pages/
    `-- shared-components/

The original demo1 directory remained beside the new demo1-1 directory. Neither path contained the stable application ID in its directory name; the ID was available only inside the application metadata and deployment configuration.

Git protection becomes an export blocker

Next, I changed the application in APEX Builder and tried to refresh its APEXlang source. SQLcl refused to export over a target that it considered changed:

project export -o apex.106

The command reported:

Exporting Workspace DEMO1 - application 106:EMP & DEPT Mini Hub
APEXlang export target has tracked or untracked Git changes:
src\database\demo1\apex_apps\demo1.
Commit, stash, or remove those changes before re-exporting.
Failed to export APEXlang application_id = 106 due to APEXlang export target
has tracked or untracked Git changes:
src\database\demo1\apex_apps\demo1.
-------------------------------
Exported 0 objects
Elapsed 13 sec

I committed the generated source and tried again. It failed again, even though git status reported no changes:

SQL> project export -o apex.106
*** APEX_APPLICATIONS ***
WARN: apex.apexlang=true, but legacy APEX SQL source or stage content remains. Remove legacy src/database/<schema>/apex_apps/f<app_id> directories, remove legacy dist/rele
ases/apex/f<app_id> directories, then run project export and project stage again. Found: dist\releases\apex\f106\f106.sql
Exporting Workspace DEMO1 - application 106:EMP & DEPT Mini Hub
APEXlang export target has tracked or untracked Git changes: src\database\demo1\apex_apps\demo1. Commit, stash, or remove those changes before re-exporting. Failed to expo
rt APEXlang application_id = 106 due to APEXlang export target has tracked or untracked Git changes: src\database\demo1\apex_apps\demo1. Commit, stash, or remove those cha
nges before re-exporting.
-------------------------------
-------------------------------
Exported 0 objects
Elapsed 12 sec


SQL> ! git status
On branch 26.2-apexlang
nothing to commit, working tree clean

Export blocker

Despite the clean working tree, the next project export -o apex.106 returned the same tracked-or-untracked-changes error and exported zero objects. Committing the target therefore did not resolve the condition described by the error message in this test.

The repeatable way I found to continue was to remove the complete alias directory before every refresh and then export again:

rm -rf src/database/demo1/apex_apps/demo1

project export -o apex.106

With no target directory present, the export completed and recreated the APEXlang application.

APEXlang mode: export and stage deep dive

The export that followed my manual removal of the complete alias directory cannot demonstrate automatic cleanup: the page files were already gone because I had deleted the whole source tree to get past the Git protection error.

To test deletion handling properly, I first established a normal APEXlang baseline. I exported and staged the APEXlang branch, reviewed and committed its output, and merged it into main. I then created a new branch for the next application change:

git checkout -b 26.2-apexlang-delta

At that point, page 100 (Old Home Backup) existed in both the committed src and dist baselines. I deleted page 100 in APEX Builder and exported application 106 on the delta branch:

project export -o apex.106

This export correctly removed the existing page file from src:

Starting from an established APEXlang baseline, deleting page 100 in APEX Builder produced the expected deletion from src.

I then staged the delta:

project stage

The page was also removed from dist. I repeated the same baseline-and-delta test with a static file deleted in APEX Builder. Its physical file and source reference were removed from src, and staging propagated those deletions into dist. This is the cleanup behaviour I want: a component deleted in APEX Builder disappears from the exported source and then from the deployment payload.

Staging generated an APEXlang payload beneath the application alias:

dist/releases/apex/demo1/
|-- demo1.xml
`-- demo1/
    |-- .apex/
    |-- deployments/
    |-- pages/
    |-- shared-components/
    |-- application.apx
    `-- page-groups.apx

Staging problem

The existing legacy dist/releases/apex/f106/ directory remained present and caused warnings, but staging still completed. More importantly, the top-level APEX changelog retained the old SQL controller and added the new APEXlang controller:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.3.xsd">
<include file="f106/f106.xml" relativeToChangelogFile="true"/>
<include file="demo1/demo1.xml" relativeToChangelogFile="true"/>
</databaseChangeLog>

SQLcl warned that legacy APEX SQL stage content remained, but project stage did not remove that content or its <include>. The staged changelog therefore referenced both the previous f106/f106.xml SQL deployment and the new demo1/demo1.xml APEXlang deployment.

The new APEXlang change controller used the SQLcl apex import command against the APEXlang payload:

<changeSet id="INSTALL_demo1"
           author="SQLCL-Generated"
           logicalFilePath="releases/apex/demo1/demo1.xml"
           failOnError="true"
           runOnChange="true">
  <n0:runApexScript relativeToChangelogFile="true">
    <n0:source><![CDATA[
-- sqlcl_checksum  11cd5b765726122ea37a4f1028545dcbb4604ae5
-- sqlcl_apexlang_payload_hash 9559ab34930d618b0d57a2ebc655bfd7f2897ca127c0afde2e700a709d6c48e9
declare
  -- sqlcl version       = 26.2.2.0 
  -- override_schema     = ${apex.demo1.schema}
  -- override_alias      = ${apex.demo1.alias}
  -- override_workspace  = ${apex.demo1.workspace}
  -- override_app_id     = ${apex.demo1.appId}

/*
---SKIPPED
*/
end;
/
apex import -input demo1
    ]]></n0:source>
  </n0:runApexScript>
</changeSet>

I rolled back the staged changes and ran project stage again without changing the source. Both generated values were identical across the two runs:

-- sqlcl_checksum  11cd5b765726122ea37a4f1028545dcbb4604ae5
-- sqlcl_apexlang_payload_hash 9559ab34930d618b0d57a2ebc655bfd7f2897ca127c0afde2e700a709d6c48e9

In other words, a delta created from an established APEXlang baseline correctly propagated component deletions from APEX Builder through src and into dist, produced stable checksums for unchanged source, and generated a deployment controller that imports the APEXlang application directly. At the same time, staging left the legacy SQL controller active beside the new APEXlang controller.

Oracle’s clarification: regressions and intended design

The responses in the Oracle Forum discussion were helpful. They confirmed that the layouts I observed were not the complete intended design. They also exposed a larger problem: the intended design described in the discussion is materially different from the design described in Oracle’s published documentation.

Syme’s independent export tests

Syme (skutz-Oracle) first tested the standalone apex export command with several combinations of -exptype and -split. His results confirmed that the requested export type controls the generated layout:

apex export -applicationid 101 -exptype SQL -split
apex export -applicationid 101 -exptype APEXLANG
apex export -applicationid 101 -exptype APEXLANG,SQL
apex export -applicationid 101 -exptype APEXLANG,SQL -split

The SQL-only export created an f101 structure. The APEXlang-only export used the application alias, sample-calendar, as its root. Requesting APEXLANG,SQL produced both representations, including f101.sql or the split f101 SQL directory beneath the alias root.

After those tests, Syme confirmed that there were reproducible problems in how the APEX files were being laid out. He also raised the underlying design question: should SQL and APEXlang exports be supported together, or should SQL remain below f<appId> while APEXlang lives below <app-alias>?

That independent reproduction is important. It confirms that the disagreement among project export, standalone apex export, SQLcl 26.1, and the documentation was real; it was not caused by my existing repository or configuration.

Neil’s explanation of the intended modes

Neil Fernandez then described the intended SQLcl Project model. In compact form, it is this:

In the first mode, APEXlang is intended to replace the previous READABLE_YAML output; it is not the deployment source. In the second mode, the application alias becomes the source-directory root, and neither f<appId>.sql nor readable/ is generated. Neil also clarified that apex.apexlang completely overrides export.apex.exptype and that SQL and APEXlang output must not be mixed within the Project model.

The Git protection is also intentional. SQLcl is meant to refuse an export that would overwrite tracked or untracked changes in the APEXlang target. If an application alias changes, a clean export is intended to create the new alias directory and remove the previous one, provided local changes have first been committed or stashed.

Finally, Neil identified two separate layout regressions:

1. SQLcl 26.1.2 placed supplemental APEXlang output under the application alias instead of under f<appId>/readable/.
2. SQLcl 26.2.2 removed that boundary and flattened the APEXlang files directly into f<appId>, creating the hybrid layout shown in Mode 1.

The binary/static-file corruption was a third, separate issue. Oracle fixed that defect in SQLcl 26.2.2.

What the clarification resolves

This explanation resolves several factual questions from the test:

• The flattened Mode 1 layout is a confirmed SQLcl 26.2.2 regression.
• The f<appId>/<app-alias>/ layout produced in SQLcl 26.1.2 was also not Oracle’s intended readable-output location; Oracle intended f<appId>/readable/.
• The alias-root layout in Mode 2 is intentional when apex.apexlang=true.
• Suppressing f<appId>.sql and disregarding export.apex.exptype in that mode are intentional design choices.
• Protecting locally modified APEXlang source is intentional, although the error against my clean Git working tree remains a bug.

It also makes the mixed controller result more surprising. If SQL and APEXlang output must not be mixed, staging should not leave both f106/f106.xml and demo1/demo1.xml active in the top-level changelog after the Project switches modes.

What remains unresolved

Still unresolved

The clarification explains Oracle’s intent, but it does not resolve the documentation conflict. The published SQLcl 26.2 directory-structure page says that SQLcl Project uses:

f<appId>/<app-alias>/

Its example places f<appId>.sql and the application-alias APEXlang directory together below the stable application-ID root. It does not describe f<appId>/readable/, the apex.apexlang switch, the alias-root source model, the override of export.apex.exptype, or the rule that SQL and APEXlang output must not be mixed.

I am surprised that none of those distinctions is documented on the page that defines the SQLcl Project APEXlang structure. The configuration is also not discoverable through project config -list until the setting has already been added, so a user cannot learn about the second mode there either.

From Oracle’s internal perspective, the 26.1.2 layout may have been a regression. From a user’s perspective, however, it was the behaviour described by Oracle’s documentation, and it provided the stable structure around which working export and deployment tooling could be built. Once a filesystem contract is published, users will depend on it.

A forum response is valuable, especially while bugs are being investigated, but it cannot replace the product documentation. Nor do I think the best resolution is simply to revise the documentation after the implementation has changed. The documented f<appId>/<app-alias>/ model is operationally stronger: it preserves the immutable application-ID boundary, contains the mutable alias beneath it, allows SQL and APEXlang source to coexist, and supports the standalone-export workaround described earlier.

Central design question

Why should selecting an APEXlang deployment payload also:

• reorganise the application source under src;
• stop following Oracle’s published f<appId>/<app-alias>/ structure;
• override the export types requested through export.apex.exptype;
• remove the easy switch between SQL and APEXlang deployment;
• replace the stable application-ID root with a mutable application alias;
• rewrite the application’s Git history as files move between incompatible layouts;
• remove a practical standalone-export workaround that I built around the documented structure; and
• make APEXlang re-export conditional on SQLcl’s interpretation of git status?

These are separate consequences, and each deserves a clear technical justification. I understand now that most of them are intentional. I still do not understand what benefit requires any of them merely to choose the payload placed in dist.

The Git requirement deserves particular scrutiny because it is specific to APEXlang mode. project export is synchronising application state from the database into a known filesystem target. Whether the current files have been committed, stashed, copied elsewhere, or intentionally discarded is a source-control decision for the user and the surrounding workflow—not a prerequisite the exporter should silently impose.

Protecting users from accidental loss is a reasonable goal, but the usual interface is an explicit choice: refuse by default if necessary, then provide a documented force option for a deliberate replacement. Standalone apex export already follows that model with -force. The APEXlang Project path instead made Git status part of the export operation, offered no equivalent override in this test, and then blocked the export even when Git itself reported a clean working tree. That is not only a false-positive bug; the underlying coupling between database export and Git policy also needs justification.

What did we gain, and what did we lose?

This is not a symmetrical pros-and-cons comparison. The gains are real, intentional improvements that I welcome. The losses interact with one another: a source-layout change removes a workaround, creates Git churn, complicates migration, and makes switching deployment formats harder. Listing them separately makes that distinction clearer.

What we gained

• Native APEXlang deployment. SQLcl Project can stage an APEX application as APEXlang and deploy it through apex import. This is a useful option, not a feature I want removed.
• Correct deletion propagation in the baseline-and-delta test. After page 100 and a static file were deleted in APEX Builder, project export removed them from src, and project stage removed them from dist. That is exactly how a database-to-source-to-deployment workflow should behave.
• The binary/static-file corruption fix. SQLcl 26.2.2 no longer corrupted the exported image tested in this workflow. That was a serious 26.1 defect, and fixing it is important.
• Stable generated hashes. Repeating project stage against unchanged APEXlang source produced the same sqlcl_checksum and sqlcl_apexlang_payload_hash values.
• A potentially faster deployment path. My separate performance tests show that APEXlang deployment can be faster in some circumstances, while SQL deployment can be faster in others. Having both choices is valuable; the detailed comparison belongs in another article.
• Safer non-APEX changesets. SQLcl 26.2 also splits multiple DDL operations from one source file into separate changesets. This is not part of the APEX directory problem, but it is a substantial improvement and one reason I would like to adopt this release.

These are worthwhile changes. The problem is not the existence of APEXlang deployment. The problem is how that deployment choice has been coupled to source storage, export configuration, and migration behaviour.

What we lost

• The documented, stable source structure. The useful f<appId>/<app-alias>/ boundary is replaced by one layout in readable mode and another in APEXlang mode.
• The working 26.1 export workaround. My prj_exp_app alias was my own solution, not an Oracle-documented procedure. It could retain fNNN.sql and replace the defective APEXlang subdirectory with a forced standalone export because the documented structure provided a safe application boundary. Neither 26.2 layout supports that workflow cleanly.
• The work already built around the documented contract. Export aliases, cleanup logic, validation paths, Git review practices, and deployment automation all depended on the published structure. Adopting 26.2 would require that work to be redesigned without a corresponding source-management benefit.
• An inexpensive deployment switch. Choosing SQL or APEXlang deployment now changes the source-of-truth model and reorganises src. A deployment-format decision therefore becomes a repository migration.
• A stable application identity at the directory boundary. The application ID no longer contains the APEXlang-mode source. A mutable alias becomes the root, and changing it can leave multiple application directories behind.
• Continuous Git history. Moving the same application between f<appId>/<app-alias>/, flattened f<appId>/, and alias-root layouts appears as large-scale deletions and additions. Meaningful application changes become harder to review among the migration noise.
• An export operation independent of Git policy. Enabling APEXlang deployment also made re-export conditional on SQLcl’s Git check. The guard blocked the operation even when git status reported a clean working tree, provided no documented force override, and left manual target removal as the reliable escape.
• Control over requested export types. apex.apexlang=true overrides export.apex.exptype instead of allowing the requested application-source representations to coexist.
• A straightforward upgrade path. Existing src and dist content must be cleaned or migrated, generated controllers may require manual removal, and staging can retain both old and new deployment paths.

The largest loss is not one directory level. It is the ability to keep a stable source model, repair known export defects, and choose the deployment mechanism independently.

Additional regressions and migration friction

Several problems discovered during this test are not benefits or necessary costs of APEXlang deployment. They are additional regressions or unexplained migration behaviour:

• A targeted project export -o apex.106 attempted to export ALL_USERS and produced multiple ORA-31603 errors until I added an exclusion to project.filters.
• The APEXlang export guard reported tracked or untracked changes when the Git working tree was clean.
• Switching to APEXlang mode left both f106/f106.xml and demo1/demo1.xml active in the top-level deployment changelog.
• Staging removed the existing workspace, schema, alias, and application-ID values from dist/env/default.properties.
• Staging initially refused to replace the SQLcl 26.1-generated f106.xml controller and required me to remove it manually.
• project config -list did not expose apex.apexlang or its default until I already knew the parameter name and explicitly set it.

Those issues make an already structural migration more difficult to understand and automate. More importantly, they obscure the genuinely useful improvements that SQLcl 26.2 delivers.

What I want from SQLcl Project

I do not want SQLcl Project to abandon APEXlang deployment. I want the new deployment option without coupling it to a second source model, a repository migration, or unrelated changes to export and staging behaviour.

APEXlang source and deployment

1. Use the documented source structure whenever APEXlang source is requested. Whether apex.apexlang is true, false, or absent should not change where requested application source is stored:

   src/database/<schema>/apex_apps/f<appId>/
   |-- f<appId>.sql       # when APPLICATION_SOURCE is requested
   `-- <app-alias>/
       |-- .apex/
       |-- deployments/
       |-- pages/
       |-- shared-components/
       |-- application.apx
       `-- page-groups.apx
   

   The application ID remains the stable boundary, and the mutable alias remains beneath it. The source representations written inside that boundary should be controlled by export.apex.exptype, not by the deployment setting.

   Of course, this does not mean that every project must store APEXlang source. If the user selects SQL deployment with apex.apexlang=false and does not request APEXlang through the export configuration, SQLcl should write only the requested SQL source. No APEXlang request should mean no APEXlang files. The important requirement is that, when APEXlang source is requested, it uses the documented location rather than a layout selected implicitly by the deployment mode.

2. Replace the complete application root during database export by default. When exporting application 106, SQLcl Project should normally remove everything below apex_apps/f106/ and recreate that root from the current database state. It should regenerate every requested representation, including f106.sql and the APEXlang alias directory. This removes deleted pages, deleted static files, renamed components, and obsolete alias directories in one deterministic operation.

   Oracle may also provide an explicit guarded option that exports only when the target is empty, committed, or otherwise considered safe. That can be useful for teams that want the additional protection, but it should be an opt-in policy. Complete replacement should remain the default behaviour for a database export.

3. Preserve filename and directory case. SQLcl Project should write the filenames and directory names returned by the APEX API, including APEX_EXPORT.GET_APPLICATION, without converting them to lowercase or otherwise normalising their case.

4. Leave Git policy to the user. The default database export should not depend on whether SQLcl believes the target contains committed, uncommitted, tracked, or untracked files. Replacing the application root is the requested operation. An optional guarded mode may inspect Git when the user explicitly selects it, but it should be documented and accompanied by a force option equivalent to standalone apex export -force.

5. Make apex.apexlang control deployment only. The setting should decide how project stage packages and deploys the application. It should not reorganise src, override export.apex.exptype, or require a new Git history.

6. Keep one stable deployment structure. The application should remain below its f<appId> boundary in dist, regardless of the selected deployment mechanism:

   dist/releases/apex/f<appId>/
   |-- f<appId>.xml
   |-- f<appId>.sql       # payload when SQL deployment is selected
   `-- <app-alias>/       # payload when APEXlang deployment is selected
   

   The top-level APEX changelog should continue to include only f<appId>/f<appId>.xml. In SQL mode, that controller runs the generated SQL payload. In APEXlang mode, the same controller path runs apex import against the alias directory.

7. Make switching deployment modes routine. Changing apex.apexlang should regenerate f<appId>.xml and its selected payload beneath the same dist/releases/apex/f<appId>/ root. SQLcl should remove the payload no longer used, replace its own generated controller, and leave src untouched. Moving from SQL to APEXlang deployment—or back again—should not require a repository migration.

This retains the useful new APEXlang deployment path while separating three concerns that should remain independent: what is exported into src, how application source is organised, and which payload is generated into dist.

Other SQLcl Project fixes

1. Do not export ALL_USERS unless it is explicitly requested. A targeted project export -o apex.106 should export application 106. Users should not need a project.filters exclusion merely to prevent an application export from attempting every database user.

2. Leave existing environment properties alone. project stage should not remove workspace, schema, alias, application-ID, or user-defined values from dist/env/default.properties. Those files are part of the environment-specific deployment contract and may intentionally contain values used by generated controllers or custom changesets.

3. Make Project configuration discoverable. project config -list should show every supported, non-hidden user setting—not only settings already written to project.config.json. For each setting, it should show the effective value, the documented default or that no default exists, and whether the value is explicitly configured. A user should not need to know that apex.apexlang exists before asking SQLcl to list the available settings.

4. Regenerate SQLcl-generated files without manual cleanup. A new SQLcl version should be able to replace controllers and payloads generated by an older version. If SQLcl cannot safely distinguish a generated file from a user-maintained file, it should provide a clear, documented override instead of requiring users to discover and remove controllers manually.

5. Keep the deployment changelog internally consistent. When a project changes deployment modes, staging should remove the obsolete controller and its payload. It must not warn that SQL and APEXlang content cannot coexist while leaving both controllers active in the changelog.

I think these changes would make SQLcl Project easier to understand, automate, and adopt for everyone. They preserve the improvements in SQLcl 26.2 while restoring a stable contract for existing users.

I deeply appreciate the work the SQLcl team has put into APEXlang support, the binary-export fix, component cleanup, and safer changeset generation. I hope the team hears this feedback in that spirit: keep the valuable new deployment capability, but make it fit the documented source structure and the predictable Project workflow users already depend on.

Conclusion

SQLcl 26.2 is not a release I want to reject. Fixing the binary/static-file corruption during APEXlang export is important and appreciated. Splitting multi-operation DDL into separate changesets is also a substantial improvement to deployment safety, and choosing between SQL and APEXlang application deployment is genuinely useful. My testing suggests that either deployment mechanism can be faster depending on the application and circumstances, which makes an inexpensive switch between them even more valuable.

The blocker is the coupling between deployment format and source layout. Other APEXlang export bugs remain, but the documented 26.1 directory structure made them manageable through my prj_exp_app SQLcl alias. That workaround retained project export to generate fNNN.sql, then used a forced standalone apex export to replace the defective APEXlang source with a clean, current tree. The two 26.2 structures remove the stable, application-ID-scoped path on which that workaround depends.

Neil Fernandez’s forum explanation is useful, but I am surprised that its central distinctions are absent from the published documentation: readable/ in legacy mode, the alias as the APEXlang source root, apex.apexlang overriding export.apex.exptype, and the prohibition on mixed output. The current documentation explicitly specifies f<appId>/<app-alias>/ and automatic cleanup. A forum clarification should not supersede that public contract. My preferred resolution is for SQLcl Project to follow the documented structure, not merely to update the documentation after users have already built workflows around it.

For now, I am keeping this project on SQLcl 26.1. I would like Oracle to restore the documented, stable application-ID boundary, preserve the requested source exports, and let apex.apexlang do one clear job: choose how the application is packaged and deployed. If other SQLcl Project users depend on the same workflow, now is the time to test 26.2.2, compare the generated trees, and add their experience to the discussion.

Sources

• Oracle Forums: SQLcl 26.2.2 Project export APEXlang structure is inconsistent
• Oracle SQLcl 26.2 documentation: APEXlang Project Structure
• Oracle SQLcl changelog
• Oracle APEX documentation: Using SQLcl with APEXlang
• Oracle Forums: SQLcl Project export lowercases APEXlang file and folder names
• Oracle Forums: SQLcl Project export should remove stale APEX alias folders
• SQLcl Project Aliases: A Practical Toolkit for Daily Development

• Teams already using SQLcl Project for Oracle APEX applications and preparing to upgrade APEX and SQLcl to 26.1. This is the primary audience.
• Teams considering a move to SQLcl Project while upgrading to APEX 26.1. The article shows the practical challenges that such a combined move may present.
• Teams using APEX without SQLcl Project. The APEX compatibility constraint, environment architecture, severe APEX failure, application validation, regression testing, and cutover sections still apply. You can skip the SQLcl Project-specific export, staging, and release mechanics.

TL;DR

• This is not an academic article or a white paper. It is based on a real client-facing upgrade completed in July 2026.
• Many teams oversimplify an APEX upgrade by starting with DEV. That is safe only when development, fixes, and promotions can stop completely until every environment has been upgraded; otherwise, the team may lose its normal path for delivering application fixes to the older production environment.
• This post concentrates on the architecture of a live upgrade and summarises the challenges we encountered. In addition to the expected and documented post-upgrade application work, we encountered one severe APEX issue, almost a dozen SQLcl Project issues, and one regression affecting our own code. We resolved or worked around all of them and completed the upgrade; none was a roadblock, although some took considerable time and the APEX issue required Oracle’s help to diagnose. I plan to cover individual problems and lessons from this upgrade in more detail in future posts.
• This entire article is itself the TL;DR for a much larger, comprehensive guide. If you are actively planning an upgrade rather than casually exploring the subject, stop reading here and use the complete APEX 26.1 and SQLcl 26.1 upgrade guide.

Table of Contents

• TL;DR
• Table of Contents
• The constraint that defines the architecture
• Can you stop the universe?
  • The complete-freeze model
  • The active-development model
• The three additional upgrade components
• The complete upgrade workflow
  • Phase 1: Prepare three parallel upgrade components
  • Phase 2: Establish and prove the deployable 26.1 baseline
  • Phase 3: Test deeply while production development continues
  • Phase 4: Cut over
  • Phase 5: Clean up
• What a resettable validation environment actually means
• What the real upgrade exposed
  • A severe APEXlang export failure requiring Oracle’s help
  • SQLcl Project 26.1 required substantial workarounds
  • Moving to APEXlang involves legitimate migration work
  • Functional regression testing remains mandatory
• Keeping production releases moving
  • Database object and PL/SQL changes are normally mechanical
  • APEX application changes require a deliberate merge
• Why production is upgraded before development
• Acknowledgements
• Conclusion
• Sources

The constraint that defines the architecture

The most important fact in this upgrade is not a new APEX feature or SQLcl command. It is the direction in which APEX applications can move:

There is no compatibility switch that converts a 26.1 application export into a 24.2 deployment artifact. Once an application is edited and exported from APEX 26.1, that export cannot be used to correct a production environment that is still running APEX 24.2.

This makes the order of environment upgrades an application-delivery decision, not merely an infrastructure preference. If DEV is upgraded first, developers can quickly lose the ordinary path for creating and promoting a production fix. Directly editing PROD, manually reconstructing a change on the old version, or maintaining ad hoc application copies are not acceptable substitutes for a controlled delivery process.

The safe architecture must temporarily preserve two capabilities at the same time:

• a current APEX line that can still deliver applications to the existing production environment; and
• an APEX 26.1 line where the applications, generated source, deployment history, and platform compatibility can be tested.

Everything else in this workflow follows from that requirement.

Can you stop the universe?

There are two valid ways to organise the upgrade. The right choice depends on whether the organisation can genuinely stop application delivery.

The complete-freeze model

Upgrading DEV first can work when the team can enforce a complete gate:

• everything intended for PROD has already been delivered;
• no new feature development begins;
• no production fix needs to pass through the current APEX line; and
• all work can wait until PROD, TEST, and DEV have been upgraded.

In that situation, DEV can become the upgrade environment. The workflow still requires application validation, functional regression testing, and a clean deployment test, but the team does not need to reconcile concurrent production releases into a parallel upgrade line.

The important word is complete. A nominal freeze with an exception for urgent production defects is not a complete freeze. The first urgent defect recreates the need for the older development environment… unless, of course, you want to take the risky route and develop and apply the fix directly in PROD.

The active-development model

Most application teams do not have the luxury of stopping every feature, fix, promotion, and production responsibility for the duration of a major upgrade. Baseline preparation and regression testing may take days or weeks, and production continues to change during that period.

For those teams, the current DEV/TEST/PROD path must remain available while a separate environment is upgraded and tested. Every release that reaches PROD during the upgrade must later be incorporated into the 26.1 line without losing either the production feature or the corrections already made for APEX 26.1.

That is the more demanding case covered here.

The three additional upgrade components

The active-development model adds three components to the normal environment chain:

The production-like clone and the validation environment are not interchangeable.

The clone should contain application and database metadata that is as close to PROD as practical. It is the place to discover that a page no longer opens, a plug-in is incompatible, a packaged application fails, or a business process behaves differently after the APEX upgrade. Production data is not required and may need to be removed or sanitised, but metadata fidelity matters.

The resettable environment answers a different question: can the reviewed project recreate the accepted state from a known starting point? A clone that works after an in-place upgrade does not prove that the SQLcl Project source, generated APEX exports, checksums, staged releases, and historical Liquibase changesets are complete.

The Git worktree keeps the filesystem side equally explicit. The ordinary project directory can remain on the SQLcl version used for current production delivery, while the upgrade directory selects SQLcl 26.1. A directory-aware SQLcl selector makes the version follow the folder automatically; the implementation used for this project is described in SQLcl Version Switching by Directory.

The complete upgrade workflow

The following diagram is the centre of the workflow. It shows the mandatory path, the optional drift-detection path, the application-repair loop, the deployment-validation loop, the production-release reconciliation loop, and the production-first cutover.

The complete APEX 26.1 and SQLcl 26.1 project-upgrade workflow. Click the diagram to open the full-sized version.

The five phases below deliberately match the diagram. Commands, diagnostics, detailed release manipulation, and screenshots are available in the complete guide.

Phase 1: Prepare three parallel upgrade components

Create the production-like clone, the resettable validation environment, and the SQLcl 26.1 worktree while keeping the current DEV/TEST/PROD line available.

The clone is upgraded to APEX and ORDS 26.1. The validation environment is prepared with a documented restore point. The worktree starts from the stable production branch and records the SQLcl 26.1 project representation separately from normal development.

This phase also establishes the operating rule for the rest of the upgrade: ordinary releases continue to reach PROD through the current line first. Only then are they carried forward into the upgrade line.

Phase 2: Establish and prove the deployable 26.1 baseline

Oracle’s SQLcl Project upgrade guidance starts with a dedicated branch, a new configured SQLcl version, deletion of generated database source, and a new export. Dan McGhan’s companion article explains the same tool-version upgrade pattern and the advantage of starting during a quiet period.

A combined APEX, SQLcl Project, and APEXlang upgrade has additional work to do. The objective is not merely a refreshed src folder. It is a reviewed 26.1 baseline that contains valid application exports and checksums and can be installed successfully from the project’s complete deployment history.

At a high level, this phase:

1. regenerates database-object source with SQLcl 26.1;
2. optionally uses the production-like export to detect meaningful production drift;
3. exports every APEX application separately;
4. validates, corrects, imports, and re-exports every APEXlang application;
5. stages and reviews the baseline deployment entries;
6. resets the validation environment and installs the complete project; and
7. repeats the correction, export, staging, reset, and deployment loop until the installation succeeds.

Only then is the state declared the Baseline milestone. The exact proven commit is recorded, and its changesets are synchronised to PROD with Liquibase changelog-sync. Synchronisation tells PROD that these baseline changesets describe state already present there; it does not reinstall the baseline applications or database objects.

This separation is critical. Corrections discovered after the baseline remains pending and will be applied during cutover. Moving synchronisation to the end would blur the difference between state that already exists in PROD and genuine 26.1 upgrade corrections.

Phase 3: Test deeply while production development continues

Structural validation and clean deployment do not prove business behaviour. Run the project’s real functional regression plan against the production-like 26.1 clone, with particular attention to session state, JavaScript, plug-ins, packaged applications, authentication, integrations, and business processes.

Every regression follows the same loop: understand it in the clone, correct it, validate it, refresh the generated deployment artifacts, deploy again to the resettable environment, and repeat the functional test.

Meanwhile, production development may continue. Every release that reaches PROD must also be reconciled into the clone and upgrade branch using its original release history. The reconciliation path depends on what the release changed:

• Database objects and PL/SQL are normally straightforward. We do not independently develop PL/SQL in the upgrade branch. The database change reaches PROD through the current line, the exact same release is installed into the clone, its stable Liquibase history is carried into the upgrade branch, and the related source is refreshed with SQLcl 26.1. This is primarily release-history bookkeeping, not a second semantic code merge.
• APEX applications require a deliberate merge. The current production line may add a feature to an application while the upgrade line has already added APEXlang corrections, post-upgrade metadata changes, and regression fixes to that same application. Preserve the 26.1-corrected application as a Working Copy, install the production release into the clone, and merge the upgrade corrections back into the updated main application.

There is no trustworthy one-click merge for two independently changed APEX applications. Working Copies and APEXlang source comparisons make the differences visible, but a developer must still decide which components belong in the consolidated result. The detailed approach is covered in Merging APEX Working Copies with APEXlang.

The two paths are described separately below under Database object and PL/SQL changes are normally mechanical and APEX application changes require a deliberate merge.

Testing is complete only when:

• the agreed functional suite passes;
• all post-baseline corrections are represented in source and deployment history;
• every release already delivered to PROD is present under its original identity;
• consolidated APEX applications contain both business changes and 26.1 corrections; and
• the complete project still installs successfully in the validation environment.

The result is a cutover candidate: the synchronised baseline plus the genuine post-baseline corrections that remain pending.

Phase 4: Cut over

Upgrade PROD to APEX and ORDS 26.1 first, then inspect the complete Liquibase status before deploying the project. Every pending changeset must be recognised and expected.

PROD should skip the baseline entries recorded through changelog-sync and the current-line releases it has already executed under their original identities. It should apply only the genuine post-baseline upgrade corrections. If baseline applications, carried-forward releases, representation-only drift, or unexpected objects appear as pending, stop and investigate.

Until the normal DEV and TEST environments are upgraded, the clone can serve briefly as emergency DEV. This is a short transition state, not a permanent environment design.

Upgrade DEV and TEST promptly and refresh every development application to the accepted 26.1 state. Normal feature work should resume only when the complete promotion path is again on one APEX and SQLcl Project generation.

Phase 5: Clean up

Once all environments run the new stack and the final upgrade branch has been reviewed and merged:

• decommission the production-like clone according to the team’s retention and data-handling rules;
• remove the Git worktree with git worktree remove, rather than simply deleting its directory;
• remove the merged upgrade branch if repository policy permits; and
• retain the resettable validation environment if it remains useful for deployment testing.

The resettable environment is often the component worth keeping. A facility created for the upgrade can become permanent evidence that the project remains deployable.

What a resettable validation environment actually means

The validation environment must return reliably to a documented starting point. That starting point depends on the installer model; it does not have to mean an empty database.

With a privileged nothing-to-everything installer, the environment may be restored to a backbone installation containing the database platform and deployment user. The project installer can then create application schemas, grant privileges, create the APEX workspace, and deploy the complete application estate.

With a schema-owner installer, the restore point must already contain whatever the project cannot create: application users, workspaces, infrastructure privileges, or other required platform configuration. The project is then deployed from that prepared state.

The invariant is:

Restore to a known starting point and prove that the complete project deployment can reproduce the intended state from there.

In the diagram, deploy from zero should be read as deployment from that selected restore point. The clean installation is evidence of reproducibility, not a binary judgement that every project must create its own schemas and workspace.

What the real upgrade exposed

The architecture was not designed around hypothetical risks. A real production upgrade exercised every part of it: one severe APEX failure, numerous SQLcl Project 26.1 bugs and shortcomings, legitimate APEXlang migration work, and runtime regressions that neither export nor validation could reveal.

A severe APEXlang export failure requiring Oracle’s help

One application exposed a severe failure in the APEX 26.1 export tooling. The traditional SQL-format application export still worked, but APEXlang generation failed. That distinction matters: adopting APEXlang was one of the main objectives of moving the project to SQLcl 26.1, so falling back permanently to the old SQL export was not an acceptable resolution.

The first failure came from the normal SQLcl Project application-export task:

project export -o APEX.1968

The task failed while exporting the application as APEXlang. To determine whether the failure came from SQLcl Project orchestration or the underlying APEX export, we then tried the direct APEXlang export command:

apex export -api 1968 -exptype APEXLANG

It failed with the same underlying error:

Exporting Workspace **** - application ***:******
ORA-01403: no data found
ORA-06512: at "APEX_260100.WWV_FLOW_EXPORT_INT", line 2691
ORA-06512: at "APEX_260100.WWV_META_META_DATA", line 5240
ORA-06512: at "APEX_260100.WWV_META_META_DATA", line 2179
ORA-06512: at "APEX_260100.WWV_META_META_DATA", line 4505
ORA-06512: at "APEX_260100.WWV_META_META_DATA", line 5187
ORA-06512: at "APEX_260100.WWV_FLOW_EXPORT_INT", line 2634
ORA-06512: at "APEX_260100.WWV_FLOW_EXPORT_INT", line 2825
ORA-06512: at "APEX_260100.WWV_FLOW_EXPORT_API", line 110
ORA-06512: at line 3

That was all the diagnostic information we had. The error did not identify an application page, component, plug-in, or property. Both the SQLcl Project task and the direct APEXlang export reached the same failure, and we had no practical indication of what inside the application caused it.

At that point, we asked Oracle for help in the APEX 26.1 application export forum thread. Steve Muench supplied a diagnostic query. It identified two Dynamic Actions on page 13 that referenced a plug-in which had previously been deleted.

The diagnosis led to a second problem: page 13 could not be opened normally in App Builder on the upgraded APEX 26.1 clone. The export error had not told us what to fix, and once Oracle’s query identified the page, the upgraded environment did not provide a supported graphical route for fixing it.

The same page still opened on the APEX 24.2 line. There, App Builder visibly marked the plug-in references as invalid. The orphaned components were behind a Build Option, so the application had continued to run and the inconsistent metadata had remained hidden until the APEXlang export was attempted on 26.1.

This combination is why I consider the issue severe. If the export error had identified the offending components, or if page 13 had opened normally on APEX 26.1 so we could repair them, this would have been a minor upgrade correction. Instead, the export produced an uninformative stack trace, Oracle’s help was required to discover the cause, and the problem could not be corrected in the upgraded environment alone.

The repair had to start on the still-available APEX 24.2 line:

1. remove or correct the invalid components in 24.2 DEV;
2. promote the application normally through TEST and PROD;
3. import the corrected production application into the 26.1 clone; and
4. retry the 26.1 export.

Fixing only the clone would also have left the production lineage inconsistent. The correction belonged in 24.2 DEV and had to move through the normal delivery path before the clone was refreshed. More importantly, upgrading DEV first would have removed the environment in which the page could still be opened and repaired. This was a direct demonstration of why the current APEX line must remain available during a busy upgrade.

SQLcl Project 26.1 required substantial workarounds

Moving the project to the SQLcl 26.1 build used for this upgrade exposed a long list of bugs, issues, and representation changes. I want to state clearly that I remain a strong supporter of SQLcl Project. Despite these problems, it is still the best tool currently available for the source-control and deployment workflow I need.

None of the issues below was critical, and none blocked the upgrade. We successfully worked around or mitigated all of them. The purpose of this list is to give other teams a complete picture of what they may encounter and help them recognise the symptoms quickly instead of rediscovering each workaround.

Review both source and staged releases. A successful project export or project stage is not proof that the resulting deployment is correct. Separate semantic changes from serialization noise, test binary files, inspect ORDS and grants, and confirm that a targeted export really refreshed every related object. Then prove the result by deploying it from the validation environment’s known restore point.

Moving to APEXlang involves legitimate migration work

Not everything discovered during the upgrade was a product bug. Adopting APEXlang across a real application estate required normal conversion and validation work that had to be planned and performed.

Every exported application—not merely the applications that appeared to have changed—was run through apex validate. A clean validation result was a required part of establishing the baseline.

The validation experience was mixed. Sometimes the compiler gave us a precise file, line, column, error type, and offending text. Sometimes validation succeeded but still produced warnings worth correcting. In the least helpful cases, malformed source caused a Java exception instead of a normal compiler diagnostic.

The original correction work was not captured as terminal screenshots. The following examples were reproduced afterwards with the same application source and commands, and they demonstrate the three kinds of result encountered during the upgrade. Each example used:

prj_validate 100

1. Validation succeeds with actionable warnings.

Output should look something like this:

Validating APEXlang app 100 from src/database/cla_apex/apex_apps/f100/opus -ws CLA_INTERNAL ...
APEXLang Compile Warnings:
File: application.apx
Line: 73
Column: 8
Type: PROPERTY_DEPRECATED
Warning: Property appBuilderIconName is deprecated.

File: pages/p10041-page-help.apx
Line: 3
Column: 4
Type: FILENAME_MISMATCH
Warning: Page alias in the file does not match that in the filename

Validation successful.

The application validated, but the deprecated property and filename mismatch still deserved review. A generic “validation successful” check that hid the warnings would have missed useful migration work.

2. Validation returns a precise compiler error.

Output should look something like this:

Validating APEXlang app 100 from src/database/cla_apex/apex_apps/f100/opus -ws CLA_INTERNAL ...
APEXLang Compile Errors:
File: shared-components/plugins/process/ucApexMessageServiceProcess/custom-attributes.apx
Line: 5
Column: 4
Type: SYNTAX
Error: token recognition error at: 'propr : s'

File: shared-components/plugins/process/ucApexMessageServiceProcess/custom-attributes.apx
Line: 5
Column: 16
Type: SYNTAX
Error: token recognition error at: 'erverUrl\n'

This was the good failure mode. The diagnostic identified exactly where to begin correcting the APEXlang source.

3. Validation terminates with a Java exception.

Output should look something like this:

Validating APEXlang app 100 from src/database/cla_apex/apex_apps/f100/opus -ws CLA_INTERNAL ...
2026-08-26 17:00:33.643 SEVERE oracle.dbtools.raptor.newscriptrunner.ScriptExecutor run java.base/java.lang.NumberFormatException.forInputString(Unknown Source)
java.lang.NumberFormatException: For input string: "null"
        at java.base/java.lang.NumberFormatException.forInputString(Unknown Source)
        at java.base/java.lang.Integer.parseInt(Unknown Source)
        at java.base/java.lang.Integer.parseInt(Unknown Source)
        at oracle.apexlang.core.ComponentPlugin.getAttributeValueFromComponent(ComponentPlugin.java:658)
        at oracle.apexlang.core.ComponentPlugin.createCustomAttributeFrom
        ...

This was harder to interpret because validation crashed instead of returning a compiler error. The stack still narrowed the problem to a value expected to be an integer, and editor diagnostics plus source inspection led us to the malformed property.

Validation was therefore not always easy or consistently informative, but it did not create a major delay. We found the root cause in every application, corrected the .apx source, and repeated validation until it succeeded. The validated application was then imported into the clone and exported one final time.

Please note: the final export and staging steps are mandatory in a SQLcl Project workflow. Correcting and validating the .apx files does not automatically update the application’s deployable artifacts. After validation succeeds, import the corrected APEXlang application into the clone, re-export the application so that its generated fNNN.sql file and checksum reflect the corrected state, and then run project stage to update the application entry in the staged release. SQLcl Project deploys the generated SQL application export; it does not deploy the edited .apx files directly. Stopping after APEXlang validation or import would therefore leave the deployable and staged SQL artifacts stale.

The Oracle APEXlang documentation explains the language and commands, while SQLcl Project with APEXlang: First Impressions covers the export, validation, import, and re-export cycle in more detail.

APEXlang made structural problems searchable and repeatable corrections much easier to review. It also made clear that moving a large application estate to a compiler-backed source format is a real migration activity, not merely a change of export option.

Functional regression testing remains mandatory

After every application exported, validated, imported, and deployed, functional testing still found problems.

The first involved controls backed by native Oracle Database BOOLEAN columns. On APEX 24.2, the checkboxes and switches worked even though their session-state data type remained at the default VARCHAR2. After the applications moved to APEX 26.1, the same controls still rendered, but they did not work for either Boolean value. APEX 26.1 allows the session-state data type to be set explicitly to BOOLEAN, and that setting became essential: without it, the controls could not operate correctly against the native Boolean columns. Correct source typing, Boolean session state, native Boolean defaults, filter metadata, and shared component settings were required before the controls worked again. The complete correction is documented in Native Boolean Columns in Oracle APEX 26.1 and APEXlang.

The second involved a packaged application. Flows for APEX 22.2 still worked under APEX 24.2 but failed in the APEX 26.1 clone. Upgrading Flows for APEX Community Edition to 25.1 restored operation. Because the newer package also worked on the current APEX line, it could be promoted through all environments before cutover rather than becoming a 26.1-only correction.

These examples are not a universal compatibility list. They are a warning against complacency.

An application that exports, validates, imports, deploys, and renders may still be functionally wrong. Test data entry and persistence, session state, JavaScript, integrations, authentication, plug-ins, packaged applications, and the business workflows that matter. Third-party and community applications deserve the same attention as code developed by your own team.

Keeping production releases moving

Regression testing can take long enough for several ordinary releases or urgent fixes to reach PROD. Each one must join the upgrade candidate without changing the Liquibase history that PROD already recorded.

Database/PL/SQL changes and APEX application changes require fundamentally different reconciliation strategies. If a production release contains only database-object or PL/SQL changes, carrying it into the upgrade line is normally mechanical. If an APEX application changed, the current-line feature and the accumulated 26.1 corrections may have modified the same application, and there is no automatic merge that can be trusted without review.

The complete guide’s production-release reconciliation section provides the exact sequence. The architectural distinction is worth making explicit here.

Database object and PL/SQL changes are normally mechanical

The upgrade branch is not a second development line for database objects and PL/SQL. Those changes continue through the ordinary DEV/TEST/PROD path and reach PROD first. The same released change is then delivered to the clone using the current worktree and current SQLcl version.

Once that production release is merged into main, carry its exact release folder, paths, changeset identifiers, and content into the upgrade branch. Add its include to the upgrade branch’s changelog controller and refresh the related generated source with SQLcl 26.1. Do not stage a second representation of the same logical database change.

Because PROD and the clone have already executed the same stable Liquibase changesets, this is largely release-history bookkeeping rather than a semantic code merge. A new validation environment executes that history during clean installation, while PROD recognises the original changeset identities and skips them at cutover.

There is one SQLcl-specific caution: a targeted project export -o in SQLcl 26.1 can silently ignore synonyms. When synonyms are involved, or the complete related-object set is uncertain, run project export without the -o parameter. If the project’s normal filters would exclude required related objects, temporarily adjust .dbtools/filters/project.filters, run the export, and then restore the filters.

APEX application changes require a deliberate merge

APEX is different because most upgrade-specific work happens inside the applications: APEXlang corrections, post-upgrade metadata changes, and fixes discovered during regression testing. At the same time, the current production line may deliver a new feature or hot fix to the same application.

Before delivering that production release to the clone, create a Working Copy from the clone’s current APEX 26.1 application. The Working Copy preserves every upgrade correction accumulated so far. Then install the exact application release that reached PROD into the clone’s main application. The main application now contains the new production feature, while the Working Copy retains the 26.1 corrections that the installation overwrote.

Now compare the two and deliberately merge the required upgrade corrections from the Working Copy into the updated main application. Neither complete application is automatically authoritative:

• the main application contains the latest production feature; and
• the Working Copy contains the accumulated APEX 26.1 corrections.

There is no trustworthy one-click merge for these two independently changed APEX applications. A Working Copy comparison and an APEXlang source diff make the work manageable, but a developer must still review the affected components and decide what belongs in the consolidated application.

After the merge, export and review the consolidated application, validate its APEXlang, import it if source edits were required, perform the mandatory final re-export, and stage the resulting application deployment entry. Then deploy the project to the resettable validation environment and return to functional regression testing.

This APEX reconciliation loop—not the database/PL/SQL carry-forward—is the real price of allowing productive work to continue during the upgrade. It is also why starting during a relatively quiet period remains useful even when a complete freeze is impossible.

For a detailed Working Copy and APEXlang comparison workflow, see Merging APEX Working Copies with APEXlang.

Why production is upgraded before development

The cutover order often feels counterintuitive because teams are accustomed to upgrading DEV first. The forward-only application rule reverses that instinct.

Once PROD runs APEX 26.1, it can accept the tested 26.1 application exports and post-baseline corrections. Upgrading DEV first would create a period in which the primary development environment produces applications that the production platform cannot accept.

This does not mean testing a new version in PROD. The production-like clone and resettable environment have already carried the upgrade candidate through compatibility testing, source validation, deployment replay, functional regression, and release reconciliation. PROD is first only among the normal DEV/TEST/PROD line during the final cutover.

Based on this upgrade, a practical timeline looks like this:

1. Prepare the prerequisites. Provision and upgrade the production-like clone, prepare the resettable validation environment, and create the upgrade worktree. This preparation can take as long as required.
2. Build and prove the baseline. Once the prerequisites are ready, establish the deployable baseline in the clone and prove it through the validation environment. Preferably, concentrate this initial baseline work into the next one or two days.
3. Test and reconcile for as long as required. Run functional regression testing and incorporate every release that reaches PROD. This stage may take weeks or longer; do not shorten it to meet an arbitrary cutover date.
4. Upgrade PROD. Upgrade APEX and ORDS in production, inspect the pending changesets, and deploy the reviewed post-baseline corrections.
5. Upgrade DEV and TEST immediately afterwards. Preferably complete them in the same maintenance window as PROD, or as soon afterwards as operationally possible.

The first three stages can be deliberately long. The transition between stages 4 and 5 should be deliberately short. During that gap, the already-tested APEX 26.1 clone provides a trusted temporary development environment for production bug fixes and other emergency deployments. Limit work during this transition to fixes and emergencies; normal feature development should wait until DEV and TEST have joined PROD on the same APEX and SQLcl Project generation.

Acknowledgements

Thank you to my colleagues Fekrad El-Wendi and Plamen Mushkov. Fekrad did the excellent infrastructure work that made the clone and supporting upgrade environments possible. Plamen shared the APEX side of the upgrade work with me and helped us work through its application-level challenges.

Conclusion

The defining challenge of this upgrade was not installing APEX 26.1 or changing a SQLcl version number. It was preserving a valid production-delivery path while building and proving its replacement. The one-way movement of APEX application exports made that an architecture problem before it became a command-line problem.

The production-like clone, resettable validation environment, and SQLcl 26.1 worktree protected different capabilities. Together they allowed normal delivery to continue, exposed a severe APEX failure while it could still be repaired on 24.2, isolated numerous SQLcl Project issues, supported the APEXlang migration, and caught runtime regressions before cutover.

If your organisation can stop all work until every environment is upgraded, the workflow can be simplified. If it cannot, preserve the current line, build a parallel upgrade line, test applications rather than only artifacts, and require every production release to be reconciled before cutover.

This article has intentionally stayed at the architectural and lessons-learned level. For the exact commands, aliases, screenshots, diagnostic output, Liquibase baseline procedure, application merge sequence, and production checklist, continue with the complete APEX 26.1 and SQLcl 26.1 upgrade guide.

Sources

• APEX 26.1 and SQLcl 26.1 Upgrade Guide
• Complete APEX 26.1 and SQLcl 26.1 project-upgrade workflow diagram
• Oracle: Upgrading SQLcl When Using SQLcl Project
• Dan McGhan: Upgrading SQLcl When Using SQLcl Project
• Oracle APEXlang documentation
• Oracle Forums: APEX 26.1 application fails to export as APEXlang
• Oracle Forums: SQLcl corrupts APEX static files during export
• Oracle Forums: SQLcl Project export should remove stale APEXlang files
• Oracle Forums: SQLcl Project stage fails when analysing Supporting Objects
• Oracle Forums: SQLcl Project ORDS export should use the configured project schema
• realSQLclProject: SQLcl Project bugs and enhancement requests
• realSQLclProject: SQLcl Project with APEXlang — First Impressions
• Native Boolean Columns in Oracle APEX 26.1 and APEXlang
• Merging APEX Working Copies with APEXlang
• SQLcl Version Switching by Directory
• Fekrad El-Wendi on LinkedIn
• Plamen Mushkov on LinkedIn

TL;DR

• A PROMPT_COMMAND hook calls a function before every shell prompt, which means the SQLcl version on your PATH is recalculated automatically every time you change directory.
• The function matches a substring of $PWD and swaps PATH entries accordingly — no manual export needed, and the switch is immediate within the same terminal session.
• The same mechanism applies to any multi-project setup where different folders require different SQLcl releases.

The upgrade scenario

Suppose your project runs on SQLcl 26.1 and you need to test an upgrade to 26.2. A Git worktree gives you a separate working directory for the upgrade branch alongside the existing repository:

git worktree add -b upgrade-26.2 ../my-project-26.2

Output should look something like this:

Preparing worktree (new branch 'upgrade-26.2')
HEAD is now at 1a2b3c4 latest commit

You now have two directories in play:

• /c/repo/github/my-project — main branch, should use SQLcl 26.1
• /c/repo/github/my-project-26.2 — upgrade branch, should use SQLcl 26.2

Keeping the right binary on PATH as you switch between them is the problem the hook below solves.

The PROMPT_COMMAND hook

Add the following block to your ~/.bashrc:

# ============================================================================
# Project-specific SQL PATH management
# Automatically switch between sqlcl-26.2 (for upgrade folders) and sqlcl-26.1
# ============================================================================
update_sql_path() {
    # Set upgrade_sql to your new SQLcl version path, latest_sql to your current production version.
    local upgrade_sql="/c/Install/sqlcl-26.2/sqlcl/bin"
    local latest_sql="/c/Install/sqlcl-26.1/sqlcl/bin"

    # Remove both versions from PATH first (clean base)
    PATH=$(echo "$PATH" | sed -E "s|${upgrade_sql}:?||g" | sed -E "s|${latest_sql}:?||g")

    if [[ "$PWD" == */*demo* || "$PWD" == */*26.2* ]]; then
        # In the 26.2 upgrade worktree — use the upgrade SQLcl.
        export PATH="${upgrade_sql}:${PATH}"
    else
        # All other folders — use the production SQLcl.
        export PATH="${latest_sql}:${PATH}"
    fi
}

# Hook into prompt — fires before every prompt, so every cd triggers a PATH update.
PROMPT_COMMAND="update_sql_path${PROMPT_COMMAND:+;$PROMPT_COMMAND}"

# Run once at shell startup so the right version is active before any cd.
update_sql_path

How it works:

• PROMPT_COMMAND is a bash variable that holds a command (or semicolon-separated list of commands) executed before every prompt is drawn. Since bash draws a new prompt after every command, the function fires automatically after every cd.
• update_sql_path strips both SQLcl bin paths from PATH to produce a clean base, then prepends the correct one based on a glob match against $PWD.
• The patterns (*/*demo* and */*26.2*) match any directory whose full path contains demo or 26.2. Adapt these globs to your own directory names.
• The final standalone update_sql_path call ensures the right version is active when the shell first starts, before any navigation has occurred.

A full version of this hook, maintained for real project use, is available in the realSQLclProject repository.

Tip: To open ~/.bashrc directly in VS Code from any terminal, run code ~/.bashrc. After saving your changes, reload with source ~/.bashrc.

Testing it

After saving and running source ~/.bashrc, verify the hook in the upgrade directory:

source ~/.bashrc
pwd
sql -version

Output should look something like this:

$ source ~/.bashrc
$ pwd
/c/repo/tests/demo1
$ sql -version
SQLcl: Release 26.2.0.0 Production Build: 26.2.0.181.2110

From a different directory, the production version is active:

source ~/.bashrc
pwd
sql -version

Output should look something like this:

$ .  ~/.bashrc
$ pwd
/c/repo/github/akluev.github.io
$ sql -version
SQLcl: Release 26.1.2.0 Production Build: 26.1.2.132.1334

The switch happens within the same session

Because PROMPT_COMMAND fires before every prompt, no re-sourcing or new terminal is needed. The session below is uninterrupted — the only action between the two sql -version calls is a single cd:

$ pwd
/c/repo/tests/demo1
$ sql -version
SQLcl: Release 26.2.0.0 Production Build: 26.2.0.181.2110

$ cd ..
$ pwd
/c/repo/tests
$ sql -version
SQLcl: Release 26.1.2.0 Production Build: 26.1.2.132.1334

Stepping out of the matched directory reverts the PATH immediately. The developer never has to think about which version is active.

Conclusion

This is a low-cost, zero-dependency trick — a few lines in a file you already have. Once configured, the workstation transparently supports multiple SQLcl versions at the same time, which is particularly valuable during upgrades and for environments where different projects are pinned to different releases.

The key advantage over a static approach — manually exporting PATH or sourcing a project-specific file — is that the PATH recalculation is continuous. Within the same terminal session, moving between directories always brings the correct sql binary with you. There is no stale state and no risk of running the wrong version because you forgot to re-export after switching branches.

The glob patterns in update_sql_path are the only thing you need to adjust for a new project or a different upgrade version. Everything else is infrastructure that, once in place, disappears into the background.

Sources

• realSQLclProject: .bashrc with project-specific SQL PATH management

Table of Contents

• Table of Contents
• TL;DR
• Setting up the test project
  • Create a baseline
  • Adding a substitution changeset
  • Modify The properties file
  • First deployment: variables from the properties file
  • OS environment variables take precedence
• Real-world examples
  • Example 1: Pre-deployment environment check
  • Example 2: Environment-specific configuration with graceful skip
• Conclusion
• Sources

TL;DR

• Liquibase has supported ${VAR_NAME} substitution tokens in changeset SQL for years; SQLcl Project inherits this feature without any additional configuration.
• The feature is absent from the official SQLcl Project documentation — which explains why it regularly surfaces as forum questions and why many developers working with SQLcl Project do not know it is there.
• Values are resolved from two sources: a properties file passed to Liquibase at deploy time, or OS-level environment variables set on the deploying machine — both work independently and can be combined.
• Dan McGhan’s excellent post on stage.substituteSchemas explains how SQLcl 26.1 leverages this mechanism for schema-agnostic deployments; the core substitution feature itself has been available since the first SQLcl Project release (24.3 onward) and has many more use cases.
• Substitution is the cleanest way to make any changeset environment-aware — inject server names, API endpoints, schema names, or any environment-specific value without touching the changeset files.
• If a variable is missing at deploy time, Liquibase silently writes the literal placeholder (e.g. ${AMS_SERVER_FQDN}) into the database; a Liquibase precondition can catch this before it causes silent data corruption.
• This article walks through the feature end-to-end: a minimal test project that confirms the resolution order, followed by two real-world patterns — a pre-deployment variable check and an environment-specific changeset with graceful skip.

Setting up the test project

Let’s walk through the feature end-to-end with a minimal test project.

Create a baseline

For this demo I used a schema called DEMO1 — the same name you will see referenced throughout the rest of this post. The only database privileges required are CREATE SESSION and CREATE TABLE; Liquibase needs CREATE TABLE to create its changelog tracking table.

From inside SQLcl, run:

! git init
project init -name subst

Output should look something like this:

SQL> ! git init
Initialized empty Git repository in C:/repo/tests/subst/.git/

SQL> project init -name subst
PROJECT DETAILS
------------------------
Project name:    subst
Schema(s):
Directory:       C:\repo\tests\subst
Connection name:
Project root:     subst
Your project has been successfully created

SQLcl Project creates the standard structure and a .dbtools/project.config.json file. Open that file and set your schema name — for this walkthrough the schema is DEMO1:

{
  "project" : "subst",
  "sqlcl" : {
    "connectionName" : "",
    "autoConnect" : false,
    "version" : "26.1.2.0"
  },
  "schemas" : [ "DEMO1" ],
  ...
}

Commit the result. That is your main baseline.

Adding a substitution changeset

From inside SQLcl, check out a feature branch and add a custom changeset:

! git checkout -b test1
project stage add-custom -file-name subst.sql

Output should look something like this:

SQL> ! git checkout -b test1
Switched to a new branch 'test1'

SQL> project stage add-custom -file-name subst.sql
Process completed successfully

SQLcl Project creates the staged file at dist/releases/next/changes/test1/_custom/subst.sql. Open it and replace the placeholder content with a set of prompt commands that print substitution tokens, plus the runAlways:true attribute so every deployment reruns it:

-- liquibase formatted sql
-- changeset  SqlCl:1787320902732 stripComments:false logicalFilePath:_custom\subst.sql runAlways:true
-- sqlcl_snapshot dist\releases\next\changes\test1\_custom\subst.sql:null:null:custom

prompt "TEST1: ${TEST1}"
prompt "TEST2: ${TEST2}"
prompt "TEST3: ${TEST3}"
prompt "TEST4: ${TEST4}"

-- parameters
prompt "parameter.demo1: ${parameter.demo1}"
prompt "demo1: ${demo1}"

runAlways:true is essential for this test setup because we want to re-run the changeset every time we change a variable and verify the output. Beyond testing, this matters in production too: most changesets that read substitution variables should carry either runAlways:true or runOnChange:true. Configuration values, server endpoints, and schema names can change between deployments — a changeset that only runs once on first install will never pick up those changes.

Note: Use runAlways:true when the changeset must execute on every deployment regardless of content (for example, a DML that refreshes a configuration table). Use runOnChange:true when re-execution should be triggered only when the changeset file itself is modified. For substitution-variable-driven changesets, runOnChange:true is usually the right choice (see the real-world example below).

Modify The properties file

When you ran project stage, SQLcl Project created dist/env/default.properties. Initially it contains one line:

parameter.demo1=demo1

This is the schema mapping used by the stage.substituteSchemas feature Dan McGhan describes. For this walkthrough, add four more variables to it:

parameter.demo1=demo1

test1="TEST1 lowercase"
parameter.TEST2="parameter TEST2"
TEST3="TEST3"

This file is a standard Liquibase defaults file. If you open dist/install.sql you will see it passed directly to lb update via the -def flag:

lb update -log -changelog-file releases/main.changelog.xml \
  -search-path "." -def env/default.properties

That is the connection between the file and the deployment. Any variable defined in it is available to every changeset in the deployment as a ${VAR_NAME} token.

Note: Liquibase documentation mentions two alternative ways to specify the defaults file without the -def flag: the LIQUIBASE_DEFAULTS_FILE environment variable and a JVM system property. Neither works with the Liquibase runtime embedded in SQLcl. Always pass the file explicitly via -def as shown above.

First deployment: variables from the properties file

Connect to the schema and run prj_install — the alias from the SQLcl Project Aliases post. If you are not familiar with it, run alias details prj_install to see exactly what it does:

SQL> alias details prj_install
prj_install
-----------
cd dist
prompt Running Project Installer Script...
set define off
@install.sql
cd ..

It changes into the dist folder, runs install.sql, then returns to the project root.

Note: This is the recommended approach for environments you control directly — developer VMs, integration test databases, and similar. You do not need project gen-artifact and project deploy to deploy to your own VM. Those commands exist for producing formal, auditable release artifacts destined for production or shared environments managed by a DBA.

To run the first deployment:

SQL> conn -n demo_vm26
Connected.
SQL> prj_install
Running Project Installer Script...
Installing/updating schemas
--Starting Liquibase at 2026-08-21T10:12:47 ...
Running Changeset: _custom/subst.sql::1787320902732::SqlCl
TEST1: "TEST1 lowercase"
TEST2: "parameter TEST2"
TEST3: "TEST3"
TEST4: ${TEST4}
parameter.demo1: ${parameter.demo1}
demo1: demo1

Four things stand out in this output.

1. Variable names are case-insensitive. The properties file contains test1 in lowercase. The changeset references ${TEST1} in uppercase. Liquibase still matches them. This is different from OS environment variables on Linux and macOS, where TEST1 and test1 are distinct names.

2. The parameter. prefix is stripped before substitution. A line written as parameter.TEST2="parameter TEST2" is exposed as ${TEST2}, not as ${parameter.TEST2}. You can see this clearly: ${TEST2} resolves to "parameter TEST2", while ${parameter.demo1} is not resolved at all — it prints the literal placeholder. The usable name is always the part after parameter.. This prefix is documented in the SQLcl 26.1 User Reference (section 6.1.4) as part of the schema substitution mechanism: project stage generates entries like parameter.demo1=demo1 in dist/env/default.properties so that ${demo1} resolves to the target schema name. The stripping behaviour applies to any variable written with this prefix, but the prefix is intended for schema mappings — for your own substitution variables, write them without it.

3. The schema variable follows the same rule. The auto-generated line parameter.demo1=demo1 works identically: ${demo1} resolves to demo1; ${parameter.demo1} does not resolve.

4. Missing variables are silent. TEST4 was not defined anywhere. Liquibase does not raise an error — it writes the literal text ${TEST4} into the database exactly as written in the changeset. In a prompt command the consequence is cosmetic; in a DML changeset, the placeholder ends up stored in the table.

OS environment variables take precedence

Set TEST1 as an OS variable, exit SQLcl, and re-connect:

$ export TEST1="Test1 from OS"
$ sql -nolog
SQL> conn -n demo_vm26
Connected.
SQL> prj_install
Running Project Installer Script...
Running Changeset: _custom/subst.sql::1787320902732::SqlCl
TEST1: Test1 from OS
TEST2: "parameter TEST2"
TEST3: "TEST3"
TEST4: ${TEST4}
parameter.demo1: ${parameter.demo1}
demo1: demo1

TEST1 now shows Test1 from OS even though the properties file still contains test1="TEST1 lowercase". The OS environment variable wins. All other variables — defined only in the properties file — are unchanged.

This establishes the resolution order: OS environment variables override the properties file. The properties file acts as the default; the OS supplies environment-specific overrides without any file changes.

Real-world examples

Example 1: Pre-deployment environment check

The silent-failure behaviour from the test above becomes a real problem in production deployments. The standard remedy is a dedicated runAlways:true changeset placed at the very beginning of the deployment that explicitly checks every required variable and halts if anything is missing.

The key challenge is detecting an unresolved placeholder without triggering substitution in the check itself. Writing '${MY_VAR}' in a SQL comparison would cause Liquibase to substitute it before the query runs. The solution is to split the literal using concatenation so Liquibase never sees the token:

like '$'||'{%}'

A full pre-check changeset builds a collection of all required variable values, then loops through looking for any that still match the unresolved pattern:

-- liquibase formatted sql
-- changeset ADMIN:1733418388854 stripComments:false runAlways:true logicalFilePath:pre-install/_custom/pre-check-env.sql

declare
  -- List every required variable. If a variable is not needed in this
  -- environment, set it to 'NULL' or 'N/A' in the properties file rather
  -- than leaving it absent.
  l_env_variables apex_t_varchar2 := apex_t_varchar2(
    -- passwords
    q'`${APP_PASSWORD}`',
    q'`${APP_PASSWORD_CHANGED}`',
    -- host ACLs
    q'`${IDCS_HOST}`',
    q'`${OAC_HOST}`',
    -- OCI config
    q'`${OCI_VAULT_VALUE}`',
    q'`${OCI_REGION_VALUE}`',
    q'`${OCI_TENANCYID_VALUE}`',
    -- JIRA config
    q'`${JIRA_CREDENTIALS_SECRETNAME_VALUE}`',
    q'`${JIRA_LIST_ARRAY_VALUE}`',
    -- generic
    q'`${ENV_VALUE}`'
  );
  l_missing apex_t_varchar2 := apex_t_varchar2();
begin
  for i in l_env_variables.first .. l_env_variables.last loop
    if l_env_variables(i) like '$'||'{%}' then
      apex_string.push(l_missing,
        trim(translate(l_env_variables(i), '$'||'{}', '   ')));
    end if;
  end loop;
  if l_missing.count > 0 then
    raise_application_error(-20000,
      'The following environment variables must be set: '
      || apex_string.join(l_missing, ', '));
  end if;
end;
/

A few things worth noting:

• q'…' is Oracle’s alternative quoting mechanism. It lets variable values contain single quotes, dollar signs, or other special characters without breaking the string literal.
• translate(value, '$'||'{}', ' ') strips the $, {, and } characters to extract the bare variable name for the error message.
• runAlways:true ensures this check runs on every deployment, not just the first. A variable that was set last week may not be set today.
• Place this changeset in an early-release changelog so it executes before any DDL/DML changesets that will use variables. If it raises an error, Liquibase stops the deployment immediately.

Example 2: Environment-specific configuration with graceful skip

The second pattern handles a different situation: a changeset that should run in some environments and be silently skipped in others, and that should re-run automatically whenever the variable value changes.

The ams_config_dml.sql changeset below maintains metadata of a connection to AMS (APEX Messaging Service by United Codes) in a configuration table. It uses runOnChange:true combined with an onFail:CONTINUE precondition:

-- changeset SqlCl:1761249915279 stripComments:false logicalFilePath:dev-01\_custom\ams_config_dml.sql runOnChange:true
--preconditions onFail:CONTINUE
--precondition-sql-check expectedResult:0 SELECT count(*) FROM dual WHERE '${AMS_SERVER_FQDN}' ='$'||'{'||'AMS_SERVER_FQDN'||'}'

begin
  cla_apex.cla_configuration_pkg.upsert (
    p_instance_id => 1,
    p_key_type_id => 1,
    p_key         => 'ams_server',
    p_description => 'Local AMS server URL',
    p_value       => 'https://${AMS_SERVER_FQDN}',
    p_key_group   => 'ams'
  );
end;
/

begin
  cla_apex.cla_configuration_pkg.upsert (
    p_instance_id => 1,
    p_key_type_id => 1,
    p_key         => 'ams_api_key',
    p_description => 'Local AMS API Key',
    p_value       => '${AMS_API_KEY}',
    p_key_group   => 'ams'
  );
end;
/

commit
/

The three behaviours this produces:

Variable not set. Liquibase substitutes ${AMS_SERVER_FQDN} with nothing — the token remains as a literal. The precondition detects this (the string equals its own unresolved form), the count is 1, and onFail:CONTINUE skips the changeset. The deployment continues. No error, no corrupted data.

Variable set, value unchanged since last run. Because Liquibase performs substitution before computing the changeset checksum, the resolved changeset has the same checksum as last time. runOnChange:true does not trigger a re-run. The changeset is skipped efficiently.

Variable set, value has changed. The resolved SQL is different from last time, so the checksum differs. runOnChange:true detects the change and re-executes the changeset, upserting the new server address or API key into the configuration table.

In practice this deployment pattern lets the same changelog work cleanly across very different environments. In a controlled environment with containerised deployment, AMS_SERVER_FQDN and AMS_API_KEY are always provided by the container — the configuration table stays in sync automatically. When a value needs to change, a DBA updates it in the container configuration and the next deployment picks it up via runOnChange:true. Local development VMs or environments that do not use AMS simply leave the variables unset — the precondition catches that silently and moves on.

Conclusion

Substitution variables are one of the most practical tools available in a SQLcl Project deployment. They require no additional setup beyond what every project already has, yet they are absent from the official SQLcl Project documentation — which is exactly why they are so often overlooked.

The properties file is not a requirement. dist/env/default.properties is simply a Liquibase defaults file passed via the -def flag in install.sql. You can swap it for a different file per environment, calculate the path at deploy time, or remove the flag entirely and supply all values as OS environment variables. The simplest setup is no properties file at all — just set the variables on the machine before running the deployment.

Note: dist/env/default.properties does have one unique role: when stage.substituteSchemas=true, project stage writes schema mappings directly into this file and install.sql references it by this exact path. If you rename or replace the file for your own variables, schema substitution will still work as long as you keep the parameter.<schema>=<value> entries in whatever file you pass to -def. But the file that project stage generates and updates is always dist/env/default.properties.

A useful practical split:

• Non-sensitive configuration — server names, endpoints, feature flags, schema mappings — belongs in environment-specific properties files managed alongside the deployment.
• Secrets — passwords, API keys, tokens — should never be written to a file in the repository. Supply them as OS environment variables at runtime; they automatically override any value in the properties file.

Two caveats are worth keeping in mind:

Silent failure on a missing variable. If a variable is not defined, Liquibase does not raise an error — it writes the literal placeholder (e.g. ${MY_VAR}) into the database. This is counterintuitive and easy to miss. The pre-check changeset pattern from Example 1 is the standard remedy: it catches every unset variable before any DML runs.

The parameter. prefix. This prefix is documented in the SQLcl 26.1 User Reference (section 6.1.4) as part of the schema substitution mechanism. project stage generates entries like parameter.demo1=demo1 in dist/env/default.properties so that ${demo1} resolves to the target schema name at deploy time. Any variable written with this prefix undergoes the same stripping, but the prefix is reserved for schema mappings. For your own substitution variables, write them without the parameter. prefix — and never reference them as ${parameter.MY_VAR}, which will not resolve.

Sources

• realSQLclProject: Environment Variables — Common Commands and Directives
• Dan McGhan: Schema-agnostic Staged Changesets with stage.substituteSchemas
• Oracle SQLcl 26.1 User Reference: Section 6.1.4 — Support for Schema Substitution
• Liquibase Docs: defaults-file parameter
• United Codes: APEX Messaging Service (AMS)

• SQLcl Project exports, stages, and packages database changes.
• Liquibase tracks and deploys changesets.
• Git records, reviews, and merges the resulting files.

A productive workflow therefore requires a solid command of SQLcl and Git as well as SQLcl Project itself. The commands are powerful, but some of the most useful ones are long, require several arguments, or must be run from a particular directory. Re-entering them by hand creates friction and leaves room for mistakes.

SQLcl aliases are a simple way to turn those multi-step operations into short, consistent commands.

This article focuses on the aliases I use most often. For the broader command reference, including SQLcl Project, Liquibase, Git, SQLcl, and changeset directives, see my SQLcl Project command cheat sheet.

Why SQLcl aliases deserve more attention

An alias is not limited to replacing one command with a shorter name. It can contain SQL, PL/SQL, SQLcl commands, host commands, bind arguments, prompts, and a sequence of operations. In other words, it can capture a small, repeatable workflow behind one memorable command.

Oracle’s SQLcl User’s Guide documents aliases as shortcuts for SQL, PL/SQL, or SQL*Plus scripts. Jeff Smith has also demonstrated practical aliases with bind variables in his SQLcl examples.

Aliases become even more useful in agent-assisted development. In my setup, aliases loaded into the SQLcl environment can also be invoked through the SQLcl MCP server. An agent skill can describe when an alias is appropriate, while the alias itself provides the deterministic implementation. The agent does not need to reconstruct a long command line or remember repository-specific paths every time.

Load the alias collection

My aliases are stored in the realSQLclProject repository as scripts/xml/sqlcl-project-aliases.xml. Every public alias starts with prj_, which makes the collection easy to identify and reduces the chance of colliding with aliases already installed by a user.

You do not need to clone the complete repository. You can download the alias XML file directly, save it anywhere convenient, and load it from that location in SQLcl:

cd <download-directory>
alias load sqlcl-project-aliases.xml

If you clone realSQLclProject instead, start SQLcl in the repository root and load the version-controlled file in place:

alias load scripts/xml/sqlcl-project-aliases.xml

Then confirm that the aliases are available:

alias list

The command transcripts in this article retain their original environment and object names. Repetitive sections are explicitly marked as skipped, and database connection details are redacted.

SQL> alias list
lbs
prj_compile
prj_drift_cleanup
prj_exp_app
prj_force_apex
prj_install
prj_mr
prj_rm_logs
prj_rm_ords
prj_status
prj_sync
prj_validate
SQL>

The aliases fall naturally into three groups:

1. Workarounds for SQLcl Project behavior that needs additional handling.
2. Shortcuts for frequently used Project and Liquibase operations.
3. APEXlang validation and import commands.

Group 1: Workarounds and cleanup

prj_exp_app: a safer APEX application export

In my SQLcl 26.1.2 workflow, project export has two serious problems for APEX applications:

1. It does not clean the existing APEXlang source directory. Suppose an export contains page 8, and page 8 is later deleted in APEX. The next project export writes the current application files but leaves the obsolete page 8 file behind. The same problem applies to deleted or renamed components and static files. The directory is no longer a faithful representation of the application, and a later APEXlang import can process source that should have disappeared.
2. It corrupts binary files in the APEXlang export. In SQLcl 26.1.2, exported images, application icons, and attachments are consistently damaged by incorrect binary and CRLF handling in this path. These are not harmless textual differences: the files themselves cannot be trusted or used as a clean source-controlled export.

Until those issues are resolved in the version I use, I run prj_exp_app instead of calling the Project export command directly:

conn -name proj_dev
prj_exp_app 110

The alias accepts the application ID and first runs:

project export -o APEX.110

That first step remains necessary because SQLcl Project generates the fNNN.sql application script used later for staging and deployment. In this workaround, generating that deployment file is the reason to retain the project export step.

For SQLcl 26.1.2, the alias then runs a direct APEXlang export with the equivalent of:

apex export -applicationid 110 -exptype APEXLANG -dir <application-directory> -force

The alias derives the actual directory from apex_applications and uses the short -f form of -force. That option removes the existing export directory before recreating it. Deleted pages, renamed components, obsolete static files, and other stale source therefore disappear. The clean APEX export also replaces the binary files written by project export.

The resulting directory contains both things the workflow needs:

• the fNNN.sql deployment script generated by SQLcl Project; and
• a clean, current APEXlang source tree generated by apex export.

On other detected SQLcl versions, the alias keeps the Project export and validates the resulting APEXlang application instead of applying the 26.1.2 re-export workaround.

SQL> conn -n proj_dev
Connected.
SQL> prj_exp_app 100

APP_ID
--------------------------------
100

Exporting APEX Application ID 100..
*** APEX_APPLICATIONS ***
Exporting Workspace DEMO1 - application 100:DEMO_APP
-------------------------------
APEX_APPLICATION              1
-------------------------------
Exported 1 objects
Elapsed 46 sec

Bug in 26.1 -Rexported application 100 to src/database/cla_apex/apex_apps/f100
Exporting Workspace DEMO1 - application 100:DEMO_APP
File src\database\cla_apex\apex_apps\f100\demo_app\application.apx created

This is deliberately a version-aware workaround, not a claim that every SQLcl release behaves the same way. Review the alias before using it with a newer release and remove the workaround when it is no longer necessary. The binary-export problem and stale-directory behavior are documented in the Oracle Forum reports listed in the References section.

prj_rm_ords: remove false ORDS changes

In SQLcl Project 26.1, every project stage run regenerates files under dist/releases/ords/<schema>/, even when the ORDS metadata has not changed. In a minimal reproduction, the generated SQL stayed logically identical while its autogenerated Liquibase changeset ID changed. The result is a permanent Git diff that creates unnecessary merge conflicts, pollutes history, and makes a real ORDS change harder to notice. The behavior can occur even when the ORDS export type is disabled.

After I verify that the ORDS differences are spurious, I use:

prj_rm_ords

The alias runs git restore against dist/releases/ords in both the working tree and the Git index.

This safeguard matters: prj_rm_ords discards the staged and unstaged ORDS differences in that path. Always inspect the diff first. If the export contains a real ORDS change, do not run the alias.

SQL> project stage

Stage is Comparing:
Old Branch      refs/heads/main
New Branch      refs/heads/demo1

Stage processing completed, please review and commit your changes to repository

SQL> ! git status --short
 M dist/releases/next/changes/demo1/stage.changelog.xml
 M dist/releases/ords/cla_apex/ords.sql
 M dist/releases/ords/cla_public/ords.sql

SQL> prj_rm_ords
Removing fake changes in ORDS schema...

SQL> ! git status --short
 M dist/releases/next/changes/demo1/stage.changelog.xml

SQL>

The collection also includes prj_drift_cleanup, which runs the repository’s broader drift-cleanup script to remove ORDS noise, whitespace differences, and other export artifacts during drift analysis.

Group 2: Daily Project and Liquibase shortcuts

prj_install: deploy directly from the repository

SQLcl Project provides project gen-artifact and project deploy, and those commands are indispensable when producing a controlled artifact for a DBA, an artifact repository, or a production deployment process.

That is not always the fastest feedback loop for environments controlled by the development team. In a unit-test, integration, or other developer-managed environment, I usually want to deploy the latest repository state, inspect the log, correct a problem, and run the installation again.

For that workflow, prj_install is the command I use most:

conn -name proj_test
prj_install

It changes into the dist directory, runs @install.sql, and returns to the repository root. The alias captures the ordinary non-production path without pretending that it replaces artifact-based release management.

SQL> prj_install
Running Project Installer Script...
Installing/updating schemas
--Starting Liquibase at 2026-08-14T22:56:58.946607500 using Java 17.0.13 (version 4.33.0 #0 built at 2025-12-09 17:47+0000)
Running Changeset: releases\apex\f106\f106.xml::INSTALL_106::SQLCL-Generated
--application/set_environment
API Last Extended:20260330
Your Current Version:20260330
This import is compatible with version: 20260330
COMPATIBLE (You should be able to run this import without issues.)
ID offset during import: 23175081927095270
New ID offset for application: 0

APPLICATION 106 - EMP & DEPT Mini Hub
[APEX application component output skipped]
--application/end_environment
... elapsed: 5.07 sec

...done
Running Changeset: releases\apex\f120\f120.xml::INSTALL_120::SQLCL-Generated
--application/set_environment
API Last Extended:20260330
Your Current Version:20260330
This import is compatible with version: 20260330
COMPATIBLE (You should be able to run this import without issues.)
ID offset during import: 23178133412095845
New ID offset for application: 0

APPLICATION 120 - Working Copy Test
[APEX application component output skipped]
--application/end_environment
... elapsed: 1.44 sec

...done

UPDATE SUMMARY
Run:                          2
Previously run:              35
Filtered out:                 0
-------------------------------
Total change sets:           37

Liquibase: Update has been successful. Rows affected: 0

Produced logfile: sqlcl-lb-1786762618943.log

Operation completed successfully.

Invalid object counts (INVALID status only):

Compiling invalid objects...

Compiling DEMO1 ...Done!

Invalid object counts after recompilation (INVALID status + synonyms with missing targets):

OWNER                OBJECT_TYPE             OBJECT_COUNT INVALID_COUNT
-------------------- ----------------------- ------------ -------------
DEMO1                INDEX                              6
DEMO1                LOB                                1
DEMO1                SEQUENCE                           2
DEMO1                TABLE                              4

Invalid objects:

0 rows selected.

Compilation errors:

0 rows selected.

Other compilation errors not listed
-----------------------------------
                                  0
SQL>

prj_status: preview the next installation

Before an installation, I run:

conn -name proj_test
prj_status

The alias changes into dist and executes:

lb status -changelog-file releases/main.changelog.xml

I think of this as an installation dry run. It shows the pending changesets that Liquibase currently believes it should apply. That simple preview can reveal that I connected to the wrong database, that a changeset belongs to another developer’s unfinished work, or that the target environment’s deployment history does not match my expectations.

prj_status does not prove that an installation will succeed, but it is a valuable last check before changing an environment.

SQL> prj_status
Running the Liquibase Status Command to show pending changesets...
--Starting Liquibase at 2026-08-14T22:30:38.284170600 using Java 17.0.13 (version 4.33.0 #0 built at 2025-12-09 17:47+0000)
17 changesets have not been applied to CLA_DEPLOYER@[connection details redacted]
     aop_upgrade_25.2\_custom\aop_install.xml::SqlCl:1769116579255.1.1::SQLCL-Generated
     tacrep-11/cla_apex/package_specs/erp_emergency_event_util.sql::1784667704068::CLA_APEX
     tacrep-11/cla_apex/tables/erp_app_substitution.sql::1784667702170::CLA_APEX
     [12 additional changesets skipped]
     releases\apex\f1968\f1968.xml::INSTALL_1968::SQLCL-Generated
     _custom/custom_prompt.sql::1786760223440::SqlCl

Operation completed successfully.

SQL>

prj_sync: record a baseline without executing changes

Sometimes an environment already contains the state described by the repository. This is common while establishing a baseline, mitigating drift, or reconciling hotfixes. In that situation, running every historical changeset would be unnecessary or harmful, but Liquibase still needs its history table to reflect the accepted baseline.

The command:

prj_sync

wraps:

lb changelog-sync -changelog-file releases/main.changelog.xml

The important word is sync: this marks all pending changesets as executed without running their change logic. It effectively says, “This environment already represents these changes; record them and move forward.”

Because it changes deployment history, prj_sync should never be a reflexive response to an unexpected status. First confirm the target connection and prove that the database already has the intended state.

SQL> prj_status
Running the Liquibase Status Command to show pending changesets...
--Starting Liquibase at 2026-08-14T22:37:34.495236100 using Java 17.0.13 (version 4.33.0 #0 built at 2025-12-09 17:47+0000)
16 changesets have not been applied to CLA_DEPLOYER@[connection details redacted]
     tacrep-11/cla_apex/package_specs/erp_emergency_event_util.sql::1784667704068::CLA_APEX
     tacrep-11/cla_apex/tables/erp_app_substitution.sql::1784667702170::CLA_APEX
     [12 additional changesets skipped]
     releases\apex\f1968\f1968.xml::INSTALL_1968::SQLCL-Generated
     _custom/custom_prompt.sql::1786760223440::SqlCl

Operation completed successfully.

SQL> prj_sync
Running the Liquibase changelog-sync Command to mark all changesets as executed...
--Starting Liquibase at 2026-08-14T23:00:58.798761600 using Java 17.0.13 (version 4.33.0 #0 built at 2025-12-09 17:47+0000)

Operation completed successfully.

SQL> prj_status
Running the Liquibase Status Command to show pending changesets...
--Starting Liquibase at 2026-08-14T23:01:56.104367100 using Java 17.0.13 (version 4.33.0 #0 built at 2025-12-09 17:47+0000)
CLA_DEPLOYER@[connection details redacted] is up to date

Operation completed successfully.

SQL>

prj_mr: skip one already-satisfied changeset

prj_sync handles every pending changeset. Troubleshooting often requires a more precise tool.

Imagine that a deployment stops on an ALTER TABLE ... ADD statement because the column already exists in one target environment. This can happen after a direct production correction, a deployment that was not rolled back cleanly, or another form of drift. Once I have verified that the existing column really satisfies the intended changeset, I can run:

prj_mr

I remember mr as “make run.” Internally, the alias calls:

lb mark-next-changeset-ran -changelog-file releases/main.changelog.xml

Despite the name, it does not execute the changeset. It marks only the next pending changeset as ran so that the following installation can continue with the next one.

This is a troubleshooting operation, not a way to suppress inconvenient errors. Before using it, inspect the next changeset and confirm that the target database already implements the same result.

The before-and-after status below makes the effect explicit. The AOP upgrade is the next pending changeset before prj_mr; afterward, the pending count falls from 17 to 16 and that first changeset no longer appears.

SQL> prj_status
Running the Liquibase Status Command to show pending changesets...
--Starting Liquibase at 2026-08-14T22:30:38.284170600 using Java 17.0.13 (version 4.33.0 #0 built at 2025-12-09 17:47+0000)
17 changesets have not been applied to CLA_DEPLOYER@[connection details redacted]
     aop_upgrade_25.2\_custom\aop_install.xml::SqlCl:1769116579255.1.1::SQLCL-Generated
     tacrep-11/cla_apex/package_specs/erp_emergency_event_util.sql::1784667704068::CLA_APEX
     tacrep-11/cla_apex/tables/erp_app_substitution.sql::1784667702170::CLA_APEX
     [12 additional changesets skipped]
     releases\apex\f1968\f1968.xml::INSTALL_1968::SQLCL-Generated
     _custom/custom_prompt.sql::1786760223440::SqlCl

Operation completed successfully.

SQL> prj_mr
Running the Liquibase mark-next-changeset-ran Command to mark the next changeset as executed...
--Starting Liquibase at 2026-08-14T22:37:18.078485100 using Java 17.0.13 (version 4.33.0 #0 built at 2025-12-09 17:47+0000)

Operation completed successfully.

SQL> prj_status
Running the Liquibase Status Command to show pending changesets...
--Starting Liquibase at 2026-08-14T22:37:34.495236100 using Java 17.0.13 (version 4.33.0 #0 built at 2025-12-09 17:47+0000)
16 changesets have not been applied to CLA_DEPLOYER@[connection details redacted]
     tacrep-11/cla_apex/package_specs/erp_emergency_event_util.sql::1784667704068::CLA_APEX
     tacrep-11/cla_apex/tables/erp_app_substitution.sql::1784667702170::CLA_APEX
     [12 additional changesets skipped]
     releases\apex\f1968\f1968.xml::INSTALL_1968::SQLCL-Generated
     _custom/custom_prompt.sql::1786760223440::SqlCl

Operation completed successfully.

SQL>

Small helpers that remove repeated work

Two additional aliases are useful when maintaining the repository:

• prj_force_apex removes the SQLcl-generated APEX deployment records from Liquibase metadata so that the applications can be redeployed by the next prj_install. It prompts before making the change. Use it only after confirming the connection and understanding why SQLcl Project’s recorded state is wrong.
• prj_rm_logs removes *.log files throughout the repository. It is convenient when Liquibase leaves logs in generated directories, but review the repository first in case a log is intentionally retained.

A before-and-after check makes the log cleanup visible:

SQL> ! find . -name "*.log"
./dist/sqlcl-lb-1776898824169.log
./dist/sqlcl-lb-1776900353388.log
[additional log files skipped]
./dist/sqlcl-lb-error1780358656681.log

SQL> prj_rm_logs
Removing Logs from the repo...

SQL> ! find . -name "*.log"
SQL>

After prj_force_apex, either run prj_install to redeploy the applications or prj_sync to record them as current without redeploying.

Group 3: APEXlang shortcuts

APEXlang development has a tight edit-validate-import loop. The full apex validate and apex import commands require a source path and workspace name, even though both values can be derived from the application metadata.

The aliases reduce that interface to one argument: the application ID.

Validate the APEXlang source:

conn -name proj_dev
prj_validate 110

Import, or “compile,” the validated source back into APEX:

prj_compile 110

prj_validate resolves the APEXlang directory and workspace from apex_applications, then runs apex validate. prj_compile resolves the same values and runs apex import.

SQL> conn -n proj_vm26
Connected.

SQL> prj_validate 120
Validating APEXlang app 120 from src/database/demo1/apex_apps/f120/working-copy-test -ws DEMO1 ...
Validation successful.

SQL>

SQL> conn -n proj_vm26
Connected.
SQL> prj_compile 120
Compiling APEXlang app 120 from src/database/demo1/apex_apps/f120/working-copy-test -ws DEMO1 ...
Importing application ID: 120 into workspace: DEMO1
Import successful.

SQL>

These aliases are particularly effective with coding agents. A skill can instruct the agent to validate after an edit, correct any reported APEXlang error, and import only after validation succeeds. The agent operates through two stable commands, while the aliases keep workspace names and repository paths out of its prompt.

A compact working routine

For a normal change destined for a developer-controlled environment, the core routine becomes the following. The commented blocks show exceptional paths and should be used only when their stated conditions apply.

-- Connect to the development environment.
conn -name proj_dev
prj_exp_app 110

-- Edit and review the APEXlang source files.

prj_validate 110
prj_compile 110

-- Edit Oracle Database objects and apply the changes to the development database.

project export -o TABLE1

-- Commit the exported source before staging.
! git add .
! git commit -m "ready to stage"

-- Stage the changes and remove false ORDS changes.
project stage
prj_rm_ords

-- Add custom DML after staging, then edit the generated changeset.
project stage add-custom -file-name changes1.sql

-- Deploy to the unit-test environment.
conn -name proj_test
prj_status

/*
-- Optional: force all APEX applications to be included in the next installation.
prj_force_apex
*/

prj_install

/*
-- Troubleshooting only: if the installation failed because the next
-- changeset is already satisfied, mark that one changeset and retry.
prj_mr
prj_install
*/

/*
-- Baseline or drift alternative: after verifying that the environment
-- already contains every pending change, use this instead of prj_install.
prj_sync
*/

-- Clean up the logs after reviewing them.
prj_rm_logs

Git remains part of every step: inspect exports, review the diff, commit only intended files, and merge through the team’s normal process. Aliases make important operations shorter; they do not replace source control discipline or deployment review.

Keep aliases transparent

The best aliases are not mysterious automation. Their names are consistent, their implementations are version-controlled, and a developer can inspect the XML to see exactly what each command will do.

That transparency is especially important for commands that restore Git paths, delete logs, or change Liquibase history. A short command should reduce typing, not reduce understanding.

Used that way, SQLcl aliases become more than conveniences. They provide a small, shared command vocabulary for developers, CI-oriented scripts, and coding agents working with the same SQLcl Project repository.

References

• Oracle SQLcl User’s Guide, release 26.1
• Oracle SQLcl User’s Guide: APEXlang commands
• Jeff Smith: Object Search in SQLcl
• Oracle Forums: SQLcl corrupts APEX static files during APEXlang export
• Oracle Forums: SQLcl Project export should remove stale APEX alias folders
• Oracle Forums: SQLcl Project stage always regenerates ORDS changesets
• realSQLclProject: Common Commands and Directives cheat sheet
• realSQLclProject: SQLcl Project alias collection

During an APEX 26.1 upgrade, I discovered that using a native Boolean database column requires the data type to remain Boolean throughout the complete path:

database column -> APEX source -> session state -> page control -> database column

An application may appear correct visually while one part of that path still treats the value as VARCHAR2. The result can be a control that renders but does not save, ignores its default, or fails APEXlang validation.

This article summarizes the corrections that made native Boolean items work reliably in APEXlang source maintained and validated with SQLcl.

Symptoms after the upgrade

The application showed several related symptoms:

• Checkboxes and switches did not consistently save their values.
• Some controls ignored their default values.
• Boolean Interactive Grid columns failed validation because they had character-only filter operators.
• Correct page-level APEXlang was not enough when application-level checkbox and switch settings still used the old string convention.

These issues shared one cause: metadata created around string-based Boolean conventions had survived after the underlying database columns became native BOOLEAN values.

Declare Boolean session state

Every page item or Interactive Grid column that carries a native Boolean value must declare Boolean session state:

sessionState {
    dataType: boolean
}

This applies to visible checkbox and switch controls as well as hidden items that carry Boolean values. A sessionState block that declares only its storage behavior is not sufficient; its dataType must also be boolean.

Without this declaration, APEX can treat the page value as character data and fail to round-trip it correctly to the native database column.

Keep database sources typed as Boolean

When an item or column is directly backed by a native Boolean database column, its source must also be typed as Boolean:

source {
    dataType: boolean
}

The other source properties depend on the component and must be checked against compiler-backed APEXlang guidance. The important rule is that a database-backed native Boolean source must not silently fall back to a character type.

Do not add a source block merely because an item has Boolean session state. Virtual items, local items, and default-value-only items may have no database source at all.

In APEX Page Designer, confirm both settings for a database-backed Boolean item or column: Source > Data Type must be BOOLEAN, and Session State > Data Type must also be changed from VARCHAR2 to BOOLEAN.

The Source data type is already BOOLEAN; the crossed-out VARCHAR2 Session State value must be changed to BOOLEAN.

Use native Boolean default expressions

Older applications may convert a Boolean expression to text:

default {
    type: expression
    plsqlExpression: to_char(true)
}

That expression returns a character value and conflicts with Boolean session state. Use a native Boolean literal instead:

default {
    type: expression
    plsqlExpression: true
}

Use false in the same way when the default should be false. Avoid to_char(true), to_char(false), and quoted Boolean values when the target is a native Boolean.

Remove character operators from Boolean Interactive Grid filters

Interactive Grid columns may retain filter metadata copied from character columns. For example, performanceImpactingOperators can include operators such as:

• contains
• startsWith
• caseInsensitive

These operators apply to character data types such as VARCHAR2 and CLOB; they are not valid for a Boolean column. If they remain on a Boolean column, apex validate can report an INVALID_PROPERTY error.

Remove character-only performanceImpactingOperators from the Boolean column’s columnFilter block. Do not replace them with guessed values–use only operators supported by the APEXlang compiler for that component and data type.

Correct application-level component settings

Page files are only part of the fix. APEX component settings define the values used by checkbox and switch controls throughout the application.

Applications migrated from string-based Boolean conventions may still use uppercase TRUE and FALSE values as character strings. With native Boolean columns, define native lowercase Boolean literals in shared-components/component-settings.apx:

componentSetting (
    type: item
    name: checkbox
    settings {
        checkedValue: true
        uncheckedValue: false
    }
)

componentSetting (
    type: item
    name: switch
    settings {
        onValue: true
        onLabel: Yes
        offValue: false
        offLabel: No
    }
)

Because these settings are application-wide, correcting them establishes the native Boolean convention for every checkbox and switch that uses the defaults.

Audit and validation workflow

After upgrading an application or changing database columns to native BOOLEAN, audit the APEXlang source systematically:

1. Identify database columns whose data type is BOOLEAN.
2. Find page items, hidden items, and Interactive Grid columns that expose those columns.
3. Add sessionState { dataType: boolean } where it is missing.
4. Confirm that database-backed sources declare dataType: boolean.
5. Replace string conversions and quoted defaults with native true or false expressions.
6. Remove character-only filter operators from Boolean Interactive Grid columns.
7. Review checkbox and switch settings in shared-components/component-settings.apx.
8. Run apex validate against the application source and correct every compiler error.
9. Import only after validation succeeds, then test both true-to-false and false-to-true updates in the application.

A generic SQLcl validation command is:

apex validate -input <apexlang-application-path> -ws <workspace-name>

Validation is the essential compiler gate, but it does not replace runtime testing. Confirm that values render, change, save, and reload correctly for page items and editable grid columns.

Lessons learned

Native Boolean support is cleaner than string or numeric workarounds, but an upgrade requires more than changing the database column type. Session state, source metadata, default expressions, Interactive Grid filters, and application-level component settings must agree on the Boolean type.

The most important practical lessons are:

• Trace the data type end to end rather than fixing only the visible control.
• Audit hidden items and shared component settings, not only checkboxes and switches on page files.
• Keep native Boolean literals native; do not convert them to strings.
• Use apex validate after every APEXlang change and test persistence in the running application afterward.

Once these rules are applied consistently, the fixes are mechanical and can be reused across APEX applications that adopt native Oracle Database Boolean columns.

References

• Original realSQLclProject document: Native Boolean Columns in Oracle APEX 26.1 and APEXlang

How do we combine them without losing either developer’s work?

I demonstrated one approach during an APEX Instant Tips broadcast. The technique uses three capabilities together:

• APEX working copies preserve and compare application state.
• APEXlang makes conflicting page definitions editable as source.
• SQLcl validates and imports the reconciled application.

The result is a practical workflow for resolving application drift and merging parallel development, including cases where both developers changed the same page.

The demo application

The demo uses application 120, a deliberately small application that makes each change easy to see.

The original version has a blue region on page 1 containing the text:

I am blue like the sky.

Selecting it opens a picture of the sky on page 2. I will call this the Blue version.

Another developer has changed the same application independently. Their version has a yellow region on page 1. Selecting it opens a picture of wheat on page 3. I will call this the Yellow version.

The desired result must retain both sets of behavior:

• the Blue region, page 2, and sky.jpg; and
• the Yellow region, page 3, and wheat.jpg.

The separate pages and static files are straightforward. The complication is page 1, because both developers changed it.

Step 1: Preserve the current application as a working copy

Before importing the incoming Yellow version, create a working copy of the current application and name it Blue.

At this point, the working copy and the main application are identical. The working copy is a preserved APEX-side snapshot of the Blue stream of work.

This step should happen before replacing the main application. If the current application contains changes that exist nowhere else, verify that the working copy was created successfully before continuing.

Step 2: Import the incoming version as the main application

Use SQLcl apex import to install the incoming application from the repository into the same workspace as the new main application.

In this workflow, importing the application replaces the main application while leaving the existing Blue working copy available. After the import:

• the Blue version is preserved as the working copy; and
• the incoming Yellow version is installed as the main application.

Run the application and confirm that the incoming behavior is present. In the demo, page 1 is now yellow, and its action opens the wheat image on page 3.

Step 3: Compare the working copy with the main application

Open the Blue working copy and select Compare with Main.

The comparison identifies the two kinds of changes we need to handle:

Page 2, page 3, and the two images are independent changes. The normal working-copy merge can preserve them.

Page 1 requires more care. Its comparison shows differences in regions, buttons, dynamic actions, and other page components. Choosing either complete version of the page would discard some of the other developer’s work.

Step 4: Reconcile the conflicting page in APEXlang

This is where APEXlang changes the workflow.

Open the page 1 APEXlang source for the incoming Yellow version in Visual Studio Code. Add the required Blue components to that source: in this example, the Blue region, button, and dynamic action.

The Yellow source becomes the base, and the Blue changes are applied deliberately to it. The resulting page definition contains both streams of work.

This is a semantic merge rather than a blind text merge. Review the component structure and relationships carefully. In particular, check that:

• component identifiers and names do not collide;
• buttons still target the correct dynamic actions;
• region and item references remain valid;
• page-level processing order is intentional; and
• both developers’ behavior is represented in the combined source.

Step 5: Validate and import the reconciled source

Validate the updated APEXlang before importing it:

apex validate -input <apexlang-application-path> -ws <workspace-name>

Correct every compiler error, then import the validated application:

apex import -input <apexlang-application-path> -ws <workspace-name>

At this stage, the main application contains the Yellow version plus the Blue changes manually reconciled on page 1.

The import does not finish the complete merge. The Blue working copy still contains the independent page 2 and sky.jpg changes that must be brought into the main application.

Step 6: Compare again before merging

Return to the working-copy screen and compare the Blue working copy with the main application again.

The comparison now tells a different story:

• the main application’s page 1 already contains the combined Blue and Yellow behavior;
• the working copy still contains the original Blue version of page 1; and
• page 2 and sky.jpg still need to be preserved from the working copy.

This second comparison is an important checkpoint. It confirms what has already been reconciled and what remains to be merged.

Step 7: Selectively merge the working copy

Use the normal APEX working-copy merge to bring the remaining Blue changes into the main application, but exclude page 1.

Excluding page 1 is essential. Its conflicts were already resolved through APEXlang. Merging the original working-copy version of page 1 could overwrite the combined result and restore the problem we just solved.

Select only the changes that still need to be preserved, including page 2 and the sky image, and then complete the merge.

The final application now contains:

• the combined Blue and Yellow regions on page 1;
• the Blue page 2 and sky image; and
• the Yellow page 3 and wheat image.

Step 8: Test the combined application

Run the application and test both paths.

In the demo, page 1 now resembles the Ukrainian flag: blue on top and yellow below. Selecting blue opens the sky; selecting yellow opens the wheat.

The visual result is memorable, but the important result is technical: neither developer’s work was lost.

Why the workflow works

Each tool handles the part of the merge it understands best:

APEX working copy  -> preserve and compare the current application
APEXlang           -> reconcile conflicting component definitions
SQLcl              -> validate and import the combined application
Working-copy merge -> selectively restore non-conflicting changes

Working copies provide an application-aware comparison and selective merge. APEXlang gives us a source representation for resolving a page that both developers changed. SQLcl provides the compiler gate and the import path back into APEX.

The technique does not eliminate the need for judgment. It gives us better places to apply that judgment.

Safety rules

When applying this workflow to a real application:

1. Commit or otherwise preserve every repository change before starting.
2. Confirm the target database, workspace, and application ID before importing.
3. Create and verify the working copy before replacing the main application.
4. Classify differences as independent or conflicting before merging anything.
5. Reconcile shared-page conflicts in APEXlang and validate the complete application.
6. Compare the working copy with main again after the import.
7. Exclude already-reconciled pages from the later working-copy merge.
8. Test every retained behavior, not merely whether the application imports successfully.
9. Export the final combined application back to the repository so APEX and Git agree again.

That final export closes the loop. The repository should represent the same combined application that was tested in APEX.

APEX working copies, APEXlang, and SQLcl solve different parts of the problem. Used together, they provide a controlled way to resolve application drift and combine parallel development without reducing the decision to “keep my page” or “keep their page.”