10 Migration of Legacy Configuration

This section describes how to migrate the legacy configuration and the URL mapping.

Legacy configuration is any configuration of ORDS for versions starting with 2.x to version 21.4.x. These configurations need to be migrated to the new directory structure for 22.1 and higher versions of ORDS.

10.1 Migrating From Legacy Configurations Using the CLI Installation

To migrate your applications from legacy configurations, you can use the install command or the migrate config command.

You can migrate your applications from legacy configurations in the following two ways:

Migrating the Configuration and Upgrading ORDS

You use this option when you migrate your legacy configurations (ORDS 21.4.x or earlier versions) to a new configuration structure, and also upgrade ORDS in the database. You can perform this using one of the following two options:

Using the Interactive Install Command

If you use the interactive install command, then it migrates the legacy configurations to the new configuration structure. Then, depending on the options that you selected in the earlier steps of installation, it prompts you to either upgrade ORDS in the database, or create or update additional database pools. 

ords --config <configuration_folder> install --interactive 
--legacy-config <legacy_config_folder> --log-folder <log_folder>

Using the Non-Interactive Install Command

If you use the non-interactive install command, then you must specify the required information to migrate the configuration in the command line. 

ords --config <configuration_folder> install [--db-pool <pool_name>] --admin-user <user>
 --legacy-config <folder> --log-folder <log_folder> --password-stdin <  <text-file>

Migrating the Configuration Only

You use this option when you only migrate your legacy configurations (ORDS 21.4.x or earlier version) to a new configuration structure, but do not upgrade ORDS to a newer version.

ords --config <configuration_folder> migrate config <legacy_config_folder>

When migrating the configuration completes, the following message is displayed:

Legacy configuration files located at <legacy_config> are no longer being used to configure ORDS
 or its connection pools. Your migrated configuration files are now located at <configuration_folder>.

Parent topic: Migration of Legacy Configuration

10.2 Migrating URL Mapping

The legacy URL mapping file is /path/to/conf/url-mappings.xml that contains different types of mappings.

The installer migrates the url-mappings. For each url-mapping that contains the following type, it performs the following:

  • base-path type: creates a path file for that database-pool containing the base path (single or multiple path segments)
  • base-url type: creates a hostname file for that database-pool containing the hostname.

The base-path mapping pattern may contain a path that consists of a single segment or multiple segments.

Example:
  • /sales
  • /pls/hr

The base-url mapping pattern may contain only the hostname, or it can include the protocol, hostname, and path.

Example:

https://example.com/ords/support

www.sales.com

The ORDS install CLI migrates the url-mapping.xml as follows:

For each base-path type mapping (for example, /sales), the path is added to the paths file of the pool.

Note:

If the paths file does not exist, it is created.

For each base-url type mapping (for example https://example.com/ords/support), the hostname (for example example.com) is added to the hostnames file of the pool.

If the base-url mapping contains a path after the context (for example, /ords), then the path (for example, /support) is added to the paths file.

Note:

If the hostnames or paths files do not exist, then it is created.

Note:

A SEVERE warning message is displayed if:
  • Duplicate paths or hostnames across different database pools exist
  • The database pool that the mapping points to does not exist
  • The hostname or path is invalid

Note:

The name of the directory that contains the pool.xml configuration file is used in the request URL path mapping. When you are migrating a url-mapping.xml file, the pool name from that file is used as the directory name. There is a possibility that a pool name overlaps with an entry in the paths file from another pool definition. The pool name takes precedence in the request URL mapping.
The following is an example url-mapping.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<pool-config xmlns="http://xmlns.oracle.com/apex/pool-config">
 <pool name="db1" base-path="/sales" updated="2021-09-23T19:22:19.944Z"/>
 <pool name="db1" base-path="finance/" updated="2021-09-23T19:22:50.189Z"/>
 <pool name="db2" base-url="https://example.com/ords/support" updated="2021-09-23T19:23:04.751Z"/>
 <pool name="db3" base-path="/pls/hr" updated="2021-09-23T19:23:14.832Z"/>
 <pool name="db4" base-path="employee" updated="2021-09-23T19:23:24.252Z"/>
 <pool name="db5" base-url="www.sales.com" updated="2021-09-23T19:23:35.322Z"/>
</pool-config>

Example after migrating the url-mappings to the database pools folder:

+- databases/
  +- db1/
    +- pool.xml
    +- paths     // contains: [sales, finance]
  +- db2/
    +- pool.xml
    +- hostnames // contains: [example.com]
    +- paths     // contains: [support]
  +- db3/
    +- pool.xml
    +- paths     // contains: [/pls/hr]    
  +- db4/  
    +- pool.xml
    +- paths     // contains: [employee]    
  +- db5/
    +- pool.xml
    +- hostnames // contains: [www.sales.com]

Parent topic: Migration of Legacy Configuration