Migrate to 26.1

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

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

Changes

23ai to 26ai database (23.26.0)
- Data files are not compatible, so a dump/restore is needed
ORDS 25.2 → ORDS 25.4
This now a space optimized way with own tablespace for audit and APEX data from Connor McDonald’s blog post.
New Scripts
- import-all.sh: A script to import all exports (created to automate bulk imports during migration).
- unexpire-accounts.sh:: Script to unexpire APEX_PUBLIC_USER and workspace accounts (addresses password expiration issues post-migration).
- fix-ws-group-ids.sh Script to fix p_group_ids in APEX workspace SQL files (resolves a known Oracle bug with group assignments during workspace imports).
- disable-password-expiration.sh: Script to disable password expiration for APEX workspace accounts (prevents future forced password changes).
Enhanced scripts
- backup-user.sh: Added support for ORDS export directory and schema export.
- import-backup.sh: Added support for optional remap schema parameter and auto-confirmation flag (-y).
- import-datapump.sh: Updated usage message and added support for optional remap schema parameter.
- test-script-install.sh: Added support for auto-confirmation with -y flag.
- test-app-install.sh: Added support for auto-confirmation with -y flag.
- clear-schema.sh: Added support for auto-confirmation with -y flag.
- create-user.sh: Added username validation for hyphens and improved quoting.

Migration

First pull the latest changes:

git fetch
git pull origin 25-3

Give permission to all new scripts:

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

Make sure your database is running:

docker ps

Otherwise start the database:

local-23ai.sh start

Backup the database

This will backup all schemas and APEX workspaces, APEX apps, and ORDS modules for users that were created with the local-23ai.sh create-user script. If you have additional schemas/workspaces or artifacts you need to backup them manually.

local-23ai.sh backup-all

Now check the backups/export directory if the backup was created successfully.

Recommended: backup the oradata volume

Optionally also back up the oradata files. This can take a moment, mine is about 10GB big. Make sure that ./backups/oradata does not exist.

source ./scripts/util/load_env.sh

docker exec $CONTAINER_NAME bash -c "echo 'shutdown immediate;
exit' | sqlplus / as sysdba && exit"

docker cp $CONTAINER_NAME:/opt/oracle/oradata ./backups/oradata

Backup this folder

To make sure you will be able to still use the old 23ai database, back up this whole folder. You can use it like you are used to just from the new uc-local-apex-dev-23ai folder.

cd ..
cp -r uc-local-apex-dev uc-local-apex-dev-23ai

Stop the containers

local-23ai.sh stop

Switch branch

If you don’t have the repository cloned yet, you can clone from GitHub.

git fetch
git checkout 26-1

Give permission to all new scripts

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

Re create the conn_string.txt

source ./scripts/util/load_env.sh
echo "CONN_STRING=sys/$ORACLE_PASSWORD@26ai:1521/FREEPDB1" >./ords-secrets/conn_string.txt

Patch .env file

Update the DBHOST variable in your .env file to change DBHOST="23ai" to DBHOST="26ai" and CONTAINER_NAME=local-23ai to CONTAINER_NAME=local-26ai.

On macOS use:

sed -i '' 's/DBHOST="23ai"/DBHOST="26ai"/' .env
sed -i '' 's/CONTAINER_NAME=local-23ai/CONTAINER_NAME=local-26ai/' .env

On Linux use:

sed -i 's/DBHOST="23ai"/DBHOST="26ai"/' .env
sed -i 's/CONTAINER_NAME=local-23ai/CONTAINER_NAME=local-26ai/' .env

Copy backup exports to import folder

cp -r ./backups/export/ ./backups/import/

Start the containers

(The script is renamed from local-23ai.sh to local-26ai.sh)

local-26ai.sh start

Check the logs until the database and ORDS are ready:

docker-compose logs --follow

Visit http://localhost:8181/ords (HTTP) or https://localhost:8443/ords (HTTPS) to check if ORDS is up (APEX is not yet available).

Run setup script

./scripts/after-first-db-start.sh

Restart containers

local-26ai.sh stop
local-26ai.sh start

And check whether the ORDS page now shows APEX.

Then run the unexpire accounts script to avoid password expiration issues:

./scripts/unexpire-accounts.sh

If you don’t want APEX workspace accounts to expire in the future, run also the disable password expiration script:

./scripts/disable-password-expiration.sh

(Although at the first login you can still be forced to change the password.)

Double check workspace exports

In my case there were some issues with reimporting APEX workspaces. The cause is a long known bug (oracle pls fix ;) ) where the users can’t be imported with their group assignments.

The solution is just to change the group IDs parameter of the create_fnd_user procedure to empty strings (p_group_ids => '1224412:1232423' to p_group_ids => ''). This won’t break anything.

Run the fix script to update all export files:

./scripts/fix-ws-group-ids.sh

Start import

./scripts/import-all.sh > import-log.txt

After a whole you should see something like this:

========================================
Import Summary
========================================
Total users: 14
Successfully imported: 14
Failed: 0

If you see any failures, check the import-log.txt file for details.

Manually check if everything is working

Check connections still work
Check if data is there
Login to APEX workspaces and check if apps are there
Check ORDS modules if they are there

Get rid of 23ai

If you want you can now delete the old 23ai folder you backed up before.

delete the old folder uc-local-apex-dev-23ai
delete the old docker containers
delete the old docker volume

docker rm local-23ai local-ords
docker volume rm oradata

Optional: delete old docker images

docker image ls
docker image rm {image_name}