21. API: Async Advanced Queuing (AQ)

See Using Oracle Transactional Event Queues and Advanced Queuing for more information about using AQ in python-oracledb.

Added in version 3.1.0.

Note

AsyncQueue objects are only supported in python-oracledb Thin mode.

21.1. AsyncQueue Class

class oracledb.AsyncQueue

An AsyncQueue object should be created using AsyncConnection.queue() and is used to enqueue and dequeue messages.

21.1.1. AsyncQueue Methods

async AsyncQueue.deqmany(max_num_messages: int) → list[MessageProperties]

Dequeues up to the specified number of messages from the queue and returns a list of these messages.

async AsyncQueue.deqone() → MessageProperties | None

Dequeues at most one message from the queue and returns it. If no message is dequeued, None is returned.

async AsyncQueue.enqmany(messages: list[MessageProperties]) → None

Enqueues multiple messages into the queue. The messages parameter must be a sequence containing message property objects which have all had their payload attribute set to a value that the queue supports.

Warning: calling this function in parallel on different connections acquired from the same pool may fail due to Oracle bug 29928074. Ensure that this function is not run in parallel, use standalone connections or connections from different pools, or make multiple calls to enqone() instead. The function Queue.deqmany() call is not affected.

async AsyncQueue.enqone(message: MessageProperties) → None

Enqueues a single message into the queue. The message must be a message property object which has had its payload attribute set to a value that the queue supports.

21.1.2. AsyncQueue Attributes

property AsyncQueue.connection: Connection

This read-only attribute returns a reference to the connection object on which the queue was created.

property AsyncQueue.deqoptions: DeqOptions

This read-only attribute returns a reference to the options that will be used when dequeuing messages from the queue.

property AsyncQueue.enqoptions: EnqOptions

This read-only attribute returns a reference to the options that will be used when enqueuing messages into the queue.

property AsyncQueue.name: str

This read-only attribute returns the name of the queue.

property AsyncQueue.payload_type: DbObjectType | None

This read-only attribute returns the object type for payloads that can be enqueued and dequeued. If using a JSON queue, this returns the value “JSON”. If using a raw queue, this returns the value None.

21.2. DeqOptions Class

A DeqOptions object is used to configure how messages are dequeued from queues. An instance of this object is found in the attribute AsyncQueue.deqoptions.

See DeqOptions Class for information on the supported attributes.

21.3. EnqOptions Class

An EnqOptions object is used to configure how messages are enqueued into queues. An instance of this object is found in the attribute AsyncQueue.enqoptions.

See EnqOptions Class for information on the supported attributes.

21.4. MessageProperties Class

A MessageProperties object is used to identify the properties of messages that are enqueued and dequeued in queues. They are created by the method AsyncConnection.msgproperties(). They are used by the method AsyncQueue.enqone() and returned by the method AsyncQueue.deqone().

See MessageProperties Class for information on the supported attributes.