使用DBMS_AQADM包管理訊息佇列和隊列表-雲原生資料庫 PolarDB-阿里雲

您可以使用DBMS_AQADM包中的預存程序建立並管理訊息佇列和隊列表。

說明

使用DBMS_AQADM包中的預存程序建立和管理訊息佇列和隊列表，需要使用超級使用者操作，如您有相應需求，請聯絡我們處理。

表 1. DBMS_AQADM函數/預存程序

函數/預存程序	傳回型別	說明
ALTER_QUEUE	N/A	修改現有的隊列。
ALTER_QUEUE_TABLE	N/A	修改現有的隊列表。
CREATE_QUEUE	N/A	建立隊列。
CREATE_QUEUE_TABLE	N/A	建立隊列表。
DROP_QUEUE	N/A	刪除現有隊列。
DROP_QUEUE_TABLE	N/A	刪除現有隊列表。
PURGE_QUEUE_TABLE	N/A	從隊列表中刪除一個或多個訊息。
START_QUEUE	N/A	使隊列對於入隊和出隊過程可用。
STOP_QUEUE	N/A	使隊列對於入隊和出隊過程不可用。

PolarDB PostgreSQL版（相容Oracle）支援使用下面列出的參數：

常量	說明	適用參數
DBMS_AQADM.TRANSACTIONAL(1)	此常量已定義，但是，如果使用會返回錯誤。	message_grouping
DBMS_AQADM.NONE(0)	用於為隊列表指定訊息分組。	message_grouping
DBMS_AQADM.NORMAL_QUEUE(0)	與create_queue一起使用來指定queue_type。	queue_type
DBMS_AQADM.NORMAL_QUEUE(0)	與create_queue一起使用來指定queue_type。	queue_type
DBMS_AQADM.INFINITE(-1)	與create_queue 一起使用來指定retention_time。	retention_time
DBMS_AQADM.PERSISTENT (0)	此訊息應儲存在表中。	enqueue_options_t.delivery_mode
DBMS_AQADM.BUFFERED (1)	此常量已定義，但是，如果使用會返回錯誤。	enqueue_options_t.delivery_mode
DBMS_AQADM.PERSISTENT_OR_BUFFERED (2)	此常量已定義，但是，如果使用會返回錯誤。	enqueue_options_t.delivery_mode

使用說明

ALTER_QUEUE

使用ALTER_QUEUE預存程序修改現有隊列。

文法

ALTER_QUEUE(
  max_retries IN NUMBER DEFAULT NULL,
  retry_delay IN NUMBER DEFAULT 0
  retention_time IN NUMBER DEFAULT 0,
  auto_commit IN BOOLEAN DEFAULT TRUE)
  comment IN VARCHAR2 DEFAULT NULL,

參數

參數	描述
queue_name	新隊列的名稱。
max_retries	指定使用`dequeue`語句刪除訊息的最大嘗試次數。 max_retries的值會隨著`ROLLBACK`語句的數量而增加。當失敗的嘗試次數達到max_retries指定的值之後，訊息將移動到異常隊列。當指定為0時，表示不允許重試。
retry_delay	指定在`ROLLBACK`之後計劃重新處理訊息等待的秒數。預設值為0，表示應立即重試訊息。
retention_time	指定訊息在出隊之後進行儲存所經過的時間長度。單位：秒。說明指定為預設值0時，表示訊息在出隊之後不應保留。指定為INFINITE時，表示長期保留訊息。
comment	指定與隊列關聯的注釋。

樣本

以下代碼塊，將 work_order的隊列中的retry_delay參數設定為5秒：

EXEC DBMS_AQADM.ALTER_QUEUE(queue_name => 'work_order', retry_delay => 5);

ALTER_QUEUE_TABLE

使用ALTER_QUEUE_TABLE 預存程序修改現有隊列表。

文法

