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 プロシージャを使用して、アイテムがエンキューまたはデキューされたときに通知に使用される電子メールアドレス、プロシージャ、または URL を登録することができます。 プロシージャには以下の署名があります。
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
に渡されます。