15. API: Advanced Queuing (AQ)

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

15.1. Queue Class

class oracledb.Queue

A Queue object should be created using Connection.queue() and is used to enqueue and dequeue messages.

This object is an extension to the DB API definition.

15.1.1. Queue Methods

Queue.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.

For consistency and compliance with the PEP 8 naming style, the name of the method was changed from deqMany(). The old name will continue to work for a period of time.

Queue.deqone() → MessageProperties | None

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

For consistency and compliance with the PEP 8 naming style, the name of the method was changed from deqOne(). The old name will continue to work for a period of time.

Queue.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: In python-oracledb Thick mode using Oracle Client libraries prior to 21c, calling Queue.enqmany() in parallel on different connections acquired from the same connection pool may fail due to Oracle bug 29928074. To avoid this, do one of: upgrade the client libraries, ensure that Queue.enqmany() is not run in parallel, use standalone connections or connections from different pools, or make multiple calls to Queue.enqone(). The function Queue.deqmany() call is not affected.

For consistency and compliance with the PEP 8 naming style, the name of the method was changed from enqMany(). The old name will continue to work for a period of time.

Queue.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.

For consistency and compliance with the PEP 8 naming style, the name of the method was changed from enqOne(). The old name will continue to work for a period of time.

15.1.2. Queue Attributes

property Queue.connection: Connection

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

property Queue.deqoptions: DeqOptions

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

For consistency and compliance with the PEP 8 naming style, the name of the attribute was changed from deqOptions. The old name will continue to work for a period of time.

property Queue.enqoptions: EnqOptions

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

For consistency and compliance with the PEP 8 naming style, the name of the attribute was changed from enqOptions. The old name will continue to work for a period of time.

property Queue.name: str

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

property Queue.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.

For consistency and compliance with the PEP 8 naming style, the name of the attribute was changed from payloadType. The old name will continue to work for a period of time.

15.2. DeqOptions Class

class oracledb.DeqOptions

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

This object is an extension to the DB API definition.

15.2.1. DeqOptions Attributes

property DeqOptions.condition: str

This read-write attribute specifies a boolean expression similar to the where clause of a SQL query. The boolean expression can include conditions on message properties, user data properties, and PL/SQL or SQL functions. The default is to have no condition specified.

property DeqOptions.consumername: str

This read-write attribute specifies the name of the consumer. Only messages matching the consumer name will be accessed. If the queue is not set up for multiple consumers this attribute should not be set. The default is to have no consumer name specified.

property DeqOptions.correlation: str

This read-write attribute specifies the correlation identifier of the message to be dequeued. Special pattern-matching characters, such as the percent sign (%) and the underscore (_), can be used. If multiple messages satisfy the pattern, the order of dequeuing is indeterminate. The default is to have no correlation specified.

property DeqOptions.deliverymode: int

This write-only attribute specifies what types of messages should be dequeued. It should be one of the values MSG_PERSISTENT (default), MSG_BUFFERED, or MSG_PERSISTENT_OR_BUFFERED.

Note that MSG_BUFFERED is not supported for JSON payloads.

property DeqOptions.mode: int

This read-write attribute specifies the locking behaviour associated with the dequeue operation. It should be one of the values DEQ_BROWSE, DEQ_LOCKED, DEQ_REMOVE (default), or DEQ_REMOVE_NODATA.

property DeqOptions.msgid: bytes

This read-write attribute specifies the identifier of the message to be dequeued. The default is to have no message identifier specified.

property DeqOptions.navigation: int

This read-write attribute specifies the position of the message that is retrieved. It should be one of the values DEQ_FIRST_MSG, DEQ_NEXT_MSG (default), or DEQ_NEXT_TRANSACTION.

property DeqOptions.transformation: str

This read-write attribute specifies the name of the transformation that must be applied after the message is dequeued from the database but before it is returned to the calling application. The transformation must be created using dbms_transform. The default is to have no transformation specified.

property DeqOptions.visibility: int

This read-write attribute specifies the transactional behavior of the dequeue request. It should be one of the values DEQ_ON_COMMIT (default) or DEQ_IMMEDIATE. This attribute is ignored when using the DEQ_BROWSE mode. Note the value of autocommit is always ignored.

