A new ORDS release appears every few months, with fixes, security updates, and new features. Upgrading is straightforward because the ORDS configuration folder is separate from the program: you put the new release next to the old one, upgrade the ORDS schema in the database, and start the new release with the same configuration.
This guide covers upgrading ORDS installed from the zip file, from Oracle's yum repository on Linux, and in Apache Tomcat, plus the one thing you must also update when you upgrade APEX itself.
These steps come from Oracle APEX 26.1 Book: The Complete Guide.
Version Rules
APEX 26.1 requires ORDS 26.1.1 or later, and newer ORDS releases always support the current APEX release. Check what you run now before you start.
Example:
ords --version ords --config ~/apex-lab/ords-config config verify
Output (verify):
Database pool default: Connection state: valid ORDS installed version in database: 26.2.3.r2371104
ords --version shows the program's release, and verify shows the ORDS schema version in the database. After an upgrade, both should show the new release. Back up the configuration folder before you begin; it holds the pool settings and the wallet with the stored passwords.
Upgrade ORDS Installed from the Zip File
This is the layout on Windows, macOS, and Docker setups, where ORDS lives in ~/apex-lab/ords (or C:\apex-lab\ords) and the configuration in ~/apex-lab/ords-config.
Step 1: Download and Unzip the New Release
Unzip the new ords-latest.zip into a new folder, for example ~/apex-lab/ords-26.3, so the old release stays untouched.
Example:
cd ~/apex-lab curl -LO https://download.oracle.com/otn_software/java/ords/ords-latest.zip unzip -q ords-latest.zip -d ords-26.3 rm ords-latest.zip ~/apex-lab/ords-26.3/bin/ords --version
Step 2: Stop the Running ORDS
Stop ORDS however it runs: Ctrl+C in its terminal, ~/apex-lab/stop.sh, launchctl bootout on macOS, or ending the task or service on Windows.
Step 3: Upgrade the ORDS Schema
Run ords install from the new folder with the same configuration folder and the same options as your original installation. ORDS detects the existing configuration and the older ORDS schema in the database, and upgrades the schema. Replace Welcome_2026# with your SYS password.
Example:
cd ~/apex-lab echo 'Welcome_2026#' | ~/apex-lab/ords-26.3/bin/ords \ --config ~/apex-lab/ords-config install \ --admin-user SYS \ --db-hostname localhost --db-port 1521 --db-servicename FREEPDB1 \ --feature-db-api true --feature-rest-enabled-sql true \ --feature-sdw true \ --gateway-mode proxied --gateway-user APEX_PUBLIC_USER \ --password-stdin
If you serve several databases, run the command once per pool with --db-pool and that pool's connection details.
Step 4: Start the New Release
Start ORDS from the new folder with the same --config folder.
Example:
~/apex-lab/ords-26.3/bin/ords --config ~/apex-lab/ords-config serve
Then point your PATH and any scripts or service definitions at the new folder: start.sh, the launchd agent's ProgramArguments, a Task Scheduler script, or an NSSM service. A simpler alternative that leaves every path unchanged is to swap the folder names while ORDS is stopped.
Example (instead of changing paths):
cd ~/apex-lab mv ords ords-old mv ords-26.3 ords
Step 5: Check and Clean Up
Run ords --version and ords config verify again; both should show the new release. Open /ords/apex and sign in. When everything works, delete the old folder.
Upgrade ORDS Installed from Oracle's Repository on Linux
On Oracle Linux with ORDS from the Oracle Software yum repository, dnf replaces the program in /opt/oracle/ords, and the configuration in /etc/ords/config stays as it is.
Example:
sudo systemctl stop ords sudo dnf upgrade ords
Then run the same ords --config /etc/ords/config install command as your original installation, as the oracle user, to upgrade the ORDS schema if the new release needs it, and start the service.
Example:
sudo systemctl start ords sudo tail -n 40 /var/log/ords/ords.log
The log should end with "Oracle REST Data Services initialized". For the full server layout, see how to install Oracle APEX 26.1 on Oracle Linux.
Upgrade ORDS in Apache Tomcat
Run ords install from the new release folder with the same configuration folder to upgrade the schema, then replace ords.war in Tomcat's webapps folder with the new one and restart Tomcat. The setup is described in how to deploy ORDS in Apache Tomcat.
When You Upgrade APEX
Upgrading APEX itself is a separate job, but it affects ORDS: the static files ORDS serves at /i/ must match the APEX version in the database. After an APEX upgrade, replace the images folder that ORDS serves (standalone.static.path, or webapps/i in Tomcat) with the one from the new APEX download, and restart ORDS. Then check the version it serves.
Example:
curl -s http://localhost:8080/i/apex_version.js
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| ords --version still shows the old release | The PATH, a script, or a service still points at the old folder. Update it, or swap the folder names. |
| verify shows the old schema version | ords install was not run with the new release. Run it from the new folder with the same --config. |
| Address already in use when starting the new release | The old ORDS is still running. Stop it first. |
| APEX pages without styles after an APEX upgrade | The images folder is from the old APEX version. Replace it and check /i/apex_version.js. |
| HTTP 503 after the upgrade | ORDS cannot reach the database. Run ords config verify and check the database is open. |
Related Guides
Conclusion
To upgrade ORDS, unzip the new release into its own folder, stop ORDS, run ords install from the new folder with the same configuration folder to upgrade the schema, start the new release, and repoint your scripts or swap the folder names. On Linux with the repository package, use dnf upgrade ords and rerun ords install; in Tomcat, replace ords.war. After an APEX upgrade, always replace the images folder ORDS serves.
