1. Installation and Configuration Guide
  2. Configuring Oracle REST Data Services for Multiple Databases

3 Configuring Oracle REST Data Services for Multiple Databases

Oracle REST Data Services supports the ability to connect to more than one database. This section describes different strategies for routing requests to the appropriate database.

3.1 About the Request URL

Oracle REST Data Services supports a number of different strategies for routing requests to the appropriate database. All of these strategies rely on examining the request URL and choosing the database based on some kind of match against the URL. It is useful to recap the pertinent portions of a request URL. Consider the following URL:

https://www.example.com/ords/sales/f?p=1:1

This URL consists of the following sections:

  • Protocol: https

  • Host Name: www.example.com

  • Context Root: /ords

    The context root is the location at which Oracle REST Data Services is deployed on the application server.

  • Request Path: /sales/f?p=1.1

    This is the portion of the request URL relative to the context root.

For different applications, it may be important to route requests based on certain prefixes in the request path or certain prefixes in the full request URL.

There are two steps to configuring multiple databases:

  1. Configuring the database connection information

  2. Configuring which requests are routed to which database

3.2 Configuring Additional Databases

When you first configure Oracle REST Data Services, you configure a default database connection named: default. You can create additional database connections using the install command.

Tip:

To see full help for the install command type: 

ords install --help
For adding additional database connection pool, enter the following command:
ords --config <configuration folder> install
You get the following prompts: 
Oracle REST Data Services - Interactive Install

  Enter a number to select the type of installation
    [1] Install or upgrade ORDS in the database only
    [2] Create or update a database pool and install/upgrade ORDS in the database
    [3] Create or update a database pool only
  Choose [1]:
Select option 2

Enter a number to select the database pool to update, or create an additional database pool.
  The selected (or created) database pool will be used to install or upgrade ORDS in the database.
    [1] default      jdbc:oracle:thin:@//localhost:1521/orcl
    [2] Create an additional database pool
  Choose [1]:

Select option 2

Enter the database pool name:

Enter db2

This becomes the mapping pattern for your new pool. Continue answering the prompts, similar to first time setup of the default pool.

See Also:

Interactive Command-Line Interface Installation

3.3 Advanced Routing

By default, additional databases are mapped using the database pool name specified while installing ORDS. Alternatively, custom mapping can be performed based on a path prefix or a hostname as described in the following sections.

Note:

If custom mapping is configured, then default mapping with database pool name is not enabled.

See Also:

Configuring Additional Databases

3.4 Routing Based on the Request Path

You can create the request routing rules based on the request path using the paths file. To do this, perform the following steps:
  1. Open or create a file <ords_config_folder>/databases/<database_name>/paths
  2. Enter the paths that you want to be served by this database.

Example location of the paths file

ords_conf/
+-- databases/
|   +-- db1/
|   |   +-- wallet/
|   |   +-- paths
|   |   +-- pool.xml
|   +-- db2/
|       +-- wallet/
|       +-- paths
|       +-- pool.xml
+-- globals/
Example: ords_conf/databases/db1/paths
sales
Example: ords_conf/databases/db2/pathsords_conf/databases/db2/paths
support
/finance/department1

The previous rules match all the following requests:

http://example.com/ords/sales --> db1
http://example.com/ords/sales/leads --> db1
https://www.example.com/ords/sales/forecasting.report?month=jan --> db1 (If www.example.com resolves to the same system as example.com.)

http://example.com/ords/support --> db2
http://example.com/ords/finance/department1 --> db2

3.5 Routing Based on the Request Hostname

You can create request routing rules based on the hostname using the hostnames file. To do this, perform the following steps:

  1. Open or create a file <ords_config_folder>/databases/<database_name>/hostnames.
  2. Add the hostnames you want to be served by this database.
Example location of hostnames files:
ords_conf/
+-- databases/
|   +-- db1/
|   |   +-- wallet/
|   |   +-- hostnames
|   |   +-- pool.xml
|   +-- db2/
|       +-- wallet/
|       +-- hostnames
|       +-- pool.xml
+-- globals/

Example: ords_conf/databases/db1/hostnames

www.example.com
example.org
Example ords_conf/databases/db2/hostnames
foo.bar.com

The preceding rules match the requests to their corresponding database connection as follows:

http://www.example.com/ords/ --> db1
http://example.org:8080/ords/f?p=1:1 --> db1
https://foo.bar.com/ords/myschema/resource --> db2

The preceding rules do not match following requests:

http://example.com/ords/ (The hostname is missing the www.)
http://foo.bar.net/ords/myschema/resource --> db2 (hostname is different