Skip to content

SDB Mid Tier Routing Services

Jump to bottom
Bharath Ramaprasad edited this page Mar 15, 2019 · 13 revisions

Steps to install & access SDB Mid Tier Routing (MTR) services via Docker

  1. Install Docker if not already installed on the target machine using instructions at : https://docs.docker.com/install/

  2. Make sure docker is running by issuing a docker -v at the terminal

  3. Login to docker using your dockerhub creds by issuing a docker login at the terminal

SDB Mid-Tier Routing (MTR) Docker images

The Mid-Tier routing (MTR) docker image can be found at https://hub.docker.com/r/oraclesharding/oracle-sdb-mid-tier-routing-services

Pull the latest Mid-Tier routing image

docker pull oraclesharding/oracle-sdb-mid-tier-routing-services:latest

What is contained in the MTR docker image

A tomcat container serving the following :

  1. REST APIs for retrieving swim lane details and shard info details given a sharding key.
  2. REST APIs for retrieving and administering the swim lane detail mappings on the swim lane cache.

Running SDB Mid-Tier Routing services in a Docker Container

To pull & run SDB Mid-Tier routing docker image use the docker run command as follows

`docker run --name <container name> \
 -p <host port>:8080 
 -e CATALOG_USERNAME='<username>' \
 -e CATALOG_PASSWD='<password>' \
 -e CATALOG_URL='<jdbc:oracle:thin:@hostname:port:sid>' \ 
 -e CATALOG_SVC_NAME='<catalog-service-name> (default : '')' \
 -e SWIM_LANE_CACHE_HOST='<cache host> (default : '')' \
 -e SWIM_LANE_CACHE_PORT='<cache port> (default : '')' \
 -e SWIM_LANE_CACHE_TYPE='<local | redis>' \
 oraclesharding/oracle-sdb-mid-tier-routing-services:latest`

 Parameters:

 --name:                   The name of the container (default: auto generated)
 -p:                       The port mapping of the host port to the container port. One port is exposed: 8080
 -e CATALOG_USERNAME:      Catalog user's username
 -e CATALOG_PASSWD:        Catalog user's password 
 -e CATALOG_URL:           JDBC Connect String to the catalog database 
 -e CATALOG_SVC_NAME:      Service name of the catalog  
 -e SWIM_LANE_CACHE_HOST:  The swim lane cache hostname that MTR should use
 -e SWIM_LANE_CACHE_PORT:  The swim lane cache port that MTR should use                          
 -e SWIM_LANE_CACHE_TYPE:  Swim lane cache type. Value can either be local or redis. 
                           local refers to an in-built cache within the container. 
                           REDIS refers to an external REDIS server instance.
  • Local in-memory cache mode

In this mode, the cache is local and in-memory. So if the container goes down the swim lane details are lost. So the swim lane mappings needs to be established again.

This mode is recommended if the number of shards or the swim lane mappings aren't too large.

Local mode example :

`docker run --rm --name oracle-sdb-mtr-latest \
-p 8080:8080 \
-e CATALOG_USERNAME='app_schema' \ 
-e CATALOG_PASSWD='app_schema' \
-e CATALOG_URL='jdbc:oracle:thin:@localhost:1521:composite' \
-e CATALOG_SVC_NAME='' \ 
-e SWIM_LANE_CACHE_HOST='' \
-e SWIM_LANE_CACHE_PORT='' \
-e SWIM_LANE_CACHE_TYPE='local' \
 oraclesharding/oracle-sdb-mid-tier-routing-services:latest`
  • External REDIS cache mode

In this mode, the user is responsible here to start the REDIS instance and pass in the necessary parameters for the sdb mid-tier routing docker container. As the cache is external and running in its own container, even if the sdb-mtr container goes down, the swim lane mappings are not lost.

This mode is recommended if the number of shards or the swim lane mappings are large and you need or already using a distributed cache like REDIS.

REDIS mode example :

`docker run --rm --name oracle-sdb-mtr-latest \
-p 8080:8080 \
-e CATALOG_USERNAME='app_schema' \ 
-e CATALOG_PASSWD='app_schema' \
-e CATALOG_URL='jdbc:oracle:thin:@localhost:1521:composite' \
-e CATALOG_SVC_NAME='' \ 
-e SWIM_LANE_CACHE_HOST='192.168.0.2' \
-e SWIM_LANE_CACHE_PORT='6379' \
-e SWIM_LANE_CACHE_TYPE='redis' \
 oraclesharding/oracle-sdb-mid-tier-routing-services:latest`

