Edit

Share via

CREATE EVENT NOTIFICATION (Transact-SQL)

  • Article

Applies to: SQL Server Azure SQL Managed Instance

Creates an object that sends information about a database or server event to a service broker service. Event notifications are created only by using Transact-SQL statements.

Transact-SQL syntax conventions

Syntax

CREATE EVENT NOTIFICATION event_notification_name   
ON { SERVER | DATABASE | QUEUE queue_name }   
[ WITH FAN_IN ]  
FOR { event_type | event_group } [ ,...n ]  
TO SERVICE 'broker_service' , { 'broker_instance_specifier' | 'current database' }  
[ ; ]

Arguments

event_notification_name
Is the name of the event notification. An event notification name must comply with the rules for identifiers and must be unique within the scope in which they are created: SERVER, DATABASE, or object_name.

SERVER
Applies the scope of the event notification to the current instance of SQL Server. If specified, the notification fires whenever the specified event in the FOR clause occurs anywhere in the instance of SQL Server.

Note

This option is not available in a contained database.

DATABASE
Applies the scope of the event notification to the current database. If specified, the notification fires whenever the specified event in the FOR clause occurs in the current database.

QUEUE
Applies the scope of the notification to a specific queue in the current database. QUEUE can be specified only if FOR QUEUE_ACTIVATION or FOR BROKER_QUEUE_DISABLED is also specified.

queue_name
Is the name of the queue to which the event notification applies. queue_name can be specified only if QUEUE is specified.

WITH FAN_IN
Instructs SQL Server to send only one message per event to any specified service for all event notifications that:

  • Are created on the same event.

  • Are created by the same principal (as identified by the same SID).

  • Specify the same service and broker_instance_specifier.

  • Specify WITH FAN_IN.

For example, three event notifications are created. All event notifications specify FOR ALTER_TABLE, WITH FAN_IN, the same TO SERVICE clause, and are created by the same SID. When an ALTER TABLE statement is run, the messages that are created by these three event notifications are merged into one. Therefore, the target service receives only one message of the event.

event_type
Is the name of an event type that causes the event notification to execute. event_type can be a Transact-SQL DDL event type, a SQL Trace event type, or a Service Broker event type. For a list of qualifying Transact-SQL DDL event types, see DDL Events. Service Broker event types are QUEUE_ACTIVATION and BROKER_QUEUE_DISABLED. For more information, see Event Notifications.

event_group
Is the name of a predefined group of Transact-SQL or SQL Trace event types. An event notification can fire after execution of any event that belongs to an event group. For a list of DDL event groups, the Transact-SQL events they cover, and the scope at which they can be defined, see DDL Event Groups.

event_group also acts as a macro, when the CREATE EVENT NOTIFICATION statement finishes, by adding the event types it covers to the sys.events catalog view.

' broker_service '
Specifies the target service that receives the event instance data. SQL Server opens one or more conversations to the target service for the event notification. This service must honor the same SQL Server Events message type and contract that is used to send the message.

The conversations remain open until the event notification is dropped. Certain errors could cause the conversations to close earlier. Ending some or all conversations explicitly might prevent the target service from receiving more messages.

{ 'broker_instance_specifier' | 'current database' }
Specifies a service broker instance against which broker_service is resolved. The value for a specific service broker can be acquired by querying the service_broker_guid column of the sys.databases catalog view. Use 'current database' to specify the service broker instance in the current database. 'current database' is a case-insensitive string literal.

Note

This option is not available in a contained database.

Remarks

Service Broker includes a message type and contract specifically for event notifications. Therefore, a Service Broker initiating service does not have to be created because one already exists that specifies the following contract name: https://schemas.microsoft.com/SQL/Notifications/PostEventNotification

The target service that receives event notifications must honor this preexisting contract.

Important

Service Broker dialog security should be configured for event notifications that send messages to a service broker on a remote server. Dialog security must be configured manually according to the full security model. For more information, see Configure Dialog Security for Event Notifications.

