29 DBMS_AQMIGTOOL
DBMS_AQMIGTOOLパッケージは、オーケストレーションの自動化、ソースとターゲットの互換性の診断と修正、統一されたユーザー・エクスペリエンスによって、Oracle Databaseアドバンスト・キューイング(AQ)からトランザクション・イベント・キュー(TxEventQ)への移行を簡素化します。移行シナリオは、短期間にすることも長期間にすることも、AQ停止時間ありでもなしでも実行できるため、運用上の中断がなくなります。
参照:
DBMS_AQMIGTOOLの詳細は、『Oracle Databaseアドバンスト・キューイング・ユーザーズ・ガイド』のAQからTxEventQへの移行を参照してください。
この章のトピックは、次のとおりです:
29.1 DBMS_AQMIGTOOLのセキュリティ・モデル
ユーザーがすべてのDBMS_AQMIGTOOLサブプログラムを実行するには、DBMS_AQMIGTOOLパッケージに対するEXECUTE権限が必要です。このパッケージの呼出し元がキューの所有者の場合は、DBMS_AQMIGTOOLパッケージに対するEXECUTE権限のみで十分です。ただし、呼出し元が所有者でない場合は、MANAGE_ANYキュー・システム権限も必要になります。この権限は、DBMS_AQADM.GRANT_SYSTEM_PRIVILEGEによって生成できます。
29.2 DBMS_AQMIGTOOL定数
DBMS_AQMIGTOOLパッケージは、パラメータ値の指定に使用できるいくつかの定数を定義します。
AUTOMATIC、INTERACTIVEまたはENABLE_EVALUATIONなどの列挙定数を使用するときは、それを定義するパッケージの範囲内で、その記号を指定する必要があります。管理インタフェースに関連付けられているすべてのタイプには、DBMS_AQMIGTOOLを付加する必要があります。例: DBMS_AQMIGTOOL.AUTOMATIC。
表29-1 DBMS_AQMIGTOOL定数
| パラメータ | オプション | 値 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
29.3 DBMS_AQMIGTOOLサブプログラムの要約
この項では、DBMS_AQMIGTOOLのサブプログラムをリストし、簡単に説明します。
表29-2 DBMS_AQMIGTOOLパッケージのサブプログラム
| サブプログラム | 説明 |
|---|---|
|
暫定的なTxEventQを削除して進行中の移行を取り消します |
|
|
AQおよび暫定的なTxEventQ内の |
|
|
AQの定義とデータを分析して、TxEventQでサポートされていない機能をレポートします |
|
|
進行中の移行プロセスについて現在のステータスを返します |
|
|
|
|
|
移行プロセスは、AQを削除して、AQの名前と一致するように暫定TxEventQの名前を変更し、すべての操作に対してTxEventQを有効にすることで完了します |
|
|
サポートされていない機能を検出するための内部的なAQモニタリングを無効化し、 |
|
|
AQの定義とサポートされていない機能に関するデータを分析して、AQの構成をコピーする暫定的なTxEventQを作成して移行プロセスを開始します |
|
|
キューからメッセージをパージします |
|
|
移行のプロシージャ( |
|
|
デフォルトの例外キュー(存在する場合)とともにTxEventQの名前を変更します |
29.3.1 CANCEL_MIGRATIONプロシージャ
このプロシージャは、進行中の移行を取り消す目的に利用します。これには、DBMS_AQMIGTOOL.INIT_MIGRATIONの実行中に作成された暫定的なTxEventQの削除が含まれます。
構文
PROCEDURE DBMS_AQMIGTOOL.CANCEL_MIGRATION ( cqschema IN VARCHAR2, cqname IN VARCHAR2, cancelmode IN NUMBER DEFAULT DBMS_AQMIGTOOL.RESTORE );
パラメータ
表29-3 CANCEL_MIGRATIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
移行の取消しが必要なキューの名前を指定します |
|
|
ユーザーが移行を取り消すモードを指定します。次は、返される値です。
ノート: リストアされたメッセージの優先度の動作は、AQとTxEventQのデフォルト値が異なるために変更されることがあります。
|
使用上のノート
このプロシージャの前提条件は、すでにキューで移行が開始されている必要があることです。つまり、このプロシージャの実行前に、DBMS_AQMIGTOOL.INIT_MIGRATIONが呼び出されていることが必要です。DBMS_AQMIGTOOL.RESTOREモードの場合、TxEventQの例外キュー・メッセージは、AQまたはその例外キューにリストアされません。
29.3.2 CHECK_MIGRATED_MESSAGESプロシージャ
このプロシージャは、AQと暫定的なTxEventQの両方にあるREADY状態のメッセージ数を計算します。この数は、DBMS_AQMIGTOOL.COMMIT_MIGRATIONまたはDBMS_AQMIGTOOL.CANCEL_MIGRATIONの使用前に重要なインサイトを提供します。計算された数は、サブスクライバの数とは関係ありません。
構文
PROCEDURE SYS.DBMS_AQMIGTOOL.CHECK_MIGRATED_MESSAGES ( cqschema IN VARCHAR2, cqname IN VARCHAR2, txeventq_migrated_message IN OUT NUMBER, cq_pending_messages IN OUT NUMBER);
パラメータ
表29-4 CHECK_MIGRATED_MESSAGESプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
移行プロセスが開始されているキューの名前を指定します |
|
|
暫定的なTxEventQ内にある |
|
|
AQ内にある |
使用上のノート
このプロシージャの前提条件は、すでにキューで移行が開始されている必要があることです。これは、このプロシージャの実行前に、DBMS_AQMIGTOOL.INIT_MIGRATIONが呼び出されている必要があるということです。
29.3.3 CHECK_MIGRATION_TO_TXEVENTQプロシージャ
このプロシージャは、AQの定義とデータを確認し、TxEventQでサポートされていない機能をレポートします。サポートされていない機能が検出されない場合、migration_reportは空になります。
構文
PROCEDURE DBMS_AQMIGTOOL.CHECK_MIGRATION_TO_TXEVENTQ ( cqschema IN VARCHAR2, cqname IN VARCHAR2, migration_report IN OUT TXEVENTQ_MIGREPORT_ARRAY, checkmode IN NUMBER DEFAULT DBMS_AQMIGTOOL.ENABLE_EVALUATION);
パラメータ
表29-5 CHECK_MIGRATION_TO_TXEVENTQプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
サポートされていない機能のチェックが必要なキュー名を指定します |
|
|
サポートされていないイベントの詳細とそれに対応する説明が含まれているVarray。最新の20のサポートされていない機能を保持します。 |
|
|
ユーザーがチェックするモードを指定します。次は、返される値です。
|
使用上のノート
相対メッセージ識別子、順序逸脱、変換などのいくつかの機能は、TxEventQではサポートされていません。それらのいずれかを使用するキューについては、migration_reportに記録されます。
移行プロセスの開始前に、DBMS_AQMIGTOOL.CHECK_MIGRATION_TO_TXEVENTQプロシージャを使用してサポートされていない機能を検出しておくことをお薦めします。
29.3.4 CHECK_STATUSプロシージャ
このプロシージャは移行プロセスのステータスを返します。サポートされていない機能が検出された場合、このプロシージャは、サポートされていない最新の機能について説明とともに詳細を返します。その一方で、サポートされていない機能が検出されない場合は、'互換性エラーなし'のステータスが返されます。
構文
PROCEDURE DBMS_AQMIGTOOL.CHECK_STATUS ( cqschema IN VARCHAR2, cqname IN VARCHAR2, status IN OUT VARCHAR2, migration_comment IN OUT VARCHAR2);
パラメータ
表29-6 CHECK_STATUSプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
移行プロセス・ステータスについてチェックが必要なキューの名前を指定します |
|
|
互換性ステータスを返します。互換性がない(サポートされていない機能が検出された)場合は、サポートされていない最新のイベントが戻され、ステータスが"Compatibility Error: <feature_name> Unsupported Feature"の形式で戻されます。 |
|
|
ステータスが互換性なしの場合、サポートされていないイベントの説明が示されます |
使用上のノート
このプロシージャの前提条件は、すでにキューで移行が開始されている必要があることです。これは、このプロシージャの実行前に、DBMS_AQMIGTOOL.INIT_MIGRATIONが呼び出されている必要があるということです。
次の表に、初期化前または初期化後の移行中のイベントに関する情報が格納されます。ユーザーは、この情報にセキュリティ・ビューのDBA_TXEVENTQ_MIGRATION_STATUS、USER_TXEVENTQ_MIGRATION_STATUSおよびALL_TXEVENTQ_MIGRATION_STATUSからアクセスできます。
sys.aq$_migration_status(
migration_id RAW(16);
source_schema VARCHAR2(128) NOT NULL,
source_queue VARCHAR2(128) NOT NULL,
source_queue_table VARCHAR2(128),
target_schema VARCHAR2(128) NOT NULL,
target_queue VARCHAR2(128) NOT NULL,
status NUMBER,
event VARCHAR(128),
event_timestamp TIMESTAMP WITH TIME ZONE,
event_id NUMBER,
event_error VARCHAR2(1024),
ordering VARCHAR(30),
suffix VARCHAR2(2),
mig_mode NUMBER,
spare1 NUMBER,
spare2 VARCHAR2(30),
spare3 TIMESTAMP WITH TIME ZONE
)
一意のmigration_idが、開始された移行ごとに割り当てられます。
参照:
『Oracle Databaseリファレンス』のDBA_TXEVENTQ_MIGRATION_STATUS
『Oracle Databaseリファレンス』のUSER_TXEVENTQ_MIGRATION_STATUS
『Oracle Databaseリファレンス』のALL_TXEVENTQ_MIGRATION_STATUS
29.3.5 CLEAR_UNSUPPORTED_FEATURE_TABLEプロシージャ
このプロシージャは、USER_TXEVENTQ_MIGRATION_STATUSビューの基になっている表からエントリを削除します。このビューには、DBMS_AQMIGTOOL.CHECK_MIGRATION_TO_TXEVENTQプロシージャで検出されたサポートされていない機能に関連するレコードと、その他の内部目的で使用される移行プロシージャ・コール(INIT_MIGRATION/COMMIT_MIGRATION/CANCEL_MIGRATION)の詳細が格納されます。
構文
PROCEDURE DBMS_AQMIGTOOL.CLEAR_UNSUPPORTED_FEATURE_TABLE ( cqschema IN VARCHAR2, cqname IN VARCHAR2 DEFAULT NULL, eraseall IN BOOLEAN DEFAULT FALSE);
パラメータ
表29-7 CLEAR_UNSUPPORTED_FEATURE_TABLEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
レコードのクリアが必要なキューの名前を指定します |
|
|
ノート:
|
使用上のノート
ユーザーは、このプロシージャを使用すると、DBMS_AQMIGTOOL.CHECK_MIGRATION_TO_TXEVENTQプロシージャで生成されたレコードを消去できます。キューまたはユーザーを削除すると、そのキューのレコードも消去することになります。ただし、DBMS_AQMIGTOOL.COMMIT_MIGRATIONまたはDBMS_AQMIGTOOL.CANCEL_MIGRATIONを実行しても、キューのレコードはクリアされません。そのため、このプロシージャでは、任意の時点でキューのレコードを柔軟に消去できます。
29.3.6 COMMIT_MIGRATIONプロシージャ
このプロシージャは移行プロセスを完了します。AQを削除して、暫定的なTxEventQの名前をAQの名前に変更し、すべての操作に対してTxEventQを有効にします。このプロシージャを正常に実行するには空のAQ (READY状態のメッセージがないもの)が必要になることに注意してください。それがないと、例外が発生します。
構文
PROCEDURE DBMS_AQMIGTOOL.COMMIT_MIGRATION ( cqschema IN VARCHAR, cqname IN VARCHAR, ignore_warning IN BOOLEAN DEFAULT FALSE));
パラメータ
表29-8 COMMIT_MIGRATIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
移行の完了が必要なキューの名前を指定します |
|
|
|
使用上のノート
このプロシージャの前提条件は、移行がすでにキューで開始されている必要があることです。つまり、このプロシージャの実行前に、DBMS_AQMIGTOOL.INIT_MIGRATIONプロシージャが呼び出されている必要があります。AQの例外キューのメッセージは、TxEventQの例外キューにコピーされません。
29.3.7 DISABLE_MIGRATION_CHECKプロシージャ
このプロシージャは、サポートされていない機能を検出するための内部的なAQモニタリングを無効にします。また、USER_TXEVENTQ_MIGRATION_STATUSビューに対応するイベントの記録も停止します。
構文
PROCEDURE DBMS_AQMIGTOOL.DISABLE_MIGRATION_CHECK ( cqschema IN VARCHAR2) cqname IN VARCHAR2);
パラメータ
表29-9 DISABLE_MIGRATION_CHECKプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
移行モニタリングの無効化が必要なキューの名前を指定します |
使用上のノート
移行前のステップとして、ユーザーはDBMS_AQMIGTOOL.ENABLE_EVALUATIONオプションを指定してDBMS_AQMIGTOOL.CHECK_MIGRATION_TO_TXEVENTQを呼び出すことで、サポートされていない機能の記録を開始できます。これに続けて、潜在的な問題を検出するためにAQで包括的なワークロードを実行し、その後でDBMS_AQMIGTOOL.DISABLE_MIGRATION_CHECKをコールすることでサポートされていない機能の記録を停止できます。移行の問題が見つかった場合、ユーザーはプロセスを繰り返す前にワークロードを変更できます。移行の問題が見つからなかった場合は、AQの移行を試行できます。
29.3.8 INIT_MIGRATIONプロシージャ
このプロシージャは、AQの定義とデータを調べて、TxEventQでサポートされていない機能を検出します。サポートされていない機能が検出されると、例外が発生します。それ以外の場合、このプロシージャは、ペイロード・タイプ、ルール、サブスクライバ、権限、PL/SQL通知などを含むAQの構成をコピーする暫定的なTxEventQを作成することで移行プロセスを開始します。
構文
PROCEDURE DBMS_AQMIGTOOL.INIT_MIGRATION ( cqschema IN VARCHAR2, cqname IN VARCHAR2 DEFAULT NULL, txeventqschema IN VARCHAR2 DEFAULT NULL, txeventqname IN VARCHAR2 DEFAULT NULL, mig_mode IN NUMBER DEFAULT DBMS_AQMIGTOOL.INTERACTIVE, ordering IN NUMBER DEFAULT DBMS_AQMIGTOOL.GLOBAL, suffix IN VARCHAR2 DEFAULT ‘M’);
パラメータ
表29-10 INIT_MIGRATIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キュー(AQ)が存在するスキーマ名を指定します |
|
|
移行プロセスの開始が必要なキュー(AQ)の名前を指定します。 cqnameが |
|
|
ターゲットTxEventQの作成先にするスキーマ名を指定します。この値は、 呼出し元のスキーマが |
|
|
作成するターゲットTxEventQのキューの名前を指定します。この値は、 |
|
|
移行モードを指定します。次は、返される値です。
ノート:
|
|
|
ユーザーが従うメッセージ・レベルの順序付けを指定します。次は、返される値です。
|
|
|
暫定的なTxEventQに名前を付けるための単一文字の接尾辞を指定します。暫定的なTxEventQ名は、 |
使用上のノート
-
このプロシージャは、
AQ$_<TxEventQ_name>_Eという命名形式に従って、TxEventQにデフォルトの例外キューも作成します。 -
次の事項は、
DBMS_AQMIGTOOL.ONLY_DEFINITIONモードには関係ありませんが、その他のモードに適用されます。-
暫定的なTxEventQの構成整合性を維持するために、移行の完了または取消しまでAQの管理操作を制限します。
-
AQのエンキュー操作とデキュー操作は許可されます:
-
新しいメッセージのエンキュー・リクエストは、暫定的なTxEventQに送信されます。
-
メッセージは、最初にAQからデキューされます。
READY状態のメッセージがない場合、メッセージは暫定的なTxEventQからデキューされます。
-
-
ユーザーは、暫定的なTxEventQに対してすべての直接操作を実行できないように制限されます。暫定的なTxEventQに対するエンキュー操作とデキュー操作は、常にAQを通じて実行されます。
-
-
サポートされていない機能の検出によってプロシージャが例外をトリガーする場合は、
DBMS_AQMIGTOOL.CHECK_MIGRATION_TO_TXEVENTQプロシージャを使用して、検出されたサポートされていない機能の詳細リストを取得することをお薦めします。 -
移行するキュー(AQ)が、そのキューが存在するキュー表と同じ名前を共有する場合など、名前の競合がある場合は、
DBMS_AQMIGTOOL.ONLY_DEFINITIONモードのみがサポートされます。その他のモードでは、続行しようとすると例外が発生します。
29.3.9 PURGE_QUEUE_MESSAGESプロシージャ
このプロシージャでは、キューからメッセージをパージします。ユーザー入力に応じて、AQまたは暫定的なTxEventQ(あるいはその両方)からのメッセージのパージを実行できます。具体的には、DBMS_AQMIGTOOL.COMMIT_MIGRATIONを実行するための前提条件の1つに、READY状態のメッセージが存在しない空のAQの確保があります。このプロシージャを使用すると、ユーザーはAQからすべてのメッセージを効率的にパージして、この要件を満たすことができます。
構文
PROCEDURE DBMS_AQMIGTOOL.PURGE_QUEUE_MESSAGES ( cqschema IN VARCHAR2, cqname IN VARCHAR2, purge_option IN NUMBER DEFAULT DBMS_AQMIGTOOL.ONLY_CQ);
パラメータ
表29-11 PURGE_QUEUE_MESSAGESプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
移行プロセスが開始されたキューの名前を指定します |
|
|
パージが必要になるキュー・メッセージのオプションを指定します。次のオプションを使用できます。
|
使用上のノート
AQ内のREADY状態のメッセージ数がDBMS_AQMIGTOOL.CHECK_MIGRATED_MESSAGEプロシージャから取得されていて、ユーザーがメッセージの利用のためのデキューを待たずにDBMS_AQMIGTOOL.COMMIT_MIGRATIONプロセスを高速化するように希望している場合は、DBMS_AQMIGTOOL.PURGE_QUEUE_MESSAGESプロシージャを使用できます。
このプロシージャの前提条件は、すでにキューで移行が開始されている必要があることです。これは、このプロシージャの実行前に、DBMS_AQMIGTOOL.INIT_MIGRATIONが呼び出されている必要があるということです。
29.3.10 RECOVER_MIGRATIONプロシージャ
このプロシージャは、DBMS_AQMIGTOOL.CANCEL_MIGRATION、DBMS_AQMIGTOOL.COMMIT_MIGRATIONまたはDBMS_AQMIGTOOL.INIT_MIGRATIONの実行前後で、最も近い実行可能な一貫性のあるポイントに移行状態をリストアします。その後、リカバリされた状態が出力パラメータrecovery_messageによってユーザーに表示され、この先の処置に関するガイダンスが得られます。移行のプロシージャでインスタンスのクラッシュなどの予期しない障害が発生した場合は、このプロシージャを使用すると、INIT_MIGRATIONの前、INIT_MIGRATIONの後、COMMIT_MIRGATIONの後、CANCEL_MIGRATIONの後など、最も近い一貫性のある状態に移行をリカバリできます。
構文
PROCEDURE DBMS_AQMIGTOOL.RECOVER_MIGRATION ( cqschema IN VARCHAR2, cqname IN VARCHAR2, recovery_message OUT VARCHAR2);
パラメータ
表29-12 RECOVER_MIGRATIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
移行プロセスが試行されたキューの名前を指定します |
|
|
リストアされた移行状態の最も近い実行可能な一貫性のあるポイントを示す説明メッセージを返します |
使用上のノート
次の表に、その可能性があるすべてのrecovery_messageを示します:
表29-13 recovery_messageに応じた推奨アクションの表
| 移行プロシージャの実行中にエラーが発生しました: | recovery_message | 推奨アクション |
|---|---|---|
|
|
|
移行を開始するために、ユーザーは明示的に |
|
|
|
移行を開始するためにその他のアクションは不要です。このプロシージャは正常に開始されています。 |
|
|
|
移行を完了するためにその他のアクションは不要です。このプロシージャは正常に移行を完了しています。 |
|
|
|
移行の取消しを続行するために、ユーザーは明示的に |
|
|
|
移行を取り消すためにその他のアクションは不要です。このプロシージャは正常に移行を取り消しています。 |
|
|
|
移行プロシージャの実行が検出されないため、最も近い実行可能な一貫性のあるポイントにリストアする必要はありません。 |
29.3.11 RENAME_QUEUEプロシージャ
このプロシージャは、デフォルトの例外キュー(存在する場合)とともにTxEventQの名前を変更します。
構文
PROCEDURE DBMS_AQMIGTOOL.RENAME_QUEUE ( schema IN VARCHAR2, qname IN VARCHAR2, new_qname IN VARCHAR2);
パラメータ
表29-14 RENAME_QUEUEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キューが存在するスキーマ名を指定します |
|
|
名前を変更するキューの現在の名前を指定します |
|
|
既存のキューに割り当てる新しい名前を指定します。名前はスキーマ内で重複しないようにし、予約語については、『Oracle Database SQL言語リファレンス』のオブジェクト名のガイドラインに従う必要があります。 |
使用上のノート
このプロシージャには前提条件ステップが必要です。ユーザーはDBMS_AQADM.STOP_QUEUEを実行して、同時のエンキューおよびデキュー・トランザクションが存在しないようにする必要があります。
デフォルトの例外キューが存在する場合、その名前は<schema>.AQ$_<qname>_Eから<schema>.AQ$_<new_qname>_Eに変更されます。