SDB Mid-Tier Routing services REST API documentation

1. Retrieve swim lane details for a shard key

API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#72e8c15f-4267-a03c-f5f4-a00722478cc8

CURL for API

curl --location --request POST "http://localhost:8080/sdb-mid-tier-routing-services/shardDetails/swimLane" \
     --header "Content-Type: application/vnd.oracle.sdb.mtr.sk.datatype.mixed.swimlane.v1+json" \
     --data "[
         {
           \"shardKeyType\":\"number\",
           \"shardKeyValue\":\"2000\",
           \"isSuperShardKey\": false
         },
         {
           \"shardKeyType\":\"varchar2\",
           \"shardKeyValue\":\"small\",
           \"isSuperShardKey\": true
         }
        ]"

Description : Given a shard key and optionally a super shard key, this API will retrieve any pre-associated/pre-defined swimlane details corresponding to the sharding keys on success. On failure expect 4XX or 5XX HTTP error codes.

This API supports all datatypes that are supported by JDBC for sharded database. Refer the following link for all supported data types : https://docs.oracle.com/en/database/oracle/oracle-database/12.2/jjdbc/database-sharding.html#GUID-4B151856-8B27-470C-B7DA-016FCBF97638 .

There are three aspects to this REST API :

  1. Content Type : The client invoking this REST API must include the following content type in its header :

Content type header

application/vnd.oracle.sdb.mtr.sk.datatype.mixed.swimlane.v1+json

  1. Fields of the request body :

    shardKeyType → needs to be one of the supported jdbc types. shardKeyValue → value of the shardKey. isSuperShardKey → boolean for denoting whether this is a super shard key or not.

Sharding key example

 {
   "shardKeyType":"number",
   "shardKeyValue":"1000",
   "isSuperShardKey": false
 }
  1. Order of the sharding keys

The order of the sharding keys is important and needs to correspond for example how a composite sharding key is defined in the sharded database table.

Order of shard keys example

[
  {
    "shardKeyType":"number",
    "shardKeyValue":"1000",
    "isSuperShardKey": false
  },
  {
    "shardKeyType":"varchar2",
    "shardKeyValue":"small",
    "isSuperShardKey": true
  }
]

2. Retrieve shard details for a shard key

API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#83897420-eb34-b29a-7aed-bf72bd6be396

CURL for API

 curl --location --request POST "http://localhost:8080/sdb-mid-tier-routing-services/shardDetails" \
      --header "Content-Type: application/vnd.oracle.sdb.mtr.sk.datatype.mixed.v1+json" \
      --data "[
                {
                  \"shardKeyType\":\"number\",
                  \"shardKeyValue\":\"1000\",
                  \"isSuperShardKey\": false
                },
                {
                  \"shardKeyType\":\"varchar2\",
                  \"shardKeyValue\":\"small\",
                  \"isSuperShardKey\": true
                }
              ]"

There are three aspects to this REST API :

  1. Content Type : The client invoking this REST API must include the following content type in its header :

Content type header

application/vnd.oracle.sdb.mtr.sk.datatype.mixed.v1+json

  1. Fields of the request body :

    shardKeyType → needs to be one of the types mentioned above. shardKeyValue → value of the shardKey. isSuperShardKey → boolean for denoting whether this is a super shard key or not.

Sharding key example

 {
   "shardKeyType":"number",
   "shardKeyValue":"1000",
   "isSuperShardKey": false
 }
  1. Order of the sharding keys

The order of the sharding keys is important and needs to correspond for example how a composite sharding key is defined in the sharded database table.

Order of shard keys example

[
  {
    "shardKeyType":"number",
    "shardKeyValue":"1000",
    "isSuperShardKey": false
  },
  {
    "shardKeyType":"varchar2",
    "shardKeyValue":"small",
    "isSuperShardKey": true
  }
]

Note : If there are multiple shard names returned, then there is a replication setup for a shard, wherein one is the primary and the other a standby in the case of a active / passive setup (Example : Dataguard) or both can be the masters in a active-active setup (Example : Goldengate).

Clone this wiki locally