Oracle REST Data Services 20.4.1.r0131644

Release Notes

Date: January 2021

Oracle REST Data Services on oracle.com

Support

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

Getting Started

Feedback

Important Concepts to Keep In Mind

Removal of PDF Generation Support

As previously advised in the ORDS 18.4.0 Release Notes, the Apache FOP based functionality to produce PDF Reports from Oracle Application Express has been removed in this release. This feature has also been removed from Oracle Application Express 19.2. Customers using older versions of Oracle Application Express are recommended to upgrade to newest version.

SQL Developer Web

SQL Developer Web is an ORDS hosted web application giving Oracle Database users an interface for executing queries and scripts, creating and altering database objects, building data models, accessing Performance Hub, and viewing database activity. Please consult the ORDS documentation library for instructions on how to enable this feature, which is disabled by default. Please access the SQL Developer Web documentation library for an overview of features and capabilities.

For consistent representation of date values in SQL Developer Web, ORDS should be run in the UTC timezone. This can be done as follows 

java -Duser.timezone=UTC -jar ords.war standalone

The SDW user interface now uses a number of services from the ORDS Database API. Therefore the Database API must be enabled when using SQL Developer Web.

Performance of REST APIs

Performance of ORDS based REST APIs was significantly improved in ORDS 19.3.0 by changing how ORDS handles proxied database connections. In ORDS 19.2.0 and earlier, for each HTTP request ORDS proxies from ORDS_PUBLIC_USER to the relevant ORDS enabled schema, performs the relevant database calls and then closes the proxy session. We term this behavior 'disposing' a connection.

In ORDS 19.3.0 and later ORDS changes its default behavior to keep proxied connections in the pool, ameliorating away the cost of opening and closing the proxy sessions. This gives a very substantial performance improvement. We term this behavior 'recycling' a connection.

Reverting to Previous behavior

ORDS Administrators may revert to the old behavior of 'disposing' connections by performing the following command: 

java -jar ords.war set-property jdbc.cleanup.mode dispose

To switch to recycling connections use:

java -jar ords.war set-property jdbc.cleanup.mode recycle

Managing Connection Re-use

To mitigate against database code that is leaking resources, ORDS has a configuration setting: jdbc.MaxConnectionReuseCount which controls how many times ORDS will use a database session before terminating it (and releasing the leaked resources) and replacing it with a new database session. The default value for this setting is 1000. If you are experiencing database resource exhaustion you should:

Installer Behavior Using the install or setup Command

In ORDS 19.3.0, the installer does not automatically update the ORDS parameter file (default ords parameter file or user-specified ords parameter file) when you use the following commands:

If you want the same behavior to update the ords parameter file, you will need to use the --saveParameters option.

Example:

Supported Java Version

Oracle REST Data Services requires Java 8 or later. Java 7 is no longer supported. Please consult the documentation for the minimum supported Application Server versions for ORDS.

Changes in 20.4.1

The following changes have been made since 20.3.1:

Issues Fixed in 20.4.1

New Features in 20.4.1

Changes in 20.3.1

The following changes have been made since 20.3.0:

Issues Fixed in 20.3.1

Changes in 20.3.0

The following changes have been made since 20.2.3:

Issues Fixed in 20.3.0

New Features in 20.3.0

Changes in 20.2.3

The following changes have been made since 20.2.2:

New Features in 20.2.3

Changes in 20.2.2

The following changes have been made since 20.2.0:

Issues Fixed in 20.2.2

Changes in 20.2.0

The following changes and enhancements have been made since 20.1.0:

Issues Fixed in 20.2.0

New Features in 20.2.0

Changes in 20.1.0

The following changes and enhancements have been made since 19.4.5:

Issues Fixed in 20.1.0

New Features in 20.1.0

Changes in 19.4.6

The following changes and enhancements have been made since 19.4.0:

Issues Fixed in 19.4.6

New Features in 19.4.6

Changes in 19.4.0

The following changes and enhancements have been made since 19.3.0:

Issues Fixed in 19.4.0

New Features in 19.4.0

Changes in 19.3.0

The following changes and enhancements have been made since 19.2.0

Issues Fixed in 19.3.0

New Features in 19.3.0

Changes in 19.2.0

The following changes and enhancements have been made since 19.1.0:

Issues Fixed in 19.2.0

New Features in 19.2.0

Changes in 19.1.0

The following changes and enhancements have been made since 18.4.0:

Issues Fixed in 19.1.0

New Features in 19.1.0

Changes in 18.4.0

The following changes and enhancements have been made since 18.3.0:

Issues Fixed in 18.4.0

New Features in 18.4.0

Earlier versions

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

Known Issues

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

SODA

JDK Support

TNS Connections

When using a TNS connection type the JDBC driver needs to know the location of the folder containing tnsnames.ora. To configure this when running ORDS in standalone mode do: 

java -Doracle.net.tns_admin=$ORACLE_HOME/network/admin -jar ords.war

(where $ORACLE_HOME points to the folder where Oracle Database/Oracle Instant Client is installed)

If using Tomcat or WebLogic, then the startup script used to start the app server would need to be modified to pass the -Doracle.net.tns_admin=$ORACLE_HOME/network/admin argument to the java command that starts Tomcat/WebLogic

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

RESTful Services

Support For mod_plsql logmeoff

Starting Standalone Mode when connected to CDB

The typical manner to start ORDS in standalone mode, once ORDS has been configured is:

java -jar ords.war

ORDS will detect that it is fully configured and proceed to launching standalone mode. Since 18.2 the ORDS_METADATA schema is not installed in the CDB, which means that when the default pool is connected to a CDB there is no way for ORDS to automatically verify the version of the ORDS schema installed in the database, thus ORDS prompts for the SYS AS SYSDBA password so it can connect to each PDB and verify the ORDS version installed in each PDB. This means that when connected to a CDB the above command is not sufficient to start standalone mode automatically. To work around this issue, use the following command to start ORDS (only after the ORDS instance has been configured) in standalone mode automatically: 

java -jar ords.war standalone

Support for apex.docTable