One ORDS server can serve several databases, or several pluggable databases of one container database, each through its own connection pool. You might use this to run a development PDB and a test PDB side by side, or to give each department its own database while keeping a single web tier to install, patch, and secure.
This guide shows how to add a pool, how ORDS maps pools to URLs, how to manage each pool's settings, and the one rule about APEX versions that a shared ORDS imposes.
These steps come from Oracle APEX 26.1 Book: The Complete Guide.
How Pools Map to URLs
The pool created by your first ords install is called default. Each further pool gets its own folder under databases/ in the ORDS configuration folder, with its own pool.xml and wallet, so each can have different connection settings, pool sizes, gateway modes, and features.
ORDS routes requests by URL. The default pool serves /ords/, and any other pool serves /ords/<pool name>/.
| Pool | Database | APEX URL |
|---|---|---|
| default | FREEPDB1 | http://server:8080/ords/apex |
| sales | A second PDB or database | http://server:8080/ords/sales/apex |
For how the configuration folder and pool settings work in general, see how to configure ORDS for Oracle APEX.
Step 1: Prepare the Second Database
The second database or PDB needs APEX installed, just like the first, if you want APEX there and not only REST services. Install it with apexins.sql and create its ADMIN account with apxchpwd.sql, as in how to install Oracle APEX 26.1 on Oracle Linux.
Install the same APEX version in every database that one ORDS serves. The static files at /i/ come from a single global setting, standalone.static.path, shared by all pools, and the files must match the APEX version in each database.
Step 2: Add a Pool with ords install
Run ords install again with the --db-pool option and a pool name, pointing at the second database. ORDS installs or upgrades its schema there and creates the new pool folder. Stop ORDS first, and replace SALESPDB with your service name.
Example:
read -rsp 'SYS password: ' SYS_PWD; echo echo "$SYS_PWD" | ords --config ~/apex-lab/ords-config install \ --db-pool sales \ --admin-user SYS \ --db-hostname localhost --db-port 1521 \ --db-servicename SALESPDB \ --feature-db-api true \ --feature-rest-enabled-sql true \ --feature-sdw true \ --gateway-mode proxied --gateway-user APEX_PUBLIC_USER \ --password-stdin unset SYS_PWD
As with the first database, look for "plsql.gateway.mode was set to: proxied" in the output. If it says disabled, APEX is not installed in that database yet.
Step 3: Check the Mapping
Start ORDS. Near the top of its output, it prints how pools map to URLs. With only the default pool, it shows one line:
Output (excerpt):
Mapped local pools from /Users/yourname/apex-lab/ords-config/databases: /ords/ => default => VALID
With the sales pool added, a second line maps /ords/sales/ to the sales pool. VALID means ORDS reached that database; anything else points to a connection problem in that pool. Then open http://localhost:8080/ords/sales/apex to reach the second database's workspace sign-in page.
Step 4: Manage Each Pool's Settings
Every ords config command works on the default pool unless you add --db-pool. List, size, and verify the sales pool separately.
Example:
ords --config ~/apex-lab/ords-config config --db-pool sales list ords --config ~/apex-lab/ords-config config --db-pool sales set jdbc.MaxLimit 20 ords --config ~/apex-lab/ords-config config --db-pool sales verify
Size each pool for its own users, and remember that all pools together share the memory of the ORDS server and, for PDBs in one container database, the processes and sessions limits of that database. Restart ORDS after changing settings.
Global and Pool Settings
| Shared by all pools (global) | Separate for each pool |
|---|---|
| Ports, context path, HTTPS, access logs | Database host, port, and service name |
| APEX static files (standalone.static.path) | Users and wallet passwords |
| security.httpsHeaderCheck behind a proxy | Gateway mode and jdbc.* pool sizes |
| Features such as SQL Developer Web and REST-Enabled SQL |
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| 404 at /ords/sales/apex | The pool is missing, misspelled in the URL, or its gateway is disabled. Check the mapping lines and ords config --db-pool sales get plsql.gateway.mode. |
| The pool's mapping line is not VALID, or 503 on its URLs | ORDS cannot reach that database. Run ords config --db-pool sales verify and check the service name. |
| One database's APEX pages lose their styles | The databases run different APEX versions. Upgrade them to the same release as the shared images folder. |
| A setting change affects every database | It was a global setting, or --db-pool was left out. Check the Source column of ords config list. |
Conclusion
To serve several databases from one ORDS, install the same APEX version in each, run ords install again with --db-pool and the new database's connection details, and restart ORDS. The default pool answers at /ords/ and each other pool at /ords/<pool name>/, with its own pool.xml, wallet, and sizes that you manage with ords config --db-pool.
