Migrate to 26.4

If you haven’t installed uc-local-apex-dev yet, you can find the setup instructions here.

Make sure you are on 26.3 before you start. Do the previous migrations if not.

Changes

• DB 23.26.2.0 → 23.26.3.0. The datafiles are compatible. No dump and restore is necessary. The data dictionary does not upgrade automatically. See Upgrade the data dictionary.
• ORDS 26.1.2 → 26.2.2. ORDS upgrades its own schema on the first start. No action is necessary.
• New script scripts/repair-ru-dictionary.sh (local-26ai.sh repair-ru-dictionary). A change of the database image does not upgrade the data dictionary, and it also stops the in-database JVM without a message. The script repairs both. This migration needs it one time. One run also repairs the release updates that earlier image changes missed. See Upgrade the data dictionary.
• The scripts detect the container engine now, so Podman works without changes. CONTAINER_CLI overrides the detected engine, and CI installs the project with both engines. Release 26.3 documented Podman, but the scripts called docker directly.
• The project needs the Compose plugin (docker compose). The old docker-compose and podman-compose commands are no longer supported.
• install.sh starts the database first and waits for it before it starts ORDS. Podman 5.5 and later do not report the container health status, so one compose up -d for the whole stack never continues. Docker is not affected. See the FAQ.
• APEX instance & workspace parameter handling reworked (scripts/upgrade-apex.sh, scripts/util/get_ws_settings.sh)
  • Parameters that APEX resolves at runtime (MAX_SESSION_IDLE_SEC, MAX_SESSION_LENGTH_SEC, ACCOUNT_LIFETIME_DAYS, MAX_WEBSERVICE_REQUESTS) are now set once at the instance level instead of being repeated for every workspace. Any workspace without its own override inherits the instance value.
  • get_ws_settings.sh now sets only the two parameters that genuinely need a per-workspace value: ALLOW_HOSTING_EXTENSIONS (a NOT NULL per-workspace column that does not inherit) and WORKSPACE_EMAIL_MAXIMUM (no instance-level equivalent).
  • Secure installs (SECURE_MODE=true, that is install.sh --secure) now get bounded session timeouts — 18h max length / 8h max idle — instead of the 7-day developer default. Local (non-secure) installs are unchanged and keep the long 7-day sessions for convenience.
• Every datafile now gets a size ceiling, so one datafile cannot fill the 12GB limit of the Free edition alone. A PDB that passes the limit does not open, and you cannot correct it from inside. Existing installs need one command. See Cap the tablespaces.
  • New script scripts/cap-tablespaces.sh (local-26ai.sh cap-tablespaces): --check reports the datafiles without a ceiling, --apply gives them one, and --summary gives key=value lines.
  • create-user.sh now sets MAXSIZE on the tablespace of the new schema. The default is 2G, and USER_TBS_MAXSIZE in .env changes it.
  • after-first-db-start.sh now caps the undo datafile at 2048MB, sets undo_retention to 900, and caps AUDIT_TRAIL at 1GB. Undo autotuning grows an uncapped undo datafile without a limit, which was the cause of the failure above.
  • after-first-db-start.sh now creates the UC_AUDIT_PURGE job. The job keeps 7 days of unified audit records. The old code marked records as archivable but never purged them, so the audit tablespace grew forever. On one install it reached 1783MB.
  • used-space.sh gains --summary and --quiet, and it now reports through the exit code (10 for WARNING, 11 for CRITICAL). The warning threshold moves from 10GB to 9.5GB. SPACE_WARN_GB and SPACE_CRIT_GB in .env change both thresholds.
  • stop.sh now shows a warning if the database is close to the limit. This is the last point at which you can act.

Migration

Make sure your database is running:

docker ps

Otherwise start the database:

./local-26ai.sh start

Backup the database

This will backup all schemas and APEX workspaces that were created with the local-26ai.sh create-user script. If you have additional schemas or workspaces you need to back them up manually.

./local-26ai.sh backup-all

Check the backups/export directory to confirm the backup was created successfully.

Stop the containers

./local-26ai.sh stop

Switch branch

git fetch
git checkout 26-4

Give permission to all scripts

