DBMS_AQ - - Alibaba Cloud ドキュメントセンター

Oracle 互換の PolarDB データベースは、メッセージキューとメッセージ処理をサポートしています。ユーザー定義メッセージはキューに格納されています。キューのコレクションは、キューテーブルに格納されています。 DBMS_AQADM パッケージのプロシージャを使用して、メッセージキューおよびキューテーブルを作成および管理することができます。 DBMS_AQ パッケージを使用して、キューにメッセージを追加したり、キューからメッセージを削除したり、PL/SQL コールバックプロシージャを登録または登録解除したりすることができます。

Oracle 互換の PolarDB データベースは、以下の SQL コマンドを実行することにより、DBMS_AQ パッケージに互換性のない拡張機能も提供します。

ALTER QUEUE
ALTER QUEUE TABLE
CREATE QUEUE
CREATE QUEUE TABLE
DROP QUEUE
DROP QUEUE TABLE

DBMS_AQ パッケージは、メッセージのエンキュー、メッセージのデキュー、およびコールバックプロシージャの管理を可能にするプロシージャを提供しています。下表に、サポートされているパス式を示します。


関数/プロシージャ	戻り値の型	説明
ENQUEUE	N/A	メッセージをキューに投稿します。
DEQUEUE	N/A	メッセージが利用可能になった直後にキューからメッセージを取得します。
REGISTER	N/A	コールバックプロシージャを登録します。
UNREGISTER	N/A	コールバックプロシージャの登録を解除します。

Oracle 互換性の PolarDB データベースでの DBMS_AQ の実装は、ネイティブ Oracle と比較すると部分的な実装です。上記の表にリストされているプロシージャのがサポートされています。

下表に、Oracle 互換の PolarDB データベースでサポートされている定数を示します。


定数	説明	適用パラメーター
DBMS_AQ.BROWSE (0)	ロックせずにメッセージを読み取ります。	dequeue_options_t.dequeue_mode
DBMS_AQ.LOCKED (1)	この定数は現在使用されていません。この定数を使用すると、エラーメッセージが返されます。	dequeue_options_t.dequeue_mode
DBMS_AQ.REMOVE (2)	読み取り後にメッセージを削除します。この値がデフォルト値です。	dequeue_options_t.dequeue_mode
DBMS_AQ.REMOVE_NODATA (3)	この定数は現在使用されていません。この定数を使用すると、エラーメッセージが返されます。	dequeue_options_t.dequeue_mode
DBMS_AQ.FIRST_MESSAGE (0)	検索条件に一致する最初の使用可能なメッセージを返します。	dequeue_options_t.navigation
DBMS_AQ.NEXT_MESSAGE (1)	検索条件に一致する、次に使用可能なメッセージを返します。	dequeue_options_t.navigation
DBMS_AQ.NEXT_TRANSACTION (2)	この定数は現在使用されていません。この定数を使用すると、エラーメッセージが返されます。	dequeue_options_t.navigation
DBMS_AQ.FOREVER (0)	検索条件に一致するメッセージが見つからない場合、待機を続けます。これがデフォルト値です。	dequeue_options_t.wait
DBMS_AQ.NO_WAIT (1)	検索条件に一致するメッセージが見つからない場合は待機しません。	dequeue_options_t.wait
DBMS_AQ.ON_COMMIT (0)	デキューは現在のトランザクションの一部です。	enqueue_options_t.visibility, dequeue_options_t.visibility
DBMS_AQ.IMMEDIATE (1)	この定数は現在使用されていません。この定数を使用すると、エラーメッセージが返されます。	enqueue_options_t.visibility, dequeue_options_t.visibility
DBMS_AQ.PERSISTENT (0)	メッセージはテーブルに保存する必要があります。	enqueue_options_t.delivery_mode
DBMS_AQ.BUFFERED (1)	この定数は現在使用されていません。この定数を使用すると、エラーメッセージが返されます。	enqueue_options_t.delivery_mode
DBMS_AQ.READY (0)	メッセージを処理する準備ができていることを示します。	message_properties_t.state
DBMS_AQ.WAITING (1)	メッセージが処理待ちであることを示します。	message_properties_t.state
DBMS_AQ.PROCESSED (2)	メッセージが処理されたことを明示します。	message_properties_t.state
DBMS_AQ.EXPIRED (3)	メッセージが例外キューにあることを示します。	message_properties_t.state
DBMS_AQ.NO_DELAY (0)	この定数は現在使用されていません。この定数を使用すると、エラーメッセージが返されます。	message_properties_t.delay
DBMS_AQ.NEVER (NULL)	この定数は現在使用されていません。この定数を使用すると、エラーメッセージが返されます。	message_properties_t.expiration
DBMS_AQ.NAMESPACE_AQ (0)	DBMS_AQ キューからの通知を受け入れます。	sys.aq$_reg_info.namespace
DBMS_AQ.NAMESPACE_ANONYMOUS (1)	この定数は現在使用されていません。この定数を使用すると、エラーメッセージが返されます。	sys.aq$_reg_info.namespace

