Skip to content

Commit c8f731f

Browse files
SylajaKZackaryRice
SylajaK
and
ZackaryRice
authored
WMS ID: 11512 (oracle-livelabs#462)
* New folder for a new LiveLab Created a new folder with placeholder text for a new LiveLab * Added instructions to integrate MicroTx lib files * Instructions Updated image, instructions to run the sample app, integrate TMM files with sample app, and update the YAML file. * Updated tags and tasks Restructured the content. * Changes to manifest file * Purchase and sale of stocks * replaced XA sample app with Banking and Trading app * updated intro * uncomment lines without going through details * incorporated feedback * Updated images for ATP instances * Self QA Fixed issues that were identified during self QA. * updated links to tasks within page * Self QA checks * More self QA changes * added lab 2 * MTRM-1123 Incorporated feedback received from the QA team. * Incorporated feedback Incorporated feedback received from the LiveLabs team * Update screenshots for Lab 4 Added screenshots for Lab 4: ATP-S instance from the latest OCI console * Chunked data and incorporated feedback Broke down the long lab of running the app into two smaller labs and incorporated feedback received from Anoosha. * Minor change in Lab number * minor updates to the prerequisites * Update link to common image * Optional task to enable txn history * resized images resized images and minor text updates * Updated link to the ZIP file * Updated a link * Updated a link * Updates for changes to the image Bharath has made changes to the image. I have updated the text accordingly. * changes for updated image * Changes to the stock broker app * Comments incorporated to Lab 1 * Incorporated review comments and updated images * Changes to the Stock Broker app * Incorporated feedback rxd from Bharath * Incorporated Shivanshu's feedback * Update integrate-microtx-lib-files.md * Update integrate-microtx-lib-files.md * Specify shape to select A specific shape has to be selected. * minor change * LiveLabs content for ORDS apps First draft of LiveLabs content for ORDS apps * Draft 2 Ready for review * QA review comments incorporated Self QA completed QA review comments incorporated --------- Co-authored-by: ZackaryRice <[email protected]>
1 parent ea45d6c commit c8f731f

File tree

108 files changed

+2170
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

108 files changed

+2170
-0
lines changed

‎microtx-ords-data-consistency/introduction/images/ords-microtx-bank-transfer-app.png

67.2 KB
Loading

‎microtx-ords-data-consistency/introduction/introduction.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Introduction
2+
3+
## About this Workshop
4+
5+
As organizations rush to adopt microservices architecture, they often run into problems associated with data consistency as each microservice typically has its own database. In monolithic applications, local transactions were enough as there were no other sources of data that needed to be consistent with the database. An application would start a local transaction, perform some updates, and then commit the local transaction to ensure the application moved from one consistent state to another. Once the application’s state is spread across multiple sources of data, some factors need to be considered. What happens if the updates succeed in one microservice, but fails in another microservice as part of the same request? One solution is to use a distributed transaction that spans across the sources of data used by the microservices involved in a request. To maintain consistency in the state of all microservices participating in a distributed transaction, Oracle Transaction Manager for Microservices (MicroTx) provides a transaction coordination microservice and client libraries.
6+
7+
In this workshop, you will learn how to use MicroTx to maintain data consistency across multiple Oracle REST Data Services (ORDS) applications by deploying and running a Bank Transfer application. You will also integrate MicroTx with the Kubernetes ecosystem by using tools, such as Kiali and Jaeger, to visualize the flow of requests between MicroTx and the microservices.
8+
9+
### About the Bank Transfer Application
10+
11+
The Bank Transfer application is created in PL/SQL and deployed using ORDS in Oracle Database. It demonstrates how you can develop ORDS applications that participate in a distributed transaction while using MicroTx to coordinate the transaction. You can use the Bank Transfer application to withdraw or deposit an amount. Since financial applications that move funds require strong global consistency, the application uses the XA transaction protocol.
12+
13+
The following figure shows the various microservices in the Bank Transfer application. Some microservices connect to a resource manager. Resource managers manage stateful resources such as databases, queuing or messaging systems, and caches.
14+
![Microservices in Bank Transfer application](./images/ords-microtx-bank-transfer-app.png)
15+
16+
* The MicroTx coordinator manages transactions amongst the participant services.
17+
18+
* Teller microservice, a Java microservice, initiates the transactions. It is called an XA transaction initiator service. The user interacts with this microservice to transfer money from Department One to Department Two. It exposes a REST API method to transfer funds. This method defines the transaction boundary and initiates the distributed transaction. When a new request is created, MicroTx starts an XA transaction at the Teller microservice. This microservice also contains the business logic to issue the XA commit and roll back calls.
19+
20+
* Department One and Department Two are ORDS applications. They participate in the transactions, so they are called as XA participant services. Two PDBs, FREEPDB1 and FREEPDB2, are created in a standalone instance of Oracle Database 23c Free to simulate the distributed transaction. The standalone ORDS APEX service instance, runs on port 8080, and it is configured with two database pools that connect to FREEPDB1 and FREEPDB2. The ORDS service creates database pool for each PDB and exposes the REST endpoint. A single ORDS standalone service has two database connection pools connecting to different PDBs: FREEPDB1 and FREEPDB2. Department One and Department 2 connect to individual PDBs and the ORDS participant services expose three REST APIs, namely withdraw, deposit and get balance. The MicroTx library includes headers that enable the participant services to automatically enlist in the transaction. These microservices expose REST APIs to get the account balance and to withdraw or deposit money from a specified account. They also use resources from resource manager.
21+
22+
The service must meet ACID requirements, so an XA transaction is initiated, and both withdraw and deposit are called in the context of this transaction.
23+
24+
When you run the Bank Transfer application, the Teller microservice calls the exposed `transfer` REST API call to initiate the transaction to withdraw an amount from Department 1, an ORDS service, which is connected to FREEPDB1. After the amount is successfully withdrawn, the Teller service receives HTTP 200. Then the Teller calls the `deposit` REST API from Department 2, an ORDS service, which is connected to FREEPDB2. After the amount is successfully deposited, the Teller service receives HTTP 200, and then the Teller commits the transaction. MicroTx coordinates this distributed transaction. Within the XA transaction, all actions such as withdraw and deposit either succeed, or they all are rolled back in case of a failure of any one or more actions.
25+
26+
During a transaction, the microservices also update the associated resource manager to track the change in the amount. When you run the Bank Transfer application, you will see how MicroTx ensures consistency of transactions across the distributed microservices and their resource managers.
27+
28+
Participant microservices must use the MicroTx client libraries which registers callback and provides implementation of the callback for the resource manager. As shown in the image, MicroTx communicates with the resource managers to commit or roll back the transaction. MicroTx connects with each resource manager involved in the transaction to prepare, commit, or rollback the transaction. The participant service provides the credentials to the coordinator to access the resource manager.
29+
30+
Estimated Workshop Time: 50 minutes
31+
32+
### Objectives
33+
34+
In this workshop, you will learn how to:
35+
36+
* Set up various microservices. A Java service, Teller, is the transaction initiator application. The ORDS instances, Department 1 and Department 2 participate in the service. MicroTx is connected to all the resource managers and microservices so that it can coordinate the transaction.
37+
* Run the Bank Transfer application to transfer an amount from one account to another.
38+
* Use tools, such as Kiali and Jaeger, to visualize the flow of requests between MicroTx and the microservices.
39+
40+
### Prerequisites
41+
42+
This lab assumes you have:
43+
44+
* An Oracle Cloud account
45+
46+
* At least 4 OCPUs, 24 GB memory, and 128 GB of bootable storage volume is available in your Oracle Cloud Infrastructure tenancy to run the Bank Transfer application.
47+
48+
Let's begin! If you need to create an Oracle Cloud account, click **Get Started** in the **Contents** menu on the left. Otherwise, if you have an existing account, click **Lab 1**.
49+
50+
## Learn More
51+
52+
* [Oracle® Transaction Manager for Microservices Developer Guide](http://docs.oracle.com/en/database/oracle/transaction-manager-for-microservices/23.4.1/tmmdg/index.html)
53+
* [Oracle® Transaction Manager for Microservices Quick Start Guide](http://docs.oracle.com/en/database/oracle/transaction-manager-for-microservices/23.4.1/tmmqs/index.html)
54+
55+
## Acknowledgements
56+
57+
* **Author** - Sylaja Kannan, Consulting User Assistance Developer
58+
* **Contributors** - Brijesh Kumar Deo and Bharath MC
59+
* **Last Updated By/Date** - Sylaja Kannan, February 2024

‎microtx-ords-data-consistency/ords-provision/images/click-sql.png

495 KB
Loading

‎microtx-ords-data-consistency/ords-provision/images/db-actions-sign-in-complete.png

11.2 KB
Loading

‎microtx-ords-data-consistency/ords-provision/images/run-sql-script.png

158 KB
Loading

‎microtx-ords-data-consistency/ords-provision/ords-provision.md

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
1+
# Set Up the ORDS Instances
2+
3+
## Introduction
4+
5+
This lab walks you through the steps to set up two Oracle REST Data Services (ORDS) applications, Department 1 and Department 2. These applications are created in PL/SQL and deployed using ORDS in Oracle Database. These applications participate in the XA transaction, so they are called transaction participant services.
6+
7+
There are 2 PDBs (pluggable database) and a catalog database running in a standalone instance of Oracle Database 23c Free to simulate the distributed transaction. Here are the details about the PDBs:
8+
9+
* FREE: A catalog database that the `sysdba` user can access.
10+
* FREEPDB1: A pluggable database that contains the OTMM schema. This is connected to Department 1, an ORDS service.
11+
* FREEPDB2 : A pluggable database that contains the OTMM schema. This is connected to Department 2, an ORDS service.
12+
13+
The standalone ORDS APEX service instance, runs on port 8080, and it is configured with two database pools that connect to FREEPDB1 and FREEPDB2. The ORDS service creates database pool for each PDB and exposes the REST endpoint. A single ORDS standalone service has two database connection pools connecting to different PDBs: FREEPDB1 and FREEPDB2. Department 1 and Department 2 connect to individual PDBs and the ORDS participant services expose three REST APIs, namely withdraw, deposit and get balance. The MicroTx library includes headers that enable the participant services to automatically enlist in the transaction. These microservices expose REST APIs to get the account balance and to withdraw or deposit money from a specified account. They also use resources from resource manager.
14+
15+
Estimated Time: 15 minutes
16+
17+
### Objectives
18+
19+
In this lab, you will:
20+
21+
* Start the Database service and ORDS service instances
22+
* Grant privileges to the database schema
23+
* Set Up Department 1 and Department 2 applications
24+
* Test access to the applications
25+
26+
### Prerequisites
27+
28+
This lab assumes you have:
29+
30+
* An Oracle Cloud account.
31+
* Successfully completed the previous labs:
32+
* Get Started
33+
* Lab 1: Prepare setup
34+
* Lab 2: Environment setup
35+
* Logged in using remote desktop URL as an `oracle` user. If you have connected to your instance as an `opc` user through an SSH terminal using auto-generated SSH Keys, then you must switch to the `oracle` user before proceeding with the next step.
36+
37+
```text
38+
<copy>
39+
sudo su - oracle
40+
</copy>
41+
```
42+
43+
## Task 1: Start the Database Service and ORDS Service Instances
44+
45+
1. Run the following command to verify that the Oracle Database 23c Free service instance is running.
46+
47+
```text
48+
<copy>
49+
sudo /etc/init.d/oracle-free-23c status
50+
</copy>
51+
```
52+
53+
**Example output**
54+
55+
```text
56+
Status of the Oracle FREE 23c service:
57+
LISTENER status: RUNNING
58+
FREE Database status: RUNNING
59+
```
60+
61+
If the Oracle Database 23c Free service instance is not in the `RUNNING` state, then run the following command to restart the service.
62+
63+
```text
64+
<copy>
65+
sudo systemctl restart oracle-free-23c
66+
</copy>
67+
```
68+
69+
2. Run the following commands in a new terminal to start the Oracle REST Data Services (ORDS) standalone service. Keep this terminal window open throughout the lab.
70+
71+
```text
72+
<copy>
73+
export _JAVA_OPTIONS="-Xms8192M -Xmx8192M"
74+
ords --config ${ORDS_CONFIG} serve
75+
</copy>
76+
```
77+
78+
3. Reset the password for the `SYS` user by logging into the catalog database with the default password.
79+
80+
```SQL
81+
<copy>
82+
sql sys/Passw0rd@FREE as sysdba
83+
SQL> ALTER USER SYS IDENTIFIED BY [new-user-password];
84+
SQL> ALTER USER SYSTEM IDENTIFIED BY [new-user-password];
85+
SQL> commit;
86+
SQL> exit;
87+
</copy>
88+
```
89+
90+
Where, `[new-user-password]` is the new password that you specify for FREE, a catalog database.
91+
92+
## Task 2: Grant Privileges to the Schema in FREEPDB1
93+
94+
1. Login to FREEPDB1 using the default username and password.
95+
96+
```SQL
97+
<copy>
98+
sql sys/Passw0rd@FREEPDB1 as sysdba
99+
</copy>
100+
```
101+
102+
2. Change the default password.
103+
104+
```SQL
105+
<copy>
106+
ALTER USER OTMM IDENTIFIED BY [<new-freepdb1-password>];
107+
commit;
108+
exit;
109+
</copy>
110+
```
111+
112+
Where, `<new-freepdb1-password>` is the new password that you want to set.
113+
114+
3. Run the following commands to grant privileges to the schema.
115+
116+
```SQL
117+
<copy>
118+
DECLARE
119+
l_principal VARCHAR2(20) := 'OTMM';
120+
begin
121+
DBMS_NETWORK_ACL_ADMIN.append_host_ace (
122+
host => '*',
123+
lower_port => null,
124+
upper_port => null,
125+
ace => xs$ace_type(privilege_list => xs$name_list('http'),
126+
principal_name => l_principal,
127+
principal_type => xs_acl.ptype_db));
128+
end;
129+
/
130+
131+
DECLARE
132+
l_principal VARCHAR2(20) := 'OTMM';
133+
begin
134+
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
135+
host => '*',
136+
ace => xs$ace_type(privilege_list => xs$name_list('connect', 'resolve'),
137+
principal_name => l_principal,
138+
principal_type => xs_acl.ptype_db));
139+
end;
140+
/
141+
</copy>
142+
```
143+
144+
Where, `OTMM` is the username that can access the schema.
145+
146+
4. Commit the changes and exit from SQL prompt.
147+
148+
```SQL
149+
<copy>
150+
SQL> commit;
151+
SQL> exit;
152+
</copy>
153+
```
154+
155+
## Task 3: Grant Privileges to the Schema in FREEPDB2
156+
157+
1. Login to FREEPDB2 using the default username and password.
158+
159+
```SQL
160+
<copy>
161+
sql sys/Passw0rd@FREEPDB2 as sysdba
162+
</copy>
163+
```
164+
165+
2. Change the default password.
166+
167+
```SQL
168+
<copy>
169+
ALTER USER OTMM IDENTIFIED BY [<new-freepdb2-password>];
170+
commit;
171+
exit;
172+
</copy>
173+
```
174+
175+
Where, `<new-freepdb2-password>` is the new password that you want to set.
176+
177+
3. Run the following commands to grant privileges to the schema.
178+
179+
```SQL
180+
<copy>
181+
DECLARE
182+
l_principal VARCHAR2(20) := 'OTMM';
183+
begin
184+
DBMS_NETWORK_ACL_ADMIN.append_host_ace (
185+
host => '*',
186+
lower_port => null,
187+
upper_port => null,
188+
ace => xs$ace_type(privilege_list => xs$name_list('http'),
189+
principal_name => l_principal,
190+
principal_type => xs_acl.ptype_db));
191+
end;
192+
/
193+
194+
DECLARE
195+
l_principal VARCHAR2(20) := 'OTMM';
196+
begin
197+
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
198+
host => '*',
199+
ace => xs$ace_type(privilege_list => xs$name_list('connect', 'resolve'),
200+
principal_name => l_principal,
201+
principal_type => xs_acl.ptype_db));
202+
end;
203+
/
204+
</copy>
205+
```
206+
207+
Where, `OTMM` is the username that can access the schema.
208+
209+
4. Commit the changes and exit from SQL prompt.
210+
211+
```SQL
212+
<copy>
213+
SQL> commit;
214+
SQL> exit;
215+
</copy>
216+
```
217+
218+
## Task 4: Set Up Department 1
219+
220+
1. Enter the SQL Developer web URL, `http://localhost:8080/ords/sql-developer`, to access Department 1 database.
221+
A sign-in page for Database Actions is displayed.
222+
223+
2. Enter the new password to access the FREE database as `sysdba` user.
224+
225+
The Database Actions page is displayed.
226+
227+
3. In the **Development** box, click **SQL**.
228+
229+
![Click on SQL](./images/click-sql.png)
230+
231+
4. Open the `tmmxa.sql` SQL script file which is located at `/home/oracle/OTMM/otmm-23.4.1/samples/xa/plsql/lib`.
232+
233+
5. Click **Run as SQL script** to run the `tmmxa.sql` SQL script file.
234+
235+
![Click Run as SQL script](./images/run-sql-script.png)
236+
237+
6. Open the `ordsapp.sql` SQL script file which is located at `/home/oracle/OTMM/otmm-23.4.1/samples/xa/plsql/databaseapp`.
238+
239+
7. In the script, search for `resManagerId` and enter a unique resource manager ID to identify the database in both the `deposit` and `withdraw` handlers.
240+
241+
**Example Code**
242+
243+
```text
244+
<copy>
245+
resManagerId VARCHAR2(256):= ''DEPT1-RM'';
246+
</copy>
247+
```
248+
249+
```text
250+
<copy>
251+
resManagerId VARCHAR2(256):= ''DEPT1-RM'';
252+
</copy>
253+
```
254+
255+
7. Click **Run as SQL script** to run the `ordsapp.sql` SQL script file.
256+
257+
![Click Run as SQL script](./images/run-sql-script.png)
258+
259+
8. Log out from SQL Developer.
260+
261+
## Task 5: Set Up Department 2
262+
263+
1. Enter the SQL Developer web URL, `http://localhost:8080/ords/pool2/sql-developer`, to access Department 2 database.
264+
A sign-in page for Database Actions is displayed.
265+
266+
2. Enter the schema username and password that you have specified in the previous tasks.
267+
268+
The Database Actions page is displayed.
269+
270+
3. In the **Development** box, click **SQL**.
271+
272+
![Click on SQL](./images/click-sql.png)
273+
274+
4. Open the `tmmxa.sql` SQL script file which is located at `/home/oracle/OTMM/otmm-23.4.1/samples/xa/plsql/lib`.
275+
276+
5. Click **Run as SQL script** to run the script file.
277+
278+
![Click Run as SQL script](./images/run-sql-script.png)
279+
280+
6. Open the `ordsapp.sql` SQL script file which is located at `/home/oracle/OTMM/otmm-23.4.1/samples/xa/plsql/databaseapp`.
281+
282+
7. In the script, search for `resManagerId` and enter a unique resource manager ID to identify the database in both the `deposit` and `withdraw` handlers.
283+
284+
**Example Code**
285+
286+
```text
287+
<copy>
288+
resManagerId VARCHAR2(256):= ''DEPT2-RM'';
289+
</copy>
290+
```
291+
292+
```text
293+
<copy>
294+
resManagerId VARCHAR2(256):= ''DEPT2-RM'';
295+
</copy>
296+
```
297+
298+
8. Click **Run as SQL script** to run the script file.
299+
300+
![Click Run as SQL script](./images/run-sql-script.png)
301+
302+
9. Log out from SQL Developer.
303+
304+
## Task 6: Test Access to Department 1 and Department 2
305+
306+
Run the following commands to test access and verify that REST API calls to Department 1 and Department 2 are executed successfully.
307+
308+
1. Run the following command to retrieve the balance in account 1 of Department 1.
309+
310+
```text
311+
<copy>
312+
curl --location --request GET 'http://localhost:8080/ords/otmm/accounts/account1'
313+
</copy>
314+
```
315+
316+
2. Run the following command to retrieve the balance in account 2 of Department 2.
317+
318+
```text
319+
<copy>
320+
curl --location --request GET 'http://localhost:8080/ords/pool2/otmm/accounts/account2'
321+
</copy>
322+
```
323+
324+
You may now **proceed to the next lab.**
325+
326+
## Learn More
327+
328+
* [REST Data Services Developer's Guide](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/)
329+
330+
## Acknowledgements
331+
332+
* **Author** - Sylaja Kannan
333+
* **Contributors** - Brijesh Kumar Deo and Bharath MC
334+
* **Last Updated By/Date** - Sylaja Kannan, February 2024

0 commit comments

Comments
 (0)