chmod +x ./local-26ai.sh ./setup.sh ./scripts/*.sh

Start the containers

./local-26ai.sh start

Monitor the logs until the database and ORDS report they are ready:

docker logs -f local-26ai
docker logs -f local-26ai-ords

The new instance-level parameters are applied by upgrade-apex.sh the next time APEX is (re-)installed. Newly created workspaces inherit them automatically.

Upgrade the data dictionary

The image change does not upgrade the data dictionary. The database keeps the dictionary of the release update that created it.

Release update 23.26.3 adds new dictionary views. It also adds a new version of the in-database JVM. A database from an earlier release update does not get these changes.

The container starts and reports that it is healthy. Your data and your objects stay valid. Only the dictionary is incomplete.

Show what is missing:

./scripts/repair-ru-dictionary.sh --check

Apply the repair:

./scripts/repair-ru-dictionary.sh --repair

The script reloads the catalog scripts of Oracle for the missing features. It then reloads the in-database JVM. The repair needs some minutes. The database stays open, and a restart is not necessary.

Make sure that the dictionary is now complete:

./scripts/repair-ru-dictionary.sh --summary

The output must contain missing_repairable=0, jvm_ok=yes and non_valid_components=0.

Note

The repair corrects every release update that your database missed, not only 23.26.3. One database that started on 23.26.0 reported 13 missing views, because earlier image changes left their own gaps. One --repair run closed all of them.

The dictionary_ru line in the output keeps the name of the old release update. No supported tool updates this marker. The difference to binary_version is therefore expected, and you can ignore it.

If a package stays INVALID

The repair recompiles the database objects in parallel. A package body that uses a SQL macro can fail this recompilation. The error is ORA-62565 with PLS-00201. The macro function itself is correct.

The sys.utl_recomp.recomp_serial() block in Verify does not correct this error. That procedure recompiles in a background job, and the macro call fails again.

If a package body stays INVALID, compile it directly:

alter package "OWNER"."PACKAGE_NAME" compile body;

Optional: apply the new session limits to existing workspaces

Your workspaces carry their own session values, so they keep the 7-day timeout. This step makes them use the instance values. It matters most for a secure install, which limits a session to 18 hours and an idle session to 8 hours.

Connect as SYS and do the two steps in this order. If you clear the workspace values first, the workspaces get the old values.

Step 1: set the instance values. Use the block for your install:

-- secure install (install.sh --secure): 18h maximum length, 8h maximum idle
begin
  apex_instance_admin.set_parameter('MAX_SESSION_LENGTH_SEC',  64800);
  apex_instance_admin.set_parameter('MAX_SESSION_IDLE_SEC',    28800);
  apex_instance_admin.set_parameter('ACCOUNT_LIFETIME_DAYS',   9999);
  apex_instance_admin.set_parameter('MAX_WEBSERVICE_REQUESTS', 100000);
  commit;
end;
/

-- local install: 7 days for both timeouts
begin
  apex_instance_admin.set_parameter('MAX_SESSION_LENGTH_SEC',  604800);
  apex_instance_admin.set_parameter('MAX_SESSION_IDLE_SEC',    604800);
  apex_instance_admin.set_parameter('ACCOUNT_LIFETIME_DAYS',   9999);
  apex_instance_admin.set_parameter('MAX_WEBSERVICE_REQUESTS', 100000);
  commit;
end;
/

Step 2: clear the workspace values, so that the workspaces use the instance values:

begin
  for w in (select workspace from apex_workspaces) loop
    apex_instance_admin.set_workspace_parameter(w.workspace, 'MAX_SESSION_IDLE_SEC',   null);
    apex_instance_admin.set_workspace_parameter(w.workspace, 'MAX_SESSION_LENGTH_SEC', null);
    apex_instance_admin.set_workspace_parameter(w.workspace, 'ACCOUNT_LIFETIME_DAYS',  null);
    apex_instance_admin.set_workspace_parameter(w.workspace, 'MAX_WEBSERVICE_REQUESTS', null);
  end loop;
  commit;
end;
/

ALLOW_HOSTING_EXTENSIONS stays a workspace value. It is a NOT NULL column, and it cannot use the instance value.

Cap the tablespaces

Your database was created before this release, so its datafiles have no size ceiling. One datafile can therefore grow until the PDB passes the 12GB limit of the Free edition. The PDB then does not open, and you cannot correct it from inside. Only new installs get the ceilings automatically.

Show the datafiles that have no ceiling:

./local-26ai.sh cap-tablespaces --check

Give them a ceiling:

./local-26ai.sh cap-tablespaces --apply

The command sets MAXSIZE on each datafile. It never drops an object and it never moves data. Run it again at any time.

Make sure that nothing is left:

./local-26ai.sh cap-tablespaces --summary

The output must contain uncapped_files=0 and pending_files=0.

If a datafile is already larger than its ceiling, the command uses the current size of the file and reports it. Reclaim the space and then lower the ceiling:

./local-26ai.sh shrink-space
./local-26ai.sh cap-tablespaces --apply

Note

This release also adds the UC_AUDIT_PURGE job for new installs. Your database does not get the job, because after-first-db-start.sh does not run again on an installed database. shrink-space purges the audit records for you, and the command above tells you to run it. On one install this step alone freed 1.4GB.

Verify

Navigate to http://localhost:8181/ords/apex to confirm ORDS is serving APEX.

After a major restart it is normal for some application objects to be temporarily marked INVALID; they recompile automatically on first use. If you want to recompile everything up front, connect as SYS and run:

begin
  sys.utl_recomp.recomp_serial();
end;
/

Optional: delete old docker images

Delete the images of the old release only after APEX answers. They are the way back if you must return to 26.3.

# Check which versions you still have:
docker image ls

# And remove them like this:
docker image rm container-registry.oracle.com/database/free:23.26.2.0
docker image rm container-registry.oracle.com/database/ords:26.1.2