ENQUEUE

ENQUEUE プロシージャを使用して、キューにエントリを追加できます。プロシージャには以下の署名があります。

ENQUEUE(
  queue_name IN VARCHAR2,
  enqueue_options IN DBMS_AQ.ENQUEUE_OPTIONS_T,
  message_properties IN DBMS_AQ.MESSAGE_PROPERTIES_T,
  payload IN <type_name>,
  msgid OUT RAW)

パラメーター

queue_name
既存のキューの名前。これはスキーマで修飾された名前の場合があります。スキーマ名を省略すると、サーバーは SEARCH_PATH で指定されたスキーマを使用します。 Oracle とは異なり、引用符で囲まれていない識別子は、識別子が格納される前に小文字に変換されます。特殊文字を含めるか、大文字と小文字を区別する名前を使用するには、名前を二重引用符で囲みます。

enqueue_options

enqueue_options パラメーターは、enqueue_options_t 型のパラメーターです。以下の例は、enqueue_options_t の構造を示しています。

DBMS_AQ.ENQUEUE_OPTIONS_T IS RECORD(
  visibility BINARY_INTEGER DEFAULT ON_COMMIT,
  relative_msgid RAW(16) DEFAULT NULL,
  sequence_deviation BINARY INTEGER DEFAULT NULL,
  transformation VARCHAR2(61) DEFAULT NULL,
  delivery_mode PLS_INTEGER NOT NULL DEFAULT PERSISTENT);

下表に、enqueue_options_t でサポートされている唯一のパラメーター値を示します。


visibility	ON_COMMIT
delivery_mode	PERSISTENT
sequence_deviation	NULL
transformation	NULL
relative_msgid	NULL

message_properties

message_properties パラメーターは、message_properties_t 型のパラメーターです。以下の例は、message_properties_t の構造を示しています。

      message_properties_t IS RECORD(
    priority INTEGER,
    delay INTEGER,
    expiration INTEGER,
    correlation CHARACTER VARYING(128) COLLATE pg_catalog." C",
    attempts INTEGER,
    recipient_list"AQ$_RECIPIENT_LIST_T",
    exception_queue CHARACTER VARYING(61) COLLATE pg_catalog." C",
    enqueue_time TIMESTAMP WITHOUT TIME ZONE,
      state INTEGER,
     original_msgid BYTEA,
      transaction_group CHARACTER VARYING(30) COLLATE pg_catalog." C",
      delivery_mode INTEGER
    DBMS_AQ.PERSISTENT);

下表に、message_properties_t でサポートされている値を示します。


パラメーター	説明
priority	キューテーブルの定義に優先度を参照する sort_list が含まれている場合、このパラメーターはメッセージがデキューされる順序に影響します。値が小さいほど、デキューの優先順位が高くなります。
delay	メッセージがデキュー可能になるまでに経過した秒数。 NO_DELAY 定数は、メッセージが利用可能になった直後にメッセージがデキューされることを指定します。
expiration	メッセージの有効期限が切れるまでの秒数。
correlation	エントリに関連付けられたメッセージ。デフォルト値は NULL です。
attempts	メッセージのデキューを試行した回数。このパラメーターはシステムによって維持されます。
recipient_list	この演算子はサポートされていません。
exception_queue	メッセージが期限切れになるか、過度の時間をロールバックするトランザクションによってデキューされる場合に、メッセージが移動される例外キューの名前。
enqueue_time	ユーザーがプロジェクトに追加された時刻。この値はシステムによって提供されます。
state	このパラメーターは、DBMS_AQ によって維持されます。有効値： DBMS_AQ.READY：遅延に達していません。 DBMS_AQ.WAITING：キューエントリを処理する準備ができました。 DBMS_AQ.PROCESSED：キューエントリが処理されました。 DBMS_AQ.EXPIRED：キューエントリが例外キューに移動されました。
original_msgid	このパラメーターは無視されますが、互換性のために含まれています。
transaction_group	このパラメーターは無視されますが、互換性のために含まれています。
delivery_mode	この演算子はサポートされていません。 DBMS_AQ.PERSISTENT の値を指定します。

