New Features

• The ords-metrics utility has been updated to include new JMX configuration options, enhanced metric dimensions, and configuration with the OCI Logging Service.
• Data Pump APIs now supports keep_master parameter for the db-api/database/datapump/import and db-api/database/datapump/export endpoints.

 

Bug Fixes

GENERAL

• 38740206 REST handlers resolved to incorrect endpoint within the same database
• 26168830 AutoREST-enabled PL/SQL procedures with an out parameter of BOOLEAN datatype failing with 500 Server Error Response when POST requests were issued
• 37979736 PL/SQL Gateway proxy user unable to connect to target schema failing with 571 Database Connection Error; error messages will no longer include pool-specific and target schema details
• 38406575 Failed Basic Dynamic Authentication attempts in Direct PL/SQL Gateway mode resulted in multiple entries in DB UNIFIED_AUDIT_TRAIL table logs; resulting in some locked out users
• 38389389 ORDS installer displays "Cannot drop ORDS_METADATA.ORDS_HTTP: ORA-01031: insufficient privileges when upgrading ORDS" despite successful ORDS upgrade
• 38139174 Execution of the ORDS_EXPORT.EXPORT_SCHEMA()failed to include the p_mle_env_name parameter in the output
• Execution of a SELECT statement on a table that contains SDO_GEOMETRY data returns an invalid JSON payload.

SQL DEVELOPER WEB

• 38498494 ORDS AutoREST-Enabled BATCHLOAD endpoint fails on Windows
• 38500287 SQL Developer Web displaying incorrect Command Prompt (Windows) BATCHLOAD cURL command example for Auto-REST enabled endpoints
• 38448663 "Get Bearer Token" menu option missing from a user-created ORDS OAuth2.0 Client Credential OAuth Client card
• 38423618 Share Query Results URL failed to include recently added table data
• 38434677 Share Query Results URL for larger result displaying only 500 rows
• 38570906 "Create MLE environment" slider rendering incorrectly when viewed in Chrome and Firefox browser
• 38448663 The "Get New Token" menu option of an ORDS OAuth2.0 Client Credentials client missing
• 38485320 Data Load operation in SQL Worksheet fails intermittently with ORA-00904 error message
• 38244663 Customer experienced high page load times for the Data Studio Feed Data Details page

 

Discover

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

• Download the Oracle SQL Developer Extension for VSCode today.

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

Enhancements

• Expanded instructions for configuring JMX metrics and OCI Logging Services for the ords-metrics utility.
• Updated ORDS Developer's Guide Troubleshooting section to include details on the debug.printOWADebug configuration parameter.
• Updated the ORDS Installation checklist (of the ORDS Installation and Configuration Guide) to include guidance for deploying ORDS within Oracle Kubernetes Clusters.

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'.

 

Oracle Container Registry

• The Entrypoint.sh script for the ORDS container image has been updated to allow non-SYS users the ability to install ORDS (see README for examples).

 

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.