ALTER_QUEUE_TABLE (
  queue_table IN VARCHAR2,
  comment IN VARCHAR2 DEFAULT NULL,
  primary_instance IN BINARY_INTEGER DEFAULT 0,
  secondary_instance IN BINARY_INTEGER DEFAULT 0,

參數

參數	描述
queue_table	隊列表的名稱。
comment	使用comment參數可以提供有關隊列表的注釋。
primary_instance	為了實現相容性而支援此參數，可忽略。
secondary_instance	為了實現相容性而支援此參數，可忽略。

樣本

以下命令修改名為work_order_table 的隊列表：

EXEC DBMS_AQADM.ALTER_QUEUE_TABLE
      (queue_table => 'work_order_table', comment => 'This queue table contains work orders for the shipping department.');

CREATE_QUEUE

使用CREATE_QUEUE 預存程序在現有隊列表中建立隊列。

文法

CREATE_QUEUE(
  queue_name IN VARCHAR2
  queue_table IN VARCHAR2,
  queue_type IN BINARY_INTEGER DEFAULT NORMAL_QUEUE,
  max_retries IN NUMBER DEFAULT 5,
  retry_delay IN NUMBER DEFAULT 0
  retention_time IN NUMBER DEFAULT 0,
  dependency_tracking IN BOOLEAN DEFAULT FALSE,
  comment IN VARCHAR2 DEFAULT NULL,
  auto_commit IN BOOLEAN DEFAULT TRUE)

參數

參數	描述
queue_name	新隊列的名稱。
queue_table	新隊列所在的表的名稱。
queue_type	新隊列的類型。queue_type取值如下： DBMS_AQADM.NORMAL_QUEUE：此值指定普通隊列（預設值）。 DBMS_AQADM.EXCEPTION_QUEUE：此值指定新隊列是異常隊列。異常隊列僅支援出隊操作。
max_retries	指定使用`dequeue` 語句刪除訊息的最大嘗試次數。`dequeue`的值隨著`ROLLBACK`語句數量的增加而增加。當失敗的嘗試次數達到max_retries指定的值之後，訊息移動到異常隊列。系統資料表的預設值為0；使用者建立的表的預設值為5。
retry_delay	指定在`ROLLBACK`之後計劃重新處理訊息等待的秒數。當指定為預設值0時，表示應立即重試訊息。
retention_time	指定訊息在出隊之後進行儲存所經過的時間長度。單位：秒。說明指定為預設值0時，表示訊息在出隊之後不應保留。指定為INFINITE時，表示長期保留訊息。
dependency_tracking	為了實現相容性而支援此參數，但被忽略。
comment	指定與隊列關聯的注釋。
auto_commit	為了實現相容性而支援此參數，可忽略。

樣本

以下匿名塊在work_order_table表中建立名為work_order 的隊列：

BEGIN
DBMS_AQADM.CREATE_QUEUE ( queue_name => 'work_order', queue_table => 'work_order_table', comment => 'This queue contains pending work orders.');
END;

CREATE_QUEUE_TABLE

使用CREATE_QUEUE_TABLE 預存程序建立隊列表。

文法

CREATE_QUEUE_TABLE (
  queue_table IN VARCHAR2,
  queue_payload_type IN VARCHAR2,
  storage_clause IN VARCHAR2 DEFAULT NULL,
  sort_list IN VARCHAR2 DEFAULT NULL,
  multiple_consumers IN BOOLEAN DEFAULT FALSE,
  message_grouping IN BINARY_INTEGER DEFAULT NONE,
  comment IN VARCHAR2 DEFAULT NULL,
  auto_commit IN BOOLEAN DEFAULT TRUE,
  primary_instance IN BINARY_INTEGER DEFAULT 0,
  secondary_instance IN BINARY_INTEGER DEFAULT 0,
  compatible IN VARCHAR2 DEFAULT NULL,
  secure IN BOOLEAN DEFAULT FALSE)

參數

參數	描述
queue_table	隊列表的名稱。
queue_payload_type	儲存在隊列表中的使用者自訂的資料類型。說明如果要指定RAW資料類型，您必須在使用者定義型別中建立RAW資料類型。
storage_clause	指定隊列表的屬性。 storage_clause可以是以下一項或多項： TABLESPACE tablespace_name PCTFREE integer PCTUSED integer INITRANS integer MAXTRANS integer STORAGE storage_option storage_option 可以是以下一項或多項： MINEXTENTS integer MAXEXTENTS integer PCTINCREASE integer INITIAL size_clause NEXT FREELISTS integer OPTIMAL size_clause BUFFER_POOL {KEEP\|RECYCLE\|DEFAULT}
sort_list	控制隊列的出隊順序。指定將用於對隊列進行排序（升序）的列名稱。當前取值如下： enq_time, priority priority, enq_time priority enq_time
multiple_consumers	如果指定，multiple_consumers必須為FALSE。
message_grouping	如果指定，message_grouping必須為 NONE。
comment	提供有關隊列表的注釋。
auto_commit	為了實現相容性而支援此參數，可忽略。
primary_instance	為了實現相容性而支援此參數，可忽略。
secondary_instance	為了實現相容性而支援此參數，可忽略。
compatible	為了實現相容性而支援此參數，可忽略。
secure	為了實現相容性而支援此參數，可忽略。

樣本

以下匿名塊首先建立work_order類型，該類型具有儲存名稱VARCHAR2的屬性，以及專案說明。然後，使用該類型建立隊列表：

BEGIN

CREATE TYPE work_order AS (name VARCHAR2, project TEXT, completed BOOLEAN);

EXEC DBMS_AQADM.CREATE_QUEUE_TABLE
      (queue_table => 'work_order_table',
       queue_payload_type => 'work_order',
       comment => 'Work order message queue table');
END;

隊列表名為work_order_table，包含類型為work_order的承載。注釋說明為Work order message queue table。

DROP_QUEUE

使用DROP_QUEUE 預存程序可以刪除隊列。

文法

DROP_QUEUE(
  queue_name  IN VARCHAR2,
  auto_commit IN BOOLEAN DEFAULT TRUE)

參數

參數	描述
queue_name	要刪除的隊列的名稱。
auto_commit	為了實現相容性而支援此參數，但被忽略。

樣本

以下匿名塊刪除名為work_order的隊列：

BEGIN
DBMS_AQADM.DROP_QUEUE(queue_name => 'work_order');
END;

DROP_QUEUE_TABLE

使用DROP_QUEUE_TABLE預存程序可以刪除隊列表。

文法

DROP_QUEUE_TABLE(
  queue_table IN VARCHAR2,
  force IN BOOLEAN default FALSE,
  auto_commit IN BOOLEAN default TRUE)

參數

參數	描述
queue_table	隊列表的名稱。
force	指定`DROP_QUEUE_TABLE`命令在刪除包含專案的表時的行為：如果目標表包含專案且force 為FALSE時，則該命令將失敗，並且伺服器將發出錯誤。如果目標表包含專案且force 為 TRUE時，則該命令將刪除表以及任何從屬對象。
auto_commit	為了實現相容性而支援此參數，但被忽略。

樣本

以下匿名塊刪除名為work_order_table 的表：

BEGIN
   DBMS_AQADM.DROP_QUEUE_TABLE ('work_order_table', force => TRUE);
END;

PURGE_QUEUE_TABLE

使用PURGE_QUEUE_TABLE預存程序可以從隊列表中刪除訊息。

文法

PURGE_QUEUE_TABLE(
  queue_table IN VARCHAR2,
  purge_condition IN VARCHAR2,
  purge_options IN aq$_purge_options_t)

參數

參數	描述
queue_table	指定從中刪除訊息的隊列表的名稱。
purge_condition	指定伺服器在決定要清除哪些訊息時將評估的條件（WHERE子句）。
purge_options	purge_options是類型為`aq$_purge_options_t`的對象。`aq$_purge_options_t`對象包含內容請參見aq$_purge_options_t。

表 2. aq$_purge_options_t

屬性

類型

說明

Block

Boolean

在表中所有隊列上是否保有獨佔鎖定。

取值為TRUE時，表示表中所有隊列上存在獨佔鎖定。
取值為FALSE時，表示表中所有隊列上不存在獨佔鎖定。

delivery_mode

INTEGER

指定將清除的訊息類型。唯一可接受的值為DBMS_AQ.PERSISTENT。

樣本

以下匿名塊從work_order_table中刪除completed 列值為YES的任何訊息：

DECLARE
   purge_options dbms_aqadm.aq$_purge_options_t;
BEGIN
   dbms_aqadm.purge_queue_table('work_order_table', 'completed = YES', purge_options);
  END;

START_QUEUE

使用START_QUEUE預存程序使隊列可用於排隊和清除佇列。

文法

START_QUEUE(
  queue_name IN VARCHAR2,
  enqueue IN BOOLEAN DEFAULT TRUE,
  dequeue IN BOOLEAN DEFAULT TRUE)

參數

參數	描述
queue_name	指定要啟動的隊列的名稱。
enqueue	指定TRUE（預設）時，啟用排隊。指定FALSE時，保持當前設定不變。
dequeue	指定TRUE（預設）時，清除佇列。指定FALSE時，保持當前設定不變。

樣本

以下匿名塊使名為work_order的隊列可用於排隊：

BEGIN
DBMS_AQADM.START_QUEUE
(queue_name => 'work_order);
END;

STOP_QUEUE

使用STOP_QUEUE預存程序在指定隊列中禁用排隊或清除佇列。

文法

STOP_QUEUE(
  queue_name IN VARCHAR2,
  enqueue IN BOOLEAN DEFAULT TRUE,
  dequeue IN BOOLEAN DEFAULT TRUE,
  wait IN BOOLEAN DEFAULT TRUE)

參數

參數	描述
queue_name	指定要停止的隊列的名稱。
enqueue	指定TRUE（預設）時，禁用排隊。指定FALSE時，保持當前設定不變。
dequeue	指定TRUE（預設）時，禁用出隊。指定FALSE時，保持當前設定不變。
wait	指定為TRUE時，表示伺服器等待任何未完成的事務完成，然後再應用指定的更改。在等待停止隊列時，在指定隊列中不允許任何事務排隊或清除佇列。指定為FALSE時，立即停止隊列。

樣本

以下匿名塊在名為work_order的隊列中禁用排隊和清除佇列：

BEGIN
DBMS_AQADM.STOP_QUEUE(queue_name =>'work_order', enqueue=>TRUE, dequeue=>TRUE, wait=>TRUE);
END;

排隊和清除佇列將在任何未完成的事務完成之後停止。