payload
payload パラメーターを使用して、キューエントリに関連付けられたデータを提供することができます。ペイロードタイプは、対応するキューテーブルを作成するときに指定したタイプと一致する必要があります。詳細については、DBMS_AQADM.CREATE_QUEUE_TABLE をご参照ください。
msgid
msgid パラメーターを使用して、システムによって生成された固有のメッセージ識別子を取得することができます。

例

以下の無名ブロックは、DBMS_AQ.ENQUEUE を呼び出して、work_order という名前のキューにメッセージを追加します。

DECLARE

  enqueue_options    DBMS_AQ.ENQUEUE_OPTIONS_T;
  message_properties DBMS_AQ.MESSAGE_PROPERTIES_T;
  message_handle     raw(16);
  payload            work_order;

BEGIN

  payload := work_order('Smith', 'system upgrade');

DBMS_AQ.ENQUEUE(
  queue_name         => 'work_order',
  enqueue_options    => enqueue_options,
  message_properties => message_properties,
  payload            => payload,
  msgid              => message_handle
    );
 END;

DEQUEUE

DEQUEUE プロシージャを使用して、メッセージをデキューすることができます。プロシージャには以下の署名があります。

DEQUEUE(
  queue_name IN VARCHAR2,
  dequeue_options IN DBMS_AQ.DEQUEUE_OPTIONS_T,
  message_properties OUT DBMS_AQ.MESSAGE_PROPERTIES_T,
  payload OUT type_name,
  msgid OUT RAW)

パラメーター

queue_name
既存のキューの名前。これはスキーマで修飾された名前の場合があります。スキーマ名を省略すると、サーバーは SEARCH_PATH で指定されたスキーマを使用します。 Oracle とは異なり、引用符で囲まれていない識別子は、識別子が格納される前に小文字に変換されます。特殊文字を含めるか、大文字と小文字を区別する名前を使用するには、名前を二重引用符で囲みます。

dequeue_options

dequeue _options パラメーターは、dequeue_options_t 型のパラメーターです。以下の例は、dequeue_options_t の構造を示しています。

DEQUEUE_OPTIONS_T IS RECORD(
  consumer_name CHARACTER VARYING(30),
  dequeue_mode INTEGER,
  navigation INTEGER,
  visibility INTEGER,
  wait INTEGER,
  msgid BYTEA,
  correlation CHARACTER VARYING(128),
  deq_condition CHARACTER VARYING(4000),
  transformation CHARACTER VARYING(61),
  delivery_mode INTEGER);

次の表に、dequeue_options_t でサポートされる唯一のパラメーター値を示します。


パラメーター	説明
consumer_name	NULL である必要があります。
dequeue_mode	デキュー操作のロック動作。有効値： DBMS_AQ.BROWSE：ロックを取得せずにメッセージを読み取ります。 DBMS_AQ.LOCKED：ロックを取得した後にメッセージを読み取ります。 DBMS_AQ.REMOVE：メッセージを削除する前にメッセージを読み取ります。 DBMS_AQ.REMOVE_NODATA：メッセージを読み取りますが、メッセージは削除しません。
navigation	取得するメッセージを指定します。有効値： FIRST_MESSAGE：検索基準に一致するキュー内の最初のメッセージ。 NEXT_MESSAGE：最初の用語に一致する次の使用可能なメッセージ。
visibility	ON_COMMIT である必要があります。現在のトランザクションをロールバックすると、デキューされたアイテムはキューに残ります。
wait	0 より大きい数値、または以下の値に設定する必要があります。 DBMS_AQ.FOREVER: waits indefinitely. DBMS_AQ.NO_WAIT: does not wait.
msgid	デキューされるメッセージの ID。
correlation	このパラメーターは無視されますが、互換性のために含まれています。
deq_condition	BOOLEAN 値を計算し、メッセージをデキューする必要があるかどうかを指定するVARCHAR2 式。
transformation	このパラメーターは無視されますが、互換性のために含まれています。
delivery_mode	PERSISTENT である必要があります。このモードでは、バッファー済みのメッセージはサポートされていません。

