Migrate to 26.3

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

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

Changes

• DB 23.26.1.0 → 23.26.2.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.0 → 26.1.2
• New scripts
  • install.sh: one-shot installer that runs setup.sh, pulls images, brings the stack up, waits for the DB and ORDS to be ready, bakes in the ORDS gateway-mode config (and restarts ORDS), and runs after-first-db-start.sh non-interactively — only relevant for fresh installs, not for in-place migrations.
  • upgrade-apex.sh: dedicated script to upgrade the APEX version (split out of after-first-db-start.sh); verifies the apex-images layout and hardens the image copy step.
• Enhanced scripts
  • after-first-db-start.sh: pre-checks for required commands (sql, docker, unzip, curl/wget) and reports any that are missing before continuing; reuses ORACLE_PASSWORD for the APEX Internal ADMIN password setup.
  • upgrade-apex.sh: disables the strong-admin-password rule so the generated alphanumeric password is accepted.
  • APEX download now works with either curl or wget (#30).
  • Non-interactive SQLcl calls are forced to a dumb terminal, fixing output/behavior over SSH and in CI.
  • Prefer the docker compose (v2 plugin) over the deprecated standalone docker-compose (v1) when both are present.
• Bug fixes
  • Removing a user / dropping all objects no longer errors when the user has no APEX workspace.
  • Fixed the call to the password-change script and added error handling (#28).
  • Hardened user_exists_in_db so the count is parsed correctly and defaults to 0.
  • Added an apex-path to prevent an error during a clean install, and made the APEX installation exit cleanly when finished.
• Tooling
  • New manually-triggered CI workflow (test-db-upgrade.yml) that installs the current version, seeds a comprehensive schema, upgrades on the same datafiles, and asserts nothing was lost or invalidated (including APEX-schema integrity). This is what validates that the DB bump in this release is datafile-compatible.
  • New CI workflow (test-clean-install.yml) that exercises install.sh on a fresh environment.
• Documentation
  • Expanded Windows setup instructions (WSL2) and various doc/typo fixes.

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-3

Give permission to all scripts

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

Start the containers

./local-26ai.sh start

The new binaries open the existing datafiles. Monitor the logs until the database shows DATABASE IS READY TO USE!. Also make sure that ORDS reports that it is initialized:

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

Upgrade the data dictionary

The image change does not upgrade the data dictionary. The database keeps the dictionary of the old release update.

Release update 23.26.2 adds new dictionary views. It also adds a new version of the in-database JVM. A database from 23.26.1 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 and jvm_ok=yes.

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;

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

docker image ls
docker image rm container-registry.oracle.com/database/free:23.26.1.0
docker image rm container-registry.oracle.com/database/ords:26.1.0