8 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.
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>.
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.
/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
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]