message_properties

message_properties パラメーターは、message_properties_t type のパラメーターです。以下の例は、message_properties_t の構造を示しています。

    message_properties_t IS RECORD(
    priority INTEGER,
    delay INTEGER,
    expiration INTEGER,
    correlation CHARACTER VARYING(128) COLLATE pg_catalog." C",
    attempts INTEGER,
    recipient_list"AQ$_RECIPIENT_LIST_T",
    exception_queue CHARACTER VARYING(61) COLLATE pg_catalog." C",
    enqueue_time TIMESTAMP WITHOUT TIME ZONE,
    state INTEGER,
    original_msgid BYTEA,
    transaction_group CHARACTER VARYING(30) COLLATE pg_catalog." C",
    delivery_mode INTEGER
  DBMS_AQ.PERSISTENT);

次の表に、message_properties_t でサポートされているパラメーターを示します。


パラメーター	説明
priority	キューテーブルの定義に優先度を参照する sort_list が含まれている場合、このパラメーターはメッセージがデキューされる順序に影響します。値が小さいほど、デキューの優先順位が高くなります。
delay	メッセージがデキュー可能になるまでに経過した秒数。 NO_DELAY 定数は、メッセージが利用可能になった直後にメッセージがデキューされることを指定します。
expiration	メッセージの有効期限が切れるまでの秒数。
correlation	エントリに関連付けられたメッセージ。デフォルト値は NULL です。
attempts	メッセージのデキューを試行した回数。このパラメーターはシステムによって維持されます。
recipient_list	この演算子はサポートされていません。
exception_queue	メッセージが期限切れになるか、過度の時間をロールバックするトランザクションによってデキューされる場合に、メッセージが移動される例外キューの名前。
enqueue_time	ユーザーがプロジェクトに追加された時刻。この値はシステムによって提供されます。
state	このパラメーターは、DBMS_AQ によって維持されます。有効値： DBMS_AQ.WAITING：遅延に達していません。 DBMS_AQ.READY：キューエントリを処理する準備ができました。 DBMS_AQ.PROCESSED：キューエントリが処理されました。 DBMS_AQ.EXPIRED：キューエントリが例外キューに移動されました。
original_msgid	このパラメーターは無視されますが、互換性のために含まれています。
transaction_group	このパラメーターは無視されますが、互換性のために含まれています。
delivery_mode	この演算子はサポートされていません。 DBMS_AQ.PERSISTENT の値を指定します。

payload
payload パラメーターを使用して、デキュー操作に関係するメッセージのペイロードを取得することができます。ペイロードタイプは、キューテーブルの作成時に指定したタイプと一致する必要があります。
msgid
msgid パラメーターを使用して、一意のメッセージ識別子を取得することができます。

例

以下の無名ブロックは、DBMS_AQ.DEQUEUE を呼び出して、キューおよびペイロードからメッセージを取得します。

DECLARE

  dequeue_options    DBMS_AQ.DEQUEUE_OPTIONS_T;
  message_properties DBMS_AQ.MESSAGE_PROPERTIES_T;
  message_handle     raw(16);
  payload            work_order;

BEGIN
  dequeue_options.dequeue_mode := DBMS_AQ.BROWSE;

  DBMS_AQ.DEQUEUE(
    queue_name         => 'work_queue',
    dequeue_options    => dequeue_options,
    message_properties => message_properties,
    payload            => payload,
    msgid              => message_handle
  );

  DBMS_OUTPUT.PUT_LINE(
  'The next work order is [' || payload.subject || '].'
  );
END;

ペイロードは、DBMS_OUTPUT.PUT_LINE によって表示されます。

REGISTER

REGISTER(
  reg_list IN SYS.AQ$_REG_INFO_LIST,
  count IN NUMBER)

パラメーター

reg_list

reg_list パラメーターは、AQ$_REG_INFO_LIST 型のリストを指定します。このリストは、登録する各サブスクリプションに関する情報を提供します。リスト内の各エントリは、AQ$_REG_INFO 型です。下表に、各エントリに含まれる属性を示します。


