Skip to content

Commit 3afc612

Browse files
anders-swansonanders-swanson
authored
TxEventQ Migration (#1021)
Signed-off-by: Anders Swanson <anders.swanson@oracle.com>
1 parent 5a772f5 commit 3afc612

File tree

1 file changed

+214
-0
lines changed
  • docs-source/transactional-event-queues/content/aq-migration

1 file changed

+214
-0
lines changed

‎docs-source/transactional-event-queues/content/aq-migration/migration.md

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
+++
2+
archetype = "page"
3+
title = "AQ Migration
4+
weight = 1
5+
+++
6+
7+
This section covers the use of the [DBMS_AQMIGTOOL](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html) package for migrating Advanced Queuing (AQ) classic queues to TxEventQ.
8+
9+
Users of AQ are recommended to migrate to TxEventQ for increased support, performance, and access to new database features. It is recommended to read through the document fully before attempting migration.
10+
11+
## DBMS_AQMIGTOOL Overview
12+
13+
The migration tool interface provides the following functionalities:
14+
15+
- Migration may be performed in AUTOMATIC, INTERACTIVE, OFFLINE, or ONLY_DEFINITION mode, each mode providing specific use cases and benefits.
16+
- DBMS_AQMIGTOOL.AUTOMATIC: Enqueue and dequeue operations are allowed during migration, and a background job will commit the migration once the AQ is empty and no unsupported features are detected.
17+
- DBMS_AQMIGTOOL.INTERACTIVE (Default): Enqueue and dequeue operations are allowed, and the user must commit the migration.
18+
- DBMS_AQMIGTOOL.OFFLINE: Only dequeue operations are allowed during migration, which can help in draining the AQ.
19+
- DBMS_AQMIGTOOL.ONLY_DEFINITION: A TxEventQ copy is made from the AQ configuration, and messages are not migrated. Both the AQ and TxEventQ remain in the system after migration is committed with separate message streams. This option is recommended for users who prefer a more manual or custom migration.
20+
21+
- Users may decide to commit the migration or revert to AQ via the migration interface.
22+
23+
- During migration, in-flight messages can be tracked by viewing messages not in the PROCESSED state for both the AQ and TxEventQ.
24+
25+
- A migration history is recorded for all queues.
26+
27+
- Users may optionally purge old AQ messages if they wish to discard the data after migration.
28+
29+
- AQ Migration supports both rolling upgrades and Oracle GoldenGate (OGG) replication.
30+
31+
- During online migrations, it is safe for applications to continue enqueue/dequeue operations as normal.
32+
33+
## Migration Workflow
34+
35+
1. Check compatibility of migration and review the [limitations and workarounds](#limitations-and-workarounds).
36+
37+
2. Start the migration with the DBMS_AQMIGTOOL.INIT_MIGRATION procedure, which creates an interim TxEventQ by copying the AQ's configuration, including payload type, rules, subscribers, privileges, notifications, and more. Administrative queue changes (`alter queue`) are restricted until the migration is completed or canceled.
38+
39+
3. During migration, queue messages transition to the TxEventQ. New messages go to TxEventQ, and dequeue requests go to AQ until it is drained of messages at which point dequeue requests switch to TxEventQ. Migration status can be monitored and any errors addressed or rolled back.
40+
41+
4. Once the AQ is drained or purged, the DBMS_AQMIGTOOL.COMMIT_MIGRATION procedure drops the AQ and renames the interim TxEventQ to the AQ's name, ensuring application compatibility.
42+
1. If using DBMS_AQMIGTOOL.AUTOMATIC migration mode, commit is not required.
43+
44+
In the event of an error the prevents migration from continuing, AQ migration may be cancelled and the in-flight messages restored to the AQ without data loss.
45+
46+
### Checking Compatibility
47+
48+
The [CHECK_MIGRATION_TO_TXEVENTQ](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-6DE10CAB-63DA-49F9-A29B-682050DAEA80) procedure is used to verify an AQ is suitable for migration to TxEventQ and should be run before any migration is attempted.
49+
50+
The following SQL script creates a migration report for the AQ `my_queue` and prints the count of events in the migration report. If all features are supported, the `migration_report` will be empty.
51+
52+
```sql
53+
declare
54+
migration_report sys.TxEventQ_MigReport_Array := sys.TxEventQ_MigReport_Array();
55+
begin
56+
DBMS_AQMIGTOOL.CHECK_MIGRATION_TO_TXEVENTQ('testuser', 'my_queue', migration_report);
57+
dbms_output.put_line('Migration report unsupported events count: ' || migration_report.COUNT);
58+
end;
59+
/
60+
```
61+
62+
If the output is similar to "Migration report unsupported events count: 0", then it is safe to initiate the migration.
63+
64+
### Initiating Migration
65+
66+
The [INIT_MIGRATION](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-4D2A3314-9ADF-43DE-9201-74A8F9DB03FE) procedure is used to begin AQ migration to TxEventQ. The `mig_mode` parameter is used to control the migration type and defaults to `DBMS_AQMIGTOOL.INTERACTIVE` which allows both enqueue and dequeue during migration. A full description of `mig_mode` options is available in the procedure documentation.
67+
68+
The following SQL script starts migration for the AQ `my_queue` in the `testuser` schema. Once migration starts, an interim TxEventQ will be created named `my_queue_m` the includes a copy of the existing AQ configuration.
69+
70+
```sql
71+
begin
72+
DBMS_AQMIGTOOL.INIT_MIGRATION(
73+
cqschema => 'testuser',
74+
cqname => 'my_queue'
75+
);
76+
end;
77+
/
78+
```
79+
80+
`INIT_MIGRATION` is non-blocking may be executed concurrently on multiple queues. If `DBMS_AQMIGTOOL.INTERACTIVE` is used as the migration mode, messages may be enqueued and dequeued during migration.
81+
82+
### Checking Migration Status
83+
84+
While migration is occurring, dequeue will pull from the AQ until it is empty, at which point it will switch to the TxEventQ.
85+
86+
The following SQL statement uses the [CHECK_MIGRATED_MESSAGES](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-FECA1B81-8C0E-4ACA-B878-EFD558B33843) procedure to print the count of remaining `READY` state messages in the AQ and the count messages migrated to TxEventQ. Once the `aq_msg_cnt` reaches zero, the AQ has been fully drained and the migration can be committed. If we attempt to commit the migration before the AQ is drained of `READY` state messages, an exception will be raised.
87+
88+
```sql
89+
declare
90+
migrated_q_msg_cnt number := 0;
91+
aq_msg_cnt number := 0;
92+
begin
93+
DBMS_AQMIGTOOL.CHECK_MIGRATED_MESSAGES(
94+
cqschema => 'testuser',
95+
cqname => 'my_queue',
96+
txeventq_migrated_message => migrated_q_msg_cnt,
97+
cq_pending_messages => aq_msg_cnt
98+
);
99+
dbms_output.put_line('AQ ready state message count: ' || aq_msg_cnt);
100+
dbms_output.put_line('Migrated TxEventQ message count: ' || migrated_q_msg_cnt);
101+
end;
102+
/
103+
```
104+
105+
The [USER_TXEVENTQ_MIGRATION_STATUS](https://docs.oracle.com/en/database/oracle/oracle-database/23/refrn/USER_TXEVENTQ_MIGRATION_STATUS.html#REFRN-GUID-07BAF678-A893-4616-B559-E78E90EE1972) view is used to check the status of in-process migrations for all queues owned by the current user. Queue information, migration status, and error events are available in this view.
106+
107+
### Commit the Migration
108+
109+
Once the count of `READY` state messages in the AQ reach zero, the [COMMIT_MIGRATION](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-6E7611A4-0702-4090-B8F8-BA5BDA3E1144) procedure is used to finalize the migration operation.
110+
111+
The following SQL script commits the migration for the `my_queue` queue in the `testuser` schema. Once the migration is committed, `my_queue` becomes a TxEventQ.
112+
113+
```sql
114+
begin
115+
DBMS_AQMIGTOOL.COMMIT_MIGRATION(
116+
cqschema => 'testuser',
117+
cqname => 'my_queue'
118+
);
119+
end;
120+
/
121+
```
122+
123+
If you wish to purge all messages from the AQ rather than dequeuing them, the [PURGE_QUEUE_MESSAGES](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-DFE7E6F6-0143-4998-A970-3A90800AFCB0) procedure can be used to empty the queue.
124+
125+
The following SQL script purges messages from the `my_queue` queue in the `testuser` schema, allowing migration commit without dequeuing the AQ.
126+
127+
```sql
128+
begin
129+
DBMS_AQMIGTOOL.PURGE_QUEUE_MESSAGES(
130+
cqschema => 'testuser',
131+
cqname => 'my_queue'
132+
);
133+
end;
134+
```
135+
136+
### Checking and Handling Migration Errors
137+
138+
If you encounter an error during AQ migration or are using an AQ feature that is unsupported in TxEventQ, the [CHECK_STATUS](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-F6318675-B7B7-4F2A-B0D1-2DC287C6A0EA) procedure can be used to query the current migration status and report any errors.
139+
140+
The following SQL script checks the migration status of the `my_queue` queue. In the event of migration incompatibilities, application changes may be required before continuing migration.
141+
142+
```sql
143+
declare
144+
mig_STATUS VARCHAR2(128);
145+
mig_comments VARCHAR2(1024);
146+
begin
147+
DBMS_AQMIGTOOL.CHECK_STATUS(
148+
cqschema => 'testuser',
149+
cqname => 'my_queue',
150+
status => mig_STATUS,
151+
migration_comment => mig_comments
152+
);
153+
dbms_output.put_line('Migration Status: ' || mig_STATUS);
154+
dbms_output.put_line('Migration comments: ' || mig_comments);
155+
end;
156+
/
157+
```
158+
159+
Example of an error output due to unsupported TxEventQ enqueue operations:
160+
161+
```
162+
Migration Status: Compatibility Error: Transformation in Enq Unsupported Feature
163+
Migration comments: Unsupported parameter in Enqueue
164+
```
165+
166+
### Cancelling and Recovering Migration
167+
168+
The [CANCEL_MIGRATION](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-A3C934C4-7827-407B-ABE2-F3842D3A6267) procedure is used to cancel an in-progress migration. Use `DBMS_AQMIGTOOL.RESTORE` as the cancellation mode (default) to preserve messages during cancellation.
169+
170+
The following SQL script cancels migration for the AQ `my_queue` in the `testuser` schema:
171+
172+
```sql
173+
begin
174+
DBMS_AQMIGTOOL.CANCEL_MIGRATION(
175+
cqschema => 'testuser',
176+
cqname => 'my_queue',
177+
cancelmode => DBMS_AQMIGTOOL.RESTORE
178+
);
179+
end;
180+
/
181+
```
182+
183+
The [RECOVER_MIGRATION](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQMIGTOOL.html#GUID-755EEB52-BFAE-4FEA-A933-07546D72DD98) procedure can be used to restore a migration to the nearest safe point, either before or after the execution of DBMS_AQMIGTOOL.CANCEL_MIGRATION, DBMS_AQMIGTOOL.COMMIT_MIGRATION, or DBMS_AQMIGTOOL.INIT_MIGRATION.
184+
185+
The following SQL script recovers migration to the nearest safe point, and outputs the recovery message:
186+
187+
```sql
188+
declare
189+
recovery_message VARCHAR2(1024);
190+
begin
191+
DBMS_AQMIGTOOL.RECOVER_MIGRATION(
192+
cqschema => 'testuser',
193+
cqname => 'my_queue',
194+
recovery_message => recovery_message
195+
);
196+
dbms_output.put_line('Recovery message: ' || recovery_message);
197+
end;
198+
/
199+
```
200+
201+
## Limitations and Workarounds
202+
203+
The following features are unsupported in TxEventQ, and should be mitigated before migration:
204+
205+
- Queue Retry Delay: Set `retry_delay` to zero using DBMS_AQADM.ALTER_QUEUE.
206+
- Message transactions on enqueue/dequeue: Move the transformation to the application layer.
207+
- Multi-queue listeners: Implement single queue listening with dequeue browse.
208+
- Priority values outside the range 0-9: Adjust priority values to the range 0-9.
209+
210+
The following features do support migration. Applications using these features must be modified before migration:
211+
212+
- Message grouping.
213+
- Sequence deviation and relative message id.
214+
- Message recipient lists.

0 commit comments

Comments
 (0)