If an event transaction that activates a notification is rolled back, the sending of the event notification is also rolled back. Event notifications do not fire by an action defined in a trigger when the transaction is committed or rolled back inside the trigger. Because trace events are not bound by transactions, event notifications based on trace events are sent regardless of whether the transaction that activates them is rolled back.

If the conversation between the server and the target service is broken after an event notification fires, an error is reported and the event notification is dropped.

The event transaction that originally started the notification is not affected by the success or failure of the sending of the event notification.

Any failure to send an event notification is logged.

Permissions

To create an event notification that is scoped to the database (ON DATABASE), requires CREATE DATABASE DDL EVENT NOTIFICATION permission in the current database.

To create an event notification on a DDL statement that is scoped to the server (ON SERVER), requires CREATE DDL EVENT NOTIFICATION permission in the server.

To create an event notification on a trace event, requires CREATE TRACE EVENT NOTIFICATION permission in the server.

To create an event notification that is scoped to a queue, requires ALTER permission on the queue.

Examples

Note

In Examples A and B below, the GUID in the TO SERVICE 'NotifyService' clause ('8140a771-3c4b-4479-8ac0-81008ab17984') is specific to the computer on which the example was set up. For that instance, that was the GUID for the AdventureWorks2022 database.

To copy and run these examples, you need to replace this GUID with one from your computer and SQL Server instance. As explained in the Arguments section above, you can acquire the 'broker_instance_specifier' by querying the service_broker_guid column of the sys.databases catalog view.

A. Creating an event notification that is server scoped

The following example creates the required objects to set up a target service using Service Broker. The target service references the message type and contract of the initiating service specifically for event notifications. Then an event notification is created on that target service that sends a notification whenever an Object_Created trace event happens on the instance of SQL Server.

--Create a queue to receive messages.  
CREATE QUEUE NotifyQueue ;  
GO  

--Create a service on the queue that references  
--the event notifications contract.  
CREATE SERVICE NotifyService  
ON QUEUE NotifyQueue  
([https://schemas.microsoft.com/SQL/Notifications/PostEventNotification]);  
GO  

--Create a route on the service to define the address   
--to which Service Broker sends messages for the service.  
CREATE ROUTE NotifyRoute  
WITH SERVICE_NAME = 'NotifyService',  
ADDRESS = 'LOCAL';  
GO 

--Create the event notification.  
CREATE EVENT NOTIFICATION log_ddl1   
ON SERVER   
FOR Object_Created   
TO SERVICE 'NotifyService',  
    '8140a771-3c4b-4479-8ac0-81008ab17984' ;

B. Creating an event notification that is database scoped

The following example creates an event notification on the same target service as the previous example. The event notification fires after an ALTER_TABLE event occurs on the AdventureWorks2022 sample database.

CREATE EVENT NOTIFICATION Notify_ALTER_T1  
ON DATABASE  
FOR ALTER_TABLE  
TO SERVICE 'NotifyService',  
    '8140a771-3c4b-4479-8ac0-81008ab17984';

C. Getting information about an event notification that is server scoped

The following example queries the sys.server_event_notifications catalog view for metadata about event notification log_ddl1 that was created with server scope.

SELECT * FROM sys.server_event_notifications  
WHERE name = 'log_ddl1';

D. Getting information about an event notification that is database scoped

The following example queries the sys.event_notifications catalog view for metadata about event notification Notify_ALTER_T1 that was created with database scope.

SELECT * FROM sys.event_notifications  
WHERE name = 'Notify_ALTER_T1';

See Also

Event Notifications
DROP EVENT NOTIFICATION (Transact-SQL)
EVENTDATA (Transact-SQL)
sys.event_notifications (Transact-SQL)
sys.server_event_notifications (Transact-SQL)
sys.events (Transact-SQL)
sys.server_events (Transact-SQL)