New Features

ORDS

• Introduced a new ORDS_PAR.PAR_EXPIRATION_BY_ALIAS(); function which retrieves a PAR’s remaining time till expiration (in seconds), by passing the PAR alias as a parameter.
• Improved MLE/JS error stack messages. A new “MLE” exception prefix has been added for improved logging. New prefix also viewable when the ORDS printDebugToScreen configuration setting has been set to TRUE. Stack traces are now available for MLE/JS resource errors.
• The ORDS REST-Enabled SQL Service Response Specification for Content-Type: application/json requests adds a new responseFormat.numberAsString property for specifying whether numeric values should be returned as strings (to retain precision and scale).
• The /apex/applications/{application_id} DB-API endpoint introduces two new parameters:
  • withRuntimeInstances
  • with_audit_Info
• Customer-managed ORDS deployments can now use Database Tools in OCI (managed connections service) Instance Principal and OCI Profile credentials when selecting a db.connectionType. The default remains basic (i.e. ORDS_PUBLIC_USER).

SQL Developer Web

• The REST Workshop now supports ORDS Pre-Authenticated Requests (PARs):
  • PAR dashboard accessible by navigating to Security > Pre-Authenticated Requests. + Resource
  • Resource Handlers now feature a new Pre-Authenticated Request context menu option, with Create and Details actions.

ORDS CLI

• New ords config --db-pool [pool name] verify command. When executed, will respond with a message stating whether the pool is valid or not. And if ORDS is installed in the database, will return the ORDS (metadata) version number.
• Users can now optionally configure JWT Profiles at the database pool level, with the security.jwt.profile.mode command. Schema level remains default, however pool level configuration supports Roles-Based and Claims-Based Access Control methods as well.

Bug Fixes

ORDS

• 37721769 ORDS OAuth2 Client Credential grant types failed with a 401 Unauthorized Status Code when a user requests a Privilege-protected resource. Privileges should be ignored for 2-Legged Flows (Client Credentials) was . should ignore assigned privileges for 2 legged flows, as only ORDS Roles assigned to the the clients are applicable.
• 37823479 P_ROLE_CLAIM_NAME validation for Roles-Based Access Control JWT Profiles. Stricter validation rules are enforced for JSON Pointers (e.g. leading “/”).

SQL Developer Web

• 37782162 Client Secret modal incorrectly appears after creation of an ORDS OAuth2.0 Implicit Grant Type client.
• 37477571 SQL Worksheet keyboard shortcuts have been corrected to align with those present in the Monco Editor (i.e. VS Code).
• 37969152 BLOB files corrupted after downloading the results from the SQL Worksheet (and updating with the correct file extension).
• 37809616 Users received a “Data Log Report Error” when clicking the Next button in the Data Load or Data Link tab of a Data Studio Data Marketplace listing.
• 34497498 Refreshing the Data Studio Data Load UI during a local file data load kills the process and results in an incomplete data load.
• 34497363 Refreshing the Data Studio Data Load UI during a Cloud Store data load kills the process and results in a total failure.
• 34015805 Live Feed run details section in the Data Load UI failed to display the execution details when files are processed in chunks.

Discover

• Learn more about the ORDS PAR PL/SQL Package.

• Download the Oracle SQL Developer Extension for VSCode today.

Library updates

• ORDS Standalone has been updated to include Jetty version 12.0.18

Supported Java Versions

Oracle REST Data Services requires Java 17, or 21. The supported Java Runtime Environments are:

• Oracle Java 17
• Oracle Java 21
• Oracle GraalVM Enterprise Edition for Java 17
• Oracle GraalVM Enterprise Edition for Java 21

Note that GraphQL support requires GraalVM Enterprise Edition for Java 17 or later.

Please consult the documentation for the minimum supported Application Server versions for ORDS.

Support

• Supported by Oracle Support under your current Oracle Database Support license for Oracle REST Data Services production releases.
• Log Oracle REST Data Services bugs and issues using My Oracle Support.
  • For problems specific to SODA for REST, file a service request using "Oracle XML Developers Kit" as the product.
  • For all other problems, use "Oracle REST Data Services" as the product.

Note - Autonomous Database Shared Subscribers

If you are running a customer-managed ORDS for your Autonomous Transaction Processing, Autonomous Data Warehouse, or Autonomous JSON Database, you must upgrade your customer-managed ORDS to the version used in your Autonomous Database Shared environment. Failure to do so could lead to service disruptions.

To determine the version of ORDS in your Autonomous Database Shared database run this query:

select ords.installed_version from dual;

Documentation

General

• Documentation for this release is provided on the oracle.com web site. Click here to view the documentation and related information.
• Documentation on using SODA for REST is provided on the oracle.com web site. Click here, navigate to the documentation section and access the book titled 'SODA for REST'.

Getting Started

• A tutorial on getting started with developing RESTful Services is included in the ORDS product documentation, in the book titled 'Oracle REST Data Services Quick Start Guide'.

 

Known Issues

ORDS version 24.4, when in Standalone mode, enforces stricter URL redirection.

URIs with and without trailing slashes are considered distinct. Previously, where a 302 Temporarily Moved redirect was permitted, users may instead receive a 301 Moved Permanently response status code. ORDS 24.4 Standalone conforms to the HTTP specification found in RFC7230. ORDS customer-managed users and OCI users that consume ORDS resources should plan accordingly for this new behavior. You may review the specification here.

Oracle Database may report 'ORA-01031: insufficient privileges' for queries that involve CURSOR expressions

