-
Notifications
You must be signed in to change notification settings - Fork 20
SDB Mid Tier Routing Services
-
Install Docker if not already installed on the target machine using instructions at : https://docs.docker.com/install/
-
Make sure docker is running by issuing a
docker -v
at the terminal -
Login to docker using your dockerhub creds by issuing a
docker login
at the terminal
The Mid-Tier routing (MTR) docker image can be built using the instructions in the README file.
docker pull oracle/sdb-mid-tier-routing-services:1.0.0
A tomcat container serving the following :
- REST APIs for retrieving swim lane details and shard info details given a sharding key.
- REST APIs for retrieving and administering the swim lane detail mappings on the swim lane cache.
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.
Once the MTR docker container has been started, you can make REST API calls to Mid-Tier routing services.
- 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
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 :
- 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
-
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
}
- 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
}
]
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 :
- 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
-
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
}
- 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).
Note : The onus of associating a shard name with a swim lane is on the application administrator / owner / privileged user. The swim lane naming and the details of the swim lane such as swimLane URL, must be added by the application admin, as using just the shard name as swim lane name may not be meaningful in the application domain.
API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#6456ac2d-fc6a-53ae-dade-6b60e7663b37
CURL for API
curl --location --request POST "http://localhost:8080/sdb-mid-tier-routing-services/swimLane" \
--header "Content-Type: application/vnd.oracle.sdb.mtr.swimlane.v1+json" \
--data "{
\"shardName\":\"mpositec\",
\"swimLaneName\":\"small-swimlane-1\",
\"swimLaneURL\": \"http://localhost:10000/api/invoice/\"
}"
Description : Given a shardName retrieved from the Retrieve shard details for a shard key REST API, its corresponding swim lane name (user defined specific to the application) and swim lane url (user defined specific to the application), the REST API responds with a 200 OK for a successful association. On failure expect 4XX or 5XX HTTP error codes to indicate failure in association.
There are two aspects to this REST API :
- 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.swimlane.v1+json
-
Fields of the request body :
shardName → a valid shardName retrieved from the Retrieve shard details for a shard key REST API. swimLaneName → corresponding swim lane name (user defined specific to the application). swimLaneURL → swim lane url (user defined specific to the application) which may be an FQDN or IP for example an application load balancer or a gateway or a data API endpoint or an web / app server address amongst others.
Swim lane association request body example
{
"shardName":"mpositec",
"swimLaneName":"small-swimlane-1",
"swimLaneURL": "http://localhost:10000/api/invoice/"
}
Note : This API will return a non-empty, successful response only when there is a mapping already established between shardName(s) and the swim lane whose details are to be retrieved. To establish a mapping / association please refer to Associate shard name with a swim lane REST API.
API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#91be24a7-dc57-f35e-1828-b437d72b883a
CURL for API
curl --location --request GET "http://localhost:8080/sdb-mid-tier-routing-services/swimLane/mpositec" \
--header "Content-Type: application/vnd.oracle.sdb.mtr.swimlane.v1+json"
Description : Retrieve the swim lane details given a swim lane name in the path parameter. On failure expect 4XX or 5XX HTTP error codes to indicate failure in retrieval.
There are two aspects to this REST API :
- 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.swimlane.v1+json
- Path Parameter : The path parameter swimLaneName must be substituted with a valid swimLaneName.
Path parameter
http://localhost:8080/sdb-mid-tier-routing-services/swimLane/{swimLaneName}
Note : The onus of updating the association of a shard name and its swim lane details is on the application administrator / owner / privileged user. The swim lane naming and the details of the swim lane such as swimLane URL, must be added by the application admin, as using just the shard name as swim lane name may not be meaningful in the application domain.
API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#272857b8-c68f-d249-4d21-1e9da12bf8cc
CURL for API
curl --location --request PUT "http://localhost:8080/sdb-mid-tier-routing-services/swimLane/mpositec" \
--header "Content-Type: application/vnd.oracle.sdb.mtr.swimlane.v1+json" \
--data "{
\"shardName\":\"mpositec\",
\"swimLaneName\":\"small-swimlane-1\",
\"swimLaneURL\": \"http://localhost:10000/api/invoice/\"
}"
Description : Given a valid and already associated shardName retrieved from the Retrieve shard details for a shard key REST API, its corresponding swim lane name (user defined specific to the application) and swim lane url (user defined specific to the application), the REST API responds with a 200 OK for a successful association. On failure expect 4XX or 5XX HTTP error codes to indicate failure in association.
There are two aspects to this REST API :
- 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.swimlane.v1+json
-
Fields of the request body :
shardName → a valid shardName retrieved from the Retrieve shard details for a shard key REST API. swimLaneName → corresponding swim lane name (user defined specific to the application). swimLaneURL → swim lane url (user defined specific to the application) which may be an FQDN or IP for example an application load balancer or a gateway or a data API endpoint or an web / app server address amongst others.
Swim lane association request body example
{
"shardName":"mpositec",
"swimLaneName":"small-swimlane-1",
"swimLaneURL": "http://localhost:10000/api/invoice/"
}
Note : This API will return a successful response 200 OK only when there is a mapping already established between shardName(s) and the swim lane whose details are to be deleted exists. To establish a mapping / association please refer to Associate shard name with a swim lane REST API. To retrieve a swim lane to be deleted please refer to Retrieve swim lane details REST API
API Reference : https://documenter.getpostman.com/view/754319/RznJmG4U#65fbe3fa-fc0e-96dd-c328-b55482187fe3
CURL for API
curl --location --request DELETE "http://localhost:8080/sdb-mid-tier-routing-services/swimLane/mpositec" \
--header "Content-Type: application/vnd.oracle.sdb.mtr.swimlane.v1+json" \
--data ""
Description : Delete the swim lane mapping given a swim lane name in the path parameter. Expect 200 OK on successful deletion. On failure expect 4XX or 5XX HTTP error codes to indicate failure in deletion.
There are two aspects to this REST API :
- 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.swimlane.v1+json
- Path Parameter : The path parameter swimLaneName must be substituted with a valid swimLaneName.
Path parameter
http://localhost:8080/sdb-mid-tier-routing-services/swimLane/{swimLaneName}