Common Tasks

After you install the environment, these are the most common tasks in APEX development.

Docker or Podman

The commands on this page that call docker compose also work with Podman. Replace docker compose with podman compose. The scripts of this project (local-26ai.sh, ./scripts/*.sh) detect the engine, so you change nothing for those.

Managing Containers

Start/Stop Containers

# Stop database
local-26ai.sh stop
# You could also run this, but the script will gracefully stop the database
# docker compose stop   (or: podman compose stop)

local-26ai.sh start
# Or
# docker compose start  (or: podman compose start)

ORDS Configuration

Modify ORDS Settings

The ords-config folder in the root directory contains the configuration files of ORDS. Change these files. Then restart the ORDS container:

# After modifying config files
docker compose restart ords-26ai   # or: podman compose restart ords-26ai

SSL Configuration

To enable HTTPS for ORDS, create self-signed certificates. On macOS and Linux the script also adds the certificate to the keychain of your system:

sudo ./scripts/create-self-signed-certificates.sh
docker compose restart ords-26ai   # or: podman compose restart ords-26ai

Then open https://localhost:8443/ords. ORDS uses port 8443 for HTTPS, not port 8181.

Maintenance Tasks

Check Database Space Usage

The Free edition of the database has a space limit of 12GB. Show the used space with this command:

local-26ai.sh used-space

#    CURRENT_GB    LIMIT_GB    PERCENT_OF_LIMIT STATUS
# _____________ ___________ ___________________ _________
#          5.04          12               41.97 OK


# Tablespace                 Total MB    Used MB    Free MB    Pct. Free
# _______________________ ___________ __________ __________ ____________
# SYSAUX                         3440       3158        282            8
# SYSTEM                          690        679         11            2
# USERS                           118         59         59           50
# TBS_PLUGINS                     112         38         74           66
# UNDOTBS1                        103         23         80           78
# TBS_AOP                          77          7         70           91

Shrink Database Files

If the tablespaces are larger than the space that they use, shrink them. This command can run for several minutes.

local-26ai.sh shrink-space

This can take a while. The script works through several steps, each safe to run repeatedly:

1. Purge audit records – the AUDIT_TRAIL tablespace can balloon to several GB and never shrink back on its own. You are prompted before any audit history is deleted (defaults to yes; non-interactive runs purge automatically).
2. Drop a leftover old APEX engine – after an APEX upgrade the previous version’s schema (e.g. APEX_240200) is left behind and wastes ~hundreds of MB. If one is found you are asked to confirm before it is dropped. This is irreversible, so it is skipped when the script runs non-interactively.
3. Shrink the APEX file repository – uploaded/imported files in FLOWS_FILES leave dead space inside the storage that a normal tablespace shrink can’t reclaim. This is compacted without touching your files.
4. Shrink the tablespaces and resize the datafiles – returns the freed space to your disk.

Caution

All steps are designed to be non-destructive to your apps and data, but the audit purge deletes audit history and the old-APEX drop removes the prior engine schema. These run only after you confirm them. Make a backup first if in doubt.

Compress a Schema’s Tablespace

shrink-space reclaims unused space only. compress-space makes the data itself smaller.

The command enables Advanced Compression on the tbs_<schema> tablespace of one schema. Oracle Database Free includes this feature. The command then rebuilds the objects in that tablespace in compressed form:

• Tables get advanced row compression (COMPRESS FOR OLTP). The database compresses them again when rows change.
• B-tree indexes get advanced index compression (COMPRESS ADVANCED LOW).
• New segments also use compression, because the command sets the tablespace defaults.

After the rebuild, the command runs dbms_space.shrink_tablespace and makes the datafile smaller. The operating system gets the free space in the same run.

local-26ai.sh compress-space movies
# Skip the confirmation prompt with -y:
local-26ai.sh compress-space movies -y

# Tablespace usage before compression:
#    USED_MB    ALLOCATED_MB
# __________ _______________
#     1000.8            2100
# ...
# Tablespace usage after compression:
#    USED_MB    ALLOCATED_MB
# __________ _______________
#      595.6           749.7

Note

The command runs online and never drops an object. You can run it again safely, because it skips the objects that are already compressed. It does not compress a unique index or a primary-key index with one column. Advanced index compression cannot remove duplicate values from these indexes.

Disable Archive Logs

Archive logging is not necessary in a development environment. The after-first-db-start.sh script asks you about this setting. You can also run the script for it directly:

./scripts/disable-archive-logs.sh

Manage APEX Account Expiration

Unexpire Accounts

If the APEX_PUBLIC_USER account or a workspace account is locked because the password expired, unlock it with this command:

./scripts/unexpire-accounts.sh

Run this script after a database migration, or when an account expires after some time.

Disable Password Expiration

install.sh already runs this script, so a new installation needs it only after a change to the password profile. Run it so the passwords of APEX workspace accounts never expire:

./scripts/disable-password-expiration.sh

Note

Users can still get a prompt to change the password at the first login after a migration. This happens even when password expiration is disabled.

Workspace Import/Export

Import All Exports

Import every export file from the ./backups/import/ directory:

./scripts/import-all.sh

Use this script during a database migration, when you import many workspaces and schemas at the same time. The script shows a summary of the successful and the failed imports.

Fix Workspace Export Issues

A known bug with group assignments can make the import of an APEX workspace fail. If this happens, run this script:

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

The script deletes the group ID parameters from every export file in ./backups/import/. Then the files import correctly.

Complete Environment Reset

Delete All Data

⚠️ CAUTION: These commands delete the database volume. All schemas, workspaces, and applications are lost. Run local-26ai.sh backup-all first.

To start again with an empty database, run these commands:

docker compose down        # or: podman compose down
docker volume rm oradata-26ai   # or: podman volume rm oradata-26ai
rm .env

Then do the setup again.