In a number of cases, ORDS executes queries which include a CURSOR expression. An issue has been found executing these queries for some schemas in Oracle 18c and Oracle 19c databases. Depending on the roles and privileges involved, the issue does not occur for all schemas, which can give the impression that the issue is intermittent. Refer to RDBMS bug 29049673 for more information. The issue is manifest as follows in the exception returned:

ORA-00604: error occurred at recursive SQL level 1

ORA-01031: insufficient privileges

This is a problem with view-merging of nested cursors introduced in Oracle 18.1 database. Please use the following as a workaround:

alter system set "_fix_control"='20648883:OFF';

 

Oracle Database DATE and TIMESTAMP values

ORDS interprets Oracle Database DATE and TIMESTAMP values (which do not possess a time zone) into the time zone of ORDS. These values are then represented in the RFC3339 UTC format.

In a future release Oracle Database DATE and TIMESTAMP values will not by default be interpreted into any time zone. These values will be represented in the ISO 8601 "yyyy-mm-ddThh:mm:ss[.sss]" format. Oracle Database TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE values will remain represented in the RFC3339 UTC format.

SQL Developer Web

• DATE, TIMESTAMP, TIMESTAMP WITH TIMEZONE values downloaded from the Worksheet Query Result in the JSON format are not presented in the Internet Datetime format.

JDBC Array values

ORDS passes array values to the Oracle Database in a number of cases, for example arrays are used to pass the request headers and form fields during PL/SQL Gateway calls. Oracle JDBC Driver 18.3 and later supports an improved mechanism for passing array values, however this feature is only supported on Oracle Database 12c and later. Thus ORDS uses existing deprecated and less efficient APIs for passing array values when connecting to 11G databases, and the improved mechanism when connected to 12c and later. Customers experiencing problems with passing large array sets (for example OutOfMemory exceptions) are encouraged to upgrade from 11G to a newer database version to mitigate these issues.

Autogenerated REST Endpoints

• AutoRest resources support the OAuth 2.0 Client Credentials flow only.

 

RESTful Services

• Application Express workspaces do not support first party authentication, and therefore do not support the /sign-in/ interactive sign in form. Accessing /sign-in/ in APEX workspaces will produce a 404 status.

 

Support For mod_plsql logmeoff

• The mod_plsql logmeoff mechanism is not supported reliably by modern browsers and it is not provided by ORDS. The only way to end a HTTP Basic Authentication session is to close the Browser.

 

Feedback

• At Oracle REST Data Services on oracle.com you will find links to forums and social media channels where you can discuss topics with the ORDS community around the world and leave feedback for the development team.
  • In the forums, be sure to use clear subject lines to initiate a thread. Provide a complete and clear description of the issue, including steps to reproduce the issue.
  • Try to avoid using old, unrelated threads for a new issue.

 

Important Concepts to Keep In Mind

Revised Command Line Interface and Configuration Directory Structure

Command Line Interface

The java commands serviced from the WAR file are no longer supported. Attempting to run the following:

java -jar ords.war standalone

 

Will result in an error message, referring you to the docs. Instead you would run:

ords --config /path/to/config serve

 

Installation & Configuration

The ORDS program or script in the bin directory can be used to perform installs, changes to your configuration, changing the database passwords for your connection pools, and for creating ORDS users. To see a list of commands:

ords --help

 

Configuration Files Directory Layout

If upgrading from a previous version of ORDS, your existing configuration directory for ORDS and the files contained therein will be migrated to a new layout for versions 22.1 and higher.

You may migrate your settings using the ORDS migrate command, or you may perform a 22.1 install which will prompt ORDS to migrate your existing ORDS configuration to the new mapping for you.

ORDS standalone and default pool configuration settings are in a settings.xml file in a global subdirectory.

Connection pools are in a databases subdirectory. The intital database pool is named 'default' and has a '/' mapping pattern.

Subsequent pools will created such that the name of the pool also defines the mapping pattern.

 

SQL Developer Web

SQL Developer Web (SDW) is an ORDS hosted web application giving Oracle Database users the SQL Developer desktop experience in their browser.

SQL Developer Web provides a development interface for building and maintaining your ORDS based REST APIs, AUTOREST Enabled database objects, OAuth3 Clients, ORDS Privileges and Roles, as well as a SODA for REST graphical interface. For the best possible experience developer REST APIs for ORDS, we recommend you use SQL Developer Web.

For consistent representation of date values in SQL Developer Web, ORDS should be run in the UTC timezone. This is set automatically when using the ords command line interface. When deploying ORDS to Apache Tomcat or WebLogic Server the user.timezone may have to be set explicitly before starting the container.

-Duser.timezone=UTC

 

SQL Developer Web requires the Database API be enabled.

SQL Developer Web's DBMS_SCHEDULER interface requires database version 12.2 or higher.

 

Upgrading ORDS in the database

If you have previously executed script, ords_installer_privileges.sql, to grant your administrator user privileges to perform the install or upgrade, then you must execute the script again on that same user that you provided because additional grants have been added to this script. Note: This script does not apply to the SYS user account.

 

Deprecation Notice

The RESTful Services area of the SQL Workshop for building and managing ORDS REST APIs in APEX has been deprecated. The recommended web interface for managing your ORDS REST APIs is Database Actions, also known as, SQL Developer Web.

OAUTH2 PL/SQL API Improvements: PL/SQL interfaces for managing OAUTH2 clients (formerly found in the OAUTH and OAUTH_ADMIN PL/SQL Packages) have been consolidated and updated into two new packages: ORDS_SECURITY and ORDS_SECURITY_ADMIN. We've deprecated the OAUTH and OAUTH_ADMIN PL/SQL Packages

 

Earlier Release Versions

For information on Issues Fixed and New Features introduced for earlier versions please refer to the release notes for those versions.