11. API: Subscription Objects

This object is an extension to the DB API definition.

11.1. Subscription Class

class oracledb.Subscription: A Subscription object should be created using Connection.subscribe(). See Working with Continuous Query Notification (CQN) for more information.

11.1.1. Subscription Methods

Subscription.registerquery(statement: str, args: list | dict | None = None) → int: Registers the query for subsequent notification when tables referenced by the query are changed. This behaves similarly to Cursor.execute() but only queries are permitted and the args parameter, if specified, must be a sequence or dictionary. If the qos parameter included the flag oracledb.SUBSCR_QOS_QUERY when the subscription was created, then the ID for the registered query is returned; otherwise, None is returned.

11.1.2. Subscription Attributes

property Subscription.callback: Callable: This read-only attribute returns the callback that was registered when the subscription was created.

property Subscription.connection: Connection: This read-only attribute returns the connection that was used to register the subscription when it was created.

property Subscription.id: int: This read-only attribute returns the value of REGID found in the database view USER_CHANGE_NOTIFICATION_REGS or the value of REG_ID found in the database view USER_SUBSCR_REGISTRATIONS. For AQ subscriptions, this value is 0.

property Subscription.ip_address: str

This read-only attribute returns the IP address used for callback notifications from the database server. If not set during construction, this value is None.

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

property Subscription.name: str: This read-only attribute returns the name used to register the subscription when it was created.

property Subscription.namespace: int: This read-only attribute returns the namespace used to register the subscription when it was created.

property Subscription.operations: int: This read-only attribute returns the operations that will send notifications for each table or query that is registered using this subscription.

property Subscription.port: int: This read-only attribute returns the port used for callback notifications from the database server. If not set during construction, this value is 0.

property Subscription.protocol: int: This read-only attribute returns the protocol used to register the subscription when it was created.

property Subscription.qos: int: This read-only attribute returns the quality of service flags used to register the subscription when it was created.

property Subscription.timeout: int: This read-only attribute returns the timeout (in seconds) that was specified when the subscription was created. A value of 0 indicates that there is no timeout.

11.2. Message Class

class oracledb.Message(subscription: Subscription): A Message object is created when a notification is received. They are passed to the callback procedure specified when a subscription is created.

11.2.1. Message Attributes

property Message.consumer_name: str | None

This read-only attribute returns the name of the consumer which generated the notification. It will be populated if the subscription was created with the namespace oracledb.SUBSCR_NAMESPACE_AQ and the queue is a multiple consumer queue.

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

property Message.dbname: str | None: This read-only attribute returns the name of the database that generated the notification.

property Message.msgid: bytes | None: This read-only attribute returns the message id of the AQ message that generated the notification. It will only be populated if the subscription was created with the namespace oracledb.SUBSCR_NAMESPACE_AQ.

property Message.queries: list[MessageQuery]: This read-only attribute returns a list of message query objects that give information about query result sets changed for this notification. This attribute will be an empty list if the qos parameter did not include the flag SUBSCR_QOS_QUERY when the subscription was created.

property Message.queue_name: str | None

This read-only attribute returns the name of the queue which generated the notification. It will only be populated if the subscription was created with the namespace oracledb.SUBSCR_NAMESPACE_AQ.

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

property Message.registered: bool: This read-only attribute returns whether the subscription which generated this notification is still registered with the database. The subscription is automatically deregistered with the database when the subscription timeout value is reached or when the first notification is sent (when the quality of service flag oracledb.SUBSCR_QOS_DEREG_NFY is used).

property Message.subscription: Subscription: This read-only attribute returns the subscription object for which this notification was generated.

property Message.tables: list[MessageTable]: This read-only attribute returns a list of message table objects that give information about the tables changed for this notification. This attribute will be an empty list if the qos parameter included the flag SUBSCR_QOS_QUERY when the subscription was created.

property Message.txid: bytes | None: This read-only attribute returns the id of the transaction that generated the notification.

property Message.type: int

This read-only attribute returns the type of message that has been sent.

See the constants section on Event Types for additional information.

11.3. MessageTable Class

class oracledb.MessageTable: A MessageTable object is created when a notification is received for each table change. They are accessed in the tables attribute of message objects, and the tables attribute of message query objects.

property MessageTable.name: str | None: This read-only attribute returns the name of the table that was changed.

property MessageTable.operation: int: This read-only attribute returns the operation that took place on the table that was changed.

property MessageTable.rows: list[MessageRow]: This read-only attribute returns a list of message row objects that give information about the rows changed on the table. This value is only filled in if the qos parameter to the Connection.subscribe() method included the flag SUBSCR_QOS_ROWIDS.

11.4. MessageRow Class

class oracledb.MessageRow: A MessageRow object is created when a notification is received for each row changed in a table. They are found in the rows attribute of message table objects.

11.4.1. MessageRow Attributes

property MessageRow.operation: int: This read-only attribute returns the operation that took place on the row that was changed.

property MessageRow.rowid: str | None: This read-only attribute returns the rowid of the row that was changed.

11.5. MessageQuery Class

class oracledb.MessageQuery: A MessageQuery object is created when a notification is received for a query result set change. This object is found in the queries attribute of message objects.

property MessageQuery.id: int: This read-only attribute returns the query id of the query for which the result set changed. The value will match the value returned by Subscription.registerquery() when the related query was registered.

property MessageQuery.operation: int: This read-only attribute returns the operation that took place on the query result set that was changed. Valid values for this attribute are EVENT_DEREG and EVENT_QUERYCHANGE.

property MessageQuery.tables: list[MessageTable]: This read-only attribute returns a list of message table objects that give information about the table changes that caused the query result set to change for this notification.