Oracle REST Data Services (ORDS) 22.1 : All Change!


You may have heard version 22.1 of Oracle REST Data Services (ORDS) has been released. For the versions between 3.0 and 21.4 the installation process was pretty much the same. From version 22.1 it’s out with the old and in with the new…

I’ve put out an installation article, but remember it’s early days for me, so I will probably be revisiting this over the coming weeks as I learn more.

The Big News

  • We no longer run commands using “ords.war” directly. Instead we use an “ords” script/executable in the “bin” subdirectory. That kind-of makes every installation or configuration article you’ve ever read wrong.
  • The above change means standalone mode is also different, so even starting and stopping ORDS has changed.
  • The configuration location is no longer written into the “ords.war” file, so you have to make sure standalone, Tomcat, WebLogic knows where to find the config.
  • The contents/structure of the configuration has changed, so once again anything you’ve read about configuration has probably changed.

It all sounds quite dramatic, and it certainly confused the hell out of me, but I think a couple of weeks down the line I will forget it was ever any other way. πŸ™‚

I’ve updated one of my Vagrant builds to use the new version. I’ll do the others over time…

Over the next few days/weeks I’ve got to visit all my ORDS content (over 30 articles) to check how these changes have impacted it. Off the top of my head I think I’ve got about 3 rewrites to do, and some corrections of other articles.

Don’t Panic

From a usage perspective, ORDS looks the same, so there is no need to panic. It’s just one of those administration evolutions you expect in the lifetime of a product.



PS. I’ve been making Jeff Smith‘s life miserable regarding the documentation. Thanks for the feedback and changes Jeff. πŸ˜‰

Author: Tim...

DBA, Developer, Author, Trainer.

14 thoughts on “Oracle REST Data Services (ORDS) 22.1 : All Change!”

  1. Eric: Things have got to move forward. As ORDS has become more popular, certain aspects of its administration stick out as being not so good. This change makes the experience more consistent and better IMHO. It’s annoying to have to rewrite stuff, but I’m OK with it, provided it is for the better. Remember, usage of the product remains the same. It’s only installations that have changed.

  2. I was kidding! I know more people probably go to your site than Oracle’s for help!

  3. Hello! I have followed your instructions and installed ords 22.1 + tomcat on windows. Something must be wrong because ords throws 404 error when you start it.
    I have already checked that on the same machine/windows version: ords 22.1 standalone works and ords 21.4 + tomcat works. Could you please check the windows build and provide instructions on your article?
    Maybe there is a bug…
    Thank you in advance…

  4. Geo: I don’t use Windows for servers. I suspect you’ve not set the JAVA_OPTS environment variable, so ORDS under Tomcat doesn’t know where the config is. Check the Tomcat logs to see if the pools are initiated during the startup.

  5. I had an endless list of problems since switching from Apache based OHS to ORDS.
    I don’t know if it is just me, but I found it incredibly difficult to understand the documentation and create the required scripts to configure and install ORDS without user interaction.
    I was delighted to read that in 22.1 finally a proper cli is available but unfortunately things did not improve at all and I’m struggling as always.
    I basically only use the plsql-gateway and apex or any other components and am trying to setup a development environment using the standalone server and a production environment using tomcat.
    My latest config attempt looks something like this and only results in a 404 when trying to start my app at

    export ORDS_CONFIG=config
    ords install –config-only –feature-db-api false –feature-rest-enabled-sql false –feature-sdw false –db-pool lj-unittest –db-hostname –db-port 1521 –db-servicename TEST –gateway-mode direct –gateway-user LJ_UNITTEST –password-stdin $ORDS_CONFIG/databases/lj-unittest/paths
    ords serve

    Any hint on what I’m missing would be most appreciated.
    I also did not find any explanation in the documentation on how to exactly use the –gateway-mode option.

  6. As soon as I ran “java -jar ords.war install simple” trying to install ORDS V22 I got the “Error: A JNI error has occurred…” because I was trying to use JDK 1.8. That was when I realized I needed to read the documentation. ha. ORDS V22+ needs either Java 11 or 17. I figured I’d just need to research how to migrate to latest JDK v17. But now I read your notes and seems alot more has changed besides just requiring newer JDK. Time to put on my reading glasses.

  7. Tim: could you elaborate on your plsql gateway example. Why is the β€”admin-user argument needed and why is –gateway-mode set to proxied?

  8. Dieter: We are setting up a new connection, so we need –admin-user to connect to a privileged account, so that the necessary stuff can be done behind the scenes.

    The –gateway-mode is set to proxied, because ORDS will need to run as PLSQLUSER, to the ORDS_PUBLIC_USER will need to proxy to that account. This is similar to the way ORDS_PUBLIC_USER proxies to APEX_PUBLIC_USER when it is fronting APEX. It’s just another PL/SQL application…

    The easiest way to get to grips with this is to create a little test system and play around with it. Trying to work directly on a real system can be distracting. I’ve literally gone through all my articles testing them, to make sure I understand the impact of what I have tried.



  9. Tim: Do I need to specify an admin user because ORDS 22.1 now wants to run something in the database. Until now, this was not needed when only using the PLSQL gateway and would you know what exactly is run/installed? I’m still struggling to understand why I need the ORDS_PUBLIC_USER and then proxy to the actual one. Is this not what the –gateway-mode direct is for or what else would it be used for.

  10. Hi.

    There is a DIRECT option for running PL/SQL, but I don’t use it. I run stuff the same what APEX runs it. If I have time I’ll give it a go later and add it to the article. No promises.



Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.