属性	データ型	説明
name	VARCHAR2 (128)	サブスクリプションの名前。これはスキーマで修飾された名前の場合があります。
namespace	NUMERIC	サポートされている唯一の値は DBMS_AQ.NAMESPACE_AQ (0) です。
callback	VARCHAR2 (4000)	通知時に実行されるアクションについて説明します。 PL/SQL プロシージャのみがサポートされています。プロシージャは以下の形式で呼び出されます。`plsql://schema.procedure` スキーマフィールドは、プロシージャが配置されているスキーマを指定します。プロシージャフィールドは、通知されるプロシージャの名前を指定します。
context	RAW (16)	コールバックプロシージャで必要なユーザー定義の値。

count
count パラメーターは、reg_list のエントリ数を指定します。

例

以下の無名ブロックは、DBMS_AQ.REGISTER を呼び出して、アイテムがキューに追加またはキューから削除されたときに通知されるプロシージャを登録します。 DECLARE セクションで識別されるサブスクリプションごとに、sys.aq$_reg_info 型の一連の属性が提供されます。

DECLARE
   subscription1 sys.aq$_reg_info;
   subscription2 sys.aq$_reg_info;
   subscription3 sys.aq$_reg_info;
   subscriptionlist sys.aq$_reg_info_list;
BEGIN
   subscription1 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, 'plsql://assign_worker? PR=0',HEXTORAW('FFFF'));
   subscription2 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, 'plsql://add_to_history? PR=1',HEXTORAW('FFFF'));
   subscription3 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, 'plsql://reserve_parts? PR=2',HEXTORAW('FFFF'));

   subscriptionlist := sys.aq$_reg_info_list(subscription1, subscription2, subscription3);
   dbms_aq.register(subscriptionlist, 3);
   commit;
  END;
   /

subscriptionlist パラメーターは sys.aq$_reg_info_list 型のパラメーターであり、この例で説明されている sys.aq$_reg_info オブジェクトが含まれています。リスト名とオブジェクト数は dbms_aq.register に渡されます。

UNREGISTER

UNREGISTER プロシージャを使用して、エンキューおよびデキューに関連する通知を無効にすることができます。プロシージャには以下の署名があります。

UNREGISTER(
  reg_list IN SYS.AQ$_REG_INFO_LIST,
  count
IN NUMBER)

パラメーター

reg_list

reg_list パラメーターは、AQ$_REG_INFO_LIST 型のリストを指定し、登録する各サブスクリプションに関する情報を提供します。リスト内の各エントリは、AQ$_REG_INFO 型です。次の表に、各エントリに含まれる属性を示します。


属性	データ型	説明
name	VARCHAR2 (128)	サブスクリプションの名前。これはスキーマで修飾された名前の場合があります。
namespace	NUMERIC	サポートされている唯一の値は DBMS_AQ.NAMESPACE_AQ (0) です。
callback	VARCHAR2 (4000)	通知時に実行されるアクションについて説明します。 PL/SQL プロシージャのみがサポートされています。プロシージャは次の形式で呼び出されます。`plsql://schema.procedure` スキーマフィールドは、プロシージャが配置されているスキーマを指定します。プロシージャフィールドは、通知されるプロシージャの名前を指定します。
context	RAW (16)	プロシージャで必要なユーザー定義の値。

count
count パラメーターは、reg_list のエントリ数を指定します。

例

以下の無名ブロックは、DBMS_AQ.UNREGISTER を呼び出して、DBMS_AQ.REGISTER の例で指定された通知を無効にします。

DECLARE
   subscription1 sys.aq$_reg_info;
   subscription2 sys.aq$_reg_info;
   subscription3 sys.aq$_reg_info;
   subscriptionlist sys.aq$_reg_info_list;
BEGIN
   subscription1 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, 'plsql://assign_worker? PR=0',HEXTORAW('FFFF'));
   subscription2 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, 'plsql://add_to_history? PR=1',HEXTORAW('FFFF'));
   subscription3 := sys.aq$_reg_info('q', DBMS_AQ.NAMESPACE_AQ, 'plsql://reserve_parts? PR=2',HEXTORAW('FFFF'));

   subscriptionlist := sys.aq$_reg_info_list(subscription1, subscription2, subscription3);
   dbms_aq.unregister(subscriptionlist, 3);
   commit;
  END;
   /

subscriptionlist パラメーターは sys.aq$_reg_info_list 型のパラメーターであり、この例で説明されている sys.aq$_reg_info オブジェクトが含まれています。リスト名とオブジェクト数は dbms_aq.unregister に渡されます。