property DeqOptions.wait: int

This read-write attribute specifies the time to wait, in seconds, for a message matching the search criteria to become available for dequeuing. One of the values DEQ_NO_WAIT or DEQ_WAIT_FOREVER can also be used. The default is DEQ_WAIT_FOREVER.

15.3. EnqOptions Class

class oracledb.EnqOptions

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

This object is an extension to the DB API definition.

15.3.1. EnqOptions Attributes

property EnqOptions.deliverymode: int

This write-only attribute specifies what type of messages should be enqueued. It should be one of the values MSG_PERSISTENT (default) or MSG_BUFFERED.

Note that MSG_BUFFERED is not supported for JSON payloads.

property EnqOptions.transformation: str

This read-write attribute specifies the name of the transformation that must be applied before the message is enqueued into the database. The transformation must be created using dbms_transform. The default is to have no transformation specified.

property EnqOptions.visibility: int

This read-write attribute specifies the transactional behavior of the enqueue request. It should be one of the values ENQ_ON_COMMIT (default) or ENQ_IMMEDIATE. Note the value of autocommit is ignored.

15.4. MessageProperties Class

class oracledb.MessageProperties

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

This object is an extension to the DB API definition.

15.4.1. MessageProperties Attributes

property MessageProperties.attempts: int

This read-only attribute specifies the number of attempts that have been made to dequeue the message.

property MessageProperties.correlation: str

This read-write attribute specifies the correlation used when the message was enqueued.

property MessageProperties.delay: int

This read-write attribute specifies the number of seconds to delay an enqueued message. Any integer is acceptable but the constant MSG_NO_DELAY can also be used indicating that the message is available for immediate dequeuing.

property MessageProperties.deliverymode: int

This read-only attribute specifies the type of message that was dequeued. It will be one of the values MSG_PERSISTENT or MSG_BUFFERED.

property MessageProperties.enqtime: datetime

This read-only attribute specifies the time that the message was enqueued.

property MessageProperties.exceptionq: str

This read-write attribute specifies the name of the queue to which the message is moved if it cannot be processed successfully. Messages are moved if the number of unsuccessful dequeue attempts has exceeded the maximum number of retries or if the message has expired. All messages in the exception queue are in the MSG_EXPIRED state. The default value is the name of the exception queue associated with the queue table.

property MessageProperties.expiration: int

This read-write attribute specifies, in seconds, how long the message is available for dequeuing. This attribute is an offset from the delay attribute. Expiration processing requires the queue monitor to be running. Any integer is accepted but the constant MSG_NO_EXPIRATION can also be used indicating that the message never expires.

property MessageProperties.msgid: bytes

This read-only attribute specifies the id of the message in the last queue that enqueued or dequeued this message. If the message has never been dequeued or enqueued, the value will be None.

property MessageProperties.payload: bytes | DbObject

This read-write attribute specifies the payload that will be enqueued or the payload that was dequeued when using a queue. When enqueuing, the value is checked to ensure that it conforms to the type expected by that queue. For RAW queues, the value can be a bytes object or a string. If the value is a string it will be converted to bytes in the encoding UTF-8.

property MessageProperties.priority: int

This read-write attribute specifies the priority of the message. A smaller number indicates a higher priority. The priority can be any integer, including negative numbers. The default value is 0.

property MessageProperties.recipients: list[str]

This read-write attribute specifies a list of recipient names that can be associated with a message at the time a message is enqueued. This allows a limited set of recipients to dequeue each message. The recipient list associated with the message overrides the queue subscriber list, if there is one. The recipient names need not be in the subscriber list but can be, if desired.

To dequeue a message, the consumername attribute can be set to one of the recipient names. The original message recipient list is not available on dequeued messages. All recipients have to dequeue a message before it gets removed from the queue.

Subscribing to a queue is like subscribing to a magazine: each subscriber can dequeue all the messages placed into a specific queue, just as each magazine subscriber has access to all its articles. Being a recipient, however, is like getting a letter: each recipient is a designated target of a particular message.

property MessageProperties.state: int

This read-only attribute specifies the state of the message at the time of the dequeue. It will be one of the values MSG_WAITING, MSG_READY, MSG_PROCESSED, or MSG_EXPIRED.