CREATE QUEUE (Transact-SQL)

Se aplica a: SQL Server Azure SQL Managed Instance

Crea una nueva cola en una base de datos. Las colas almacenan mensajes. Cuando llega un mensaje para un servicio, Service Broker lo coloca en la cola asociada a ese servicio.

Convenciones de sintaxis de Transact-SQL

Sintaxis

CREATE QUEUE <object>
   [ WITH
     [ STATUS = { ON | OFF } [ , ] ]
     [ RETENTION = { ON | OFF } [ , ] ]
     [ ACTIVATION (
         [ STATUS = { ON | OFF } , ]
           PROCEDURE_NAME = <procedure> ,
           MAX_QUEUE_READERS = max_readers ,
           EXECUTE AS { SELF | 'user_name' | OWNER }
            ) [ , ] ]
     [ POISON_MESSAGE_HANDLING (
         [ STATUS = { ON | OFF } ] ) ]
    ]
     [ ON { filegroup | [ DEFAULT ] } ]
[ ; ]

<object> ::=
{ database_name.schema_name.queue_name | schema_name.queue_name | queue_name }

<procedure> ::=
{ database_name.schema_name.stored_procedure_name | schema_name.stored_procedure_name | stored_procedure_name }

Argumentos

database_name (object)

Es el nombre de la base de datos en que se crea la nueva cola. database_name debe especificar el nombre de una base de datos existente. Si no se proporciona database_name, la cola se crea en la base de datos actual.

schema_name (object)

Nombre del esquema al que pertenece la nueva cola. El valor predeterminado del esquema es el esquema predeterminado del usuario que ejecuta la instrucción. Si la instrucción CREATE QUEUE es ejecutada por un miembro del rol fijo de servidor sysadmin o por un miembro de los roles fijos de base de datos db_dbowner o db_ddladmin en la base de datos especificada por database_name, schema_name puede especificar un esquema distinto del asociado con el inicio de sesión de la conexión actual. De no ser así, schema_name debe ser el esquema predeterminado del usuario que ejecuta la instrucción.

queue_name

Nombre de la cola que se va a crear. Este nombre debe cumplir las directrices de los identificadores de SQL Server.

STATUS (cola)

Especifica si la cola está disponible (ON) o no (OFF). Cuando la cola no está disponible, no pueden agregarse mensajes a ella ni tampoco quitarse. Puede crear la cola en un estado de no disponibilidad para impedir que lleguen mensajes a ésta hasta que la cola esté disponible mediante una instrucción ALTER QUEUE. Si se pasa por alto esta cláusula, el valor predeterminado es ON y la cola estará disponible.

RETENTION

Especifica la configuración de retención para la cola. Si RETENTION = ON, todos los mensajes enviados o recibidos relativos a conversaciones que utilizan esta cola se retendrán en ella hasta que finalicen las conversaciones. Esto permite retener mensajes con fines de auditoría o para realizar transacciones de compensación si se produce un error. Si no se especifica esta cláusula, el valor predeterminado de retención es OFF.

Nota

El rendimiento puede disminuir si se establece RETENTION en ON. Utilice este valor solo si lo requiere la aplicación.

ACTIVATION

Especifica información sobre qué procedimiento almacenado es necesario iniciar para procesar los mensajes de esta cola.

STATUS (activación)

Especifica si Service Broker inicia el procedimiento almacenado. Si STATUS = ON, la cola inicia el procedimiento almacenado especificado con PROCEDURE_NAME cuando el número de procedimientos que se ejecutan actualmente es menor que MAX_QUEUE_READERS y cuando los mensajes llegan a la cola antes de que los procedimientos almacenados reciban mensajes. Si STATUS = OFF, la cola no inicia el procedimiento almacenado. Si no se especifica esta cláusula, el valor predeterminado es ON.

PROCEDURE_NAME = <procedimiento>

Especifica el nombre del procedimiento almacenado que es necesario iniciar para procesar mensajes en esta cola. Este valor debe ser un identificador de SQL Server.

database_name(procedimiento) Nombre de la base de datos que contiene el procedimiento almacenado.

schema_name(procedimiento) Nombre del esquema que contiene el procedimiento almacenado.

procedure_name Nombre del procedimiento almacenado.

MAX_QUEUE_READERS =max_readers

Especifica el número máximo de instancias del procedimiento almacenado de activación que la cola inicia al mismo tiempo. El valor de max_readers debe ser un número comprendido entre 0 y 32767.

EXECUTE AS

Especifica la cuenta de usuario de base de datos de SQL Server en la que se ejecuta el procedimiento almacenado de activación. SQL Server debe poder comprobar los permisos de este usuario en el momento en que la cola inicia el procedimiento almacenado. En el caso de un usuario de dominio, el servidor debe estar conectado al dominio cuando se inicie el procedimiento o se producirá un error en la activación. En usuarios de SQL Server, el servidor siempre puede comprobar los permisos.

SELF Especifica que el procedimiento almacenado se ejecuta como el usuario actual. Es la entidad de seguridad de base de datos que ejecuta esta instrucción CREATE QUEUE.

"user_name" Nombre del usuario con el que se ejecuta el procedimiento almacenado. El parámetro user_name debe ser un usuario de SQL Server válido especificado como identificador de SQL Server. El usuario actual debe tener el permiso IMPERSONATE para el valor de user_name especificado.

OWNER Especifica que el procedimiento almacenado se ejecuta como el propietario de la cola.

POISON_MESSAGE_HANDLING

Especifica si está habilitado para la cola el control de mensajes dudosos. El valor predeterminado es ON.

Una cola que tenga configurado en OFF el control de mensajes dudosos no se deshabilitará después de cinco reversiones de transacción consecutivas. Esto permite que el sistema de control de mensajes dudosos sea definido por la aplicación.

ON filegroup | [DEFAULT]

Especifica el grupo de archivos de SQL Server en que se va a crear esta cola. Puede usar el parámetro filegroup para identificar un grupo de archivos o emplear el identificador DEFAULT para usar el grupo de archivos predeterminado de la base de datos de Service Broker. En el contexto de esta cláusula, DEFAULT no es una palabra clave y debe delimitarse como un identificador. Si no se especifica ningún grupo de archivos, la cola utiliza el grupo de archivos predeterminado de la base de datos.

Observaciones

Una cola puede ser el destino de una instrucción SELECT. No obstante, el contenido de una cola solo puede modificarse mediante instrucciones que funcionan en conversaciones de Service Broker, como SEND, RECEIVE y END CONVERSATION. Una cola no puede ser el destino de una instrucción INSERT, UPDATE, DELETE o TRUNCATE.

Una cola no puede ser un objeto temporal. Por lo tanto, los nombres de cola que empiezan por # no son válidos.

Si crea una cola en estado inactivo, puede obtener la infraestructura de un servicio antes de permitir que los mensajes se reciban en la cola.

Service Broker no detiene los procedimientos almacenados de activación si no hay ningún mensaje en la cola. Un procedimiento almacenado de activación debe finalizar cuando no haya ningún mensaje disponible en la cola durante un breve período de tiempo.

Los permisos para el procedimiento almacenado de activación se comprueban cuando Service Broker inicia el procedimiento almacenado, no cuando se crea la cola. La instrucción CREATE QUEUE no comprueba que el usuario especificado en la cláusula EXECUTE AS tenga permiso para ejecutar el procedimiento almacenado especificado en la cláusula PROCEDURE NAME.

Cuando una cola no está disponible, Service Broker retiene los mensajes de los servicios que usan la cola en la cola de transmisión de la base de datos. En la vista de catálogo sys.transmission_queue se proporciona una vista de la cola de transmisión.

Una cola es un objeto propiedad de un esquema. Las colas aparecen en la vista de catálogo sys.objects.

La siguiente tabla contiene las columnas de una cola.

Nombre de la columna	Tipo de datos	Descripción
status	tinyint	Estado del mensaje. La instrucción RECEIVE devuelve todos los mensajes que tienen 1 como estado. Si la retención de los mensajes está activada, el estado se establece en 0. Si está desactivada, el mensaje se elimina de la cola. Los mensajes de la cola pueden contener uno de los valores siguientes: 0=Mensaje recibido retenido 1=Listo para recibir 2=Todavía no se ha completado 3=Mensaje enviado retenido
priority	tinyint	Nivel de prioridad asignado a este mensaje.
queuing_order	bigint	Número de orden del mensaje en la cola.
conversation_group_id	uniqueidentifier	Identificador para el grupo de conversación al que pertenece este mensaje.
conversation_handle	uniqueidentifier	Identificador para la conversación de la que forma parte este mensaje.
message_sequence_number	bigint	Número de secuencia del mensaje en la conversación.
service_name	nvarchar(128)	Nombre del servicio al que se destina la conversación.
service_id	int	Identificador de objeto de SQL Server del servicio al que se destina la conversación.
service_contract_name	nvarchar(128)	Nombre del contrato por el que se rige la conversación.
service_contract_id	int	Identificador de objeto de SQL Server del contrato por el que se rige la conversación.
message_type_name	nvarchar(128)	Nombre del tipo de mensaje que describe el mensaje.
message_type_id	int	Identificador de objeto de SQL Server del tipo de mensaje que describe el mensaje.
validation	nchar(2)	Validación utilizada para el mensaje. E=Vacío N=None X=XML
message_body	varbinary(max)	Contenido del mensaje.
message_enqueue_time	datetime	Hora a la que se puso en cola el mensaje.

Permisos

Tienen permiso para crear una cola los miembros de los roles fijos de base de datos db_ddladmin o db_owner o el rol fijo de servidor sysadmin.

De forma predeterminada, se concede permiso REFERENCES para una cola al propietario de la cola, a los miembros de los roles fijos de base de datos db_ddladmin o db_owner o a los miembros del rol fijo de servidor sysadmin.

De forma predeterminada, se concede el permiso RECEIVE para una cola al propietario de la cola, a los miembros del rol fijo de base de datos db_owner o a los miembros del rol fijo de servidor sysadmin.

Ejemplos

A. Creación de una cola sin parámetros

En el siguiente ejemplo se crea una cola que está disponible para recibir mensajes. No se especifica ningún procedimiento almacenado de activación para la cola.

CREATE QUEUE ExpenseQueue;

B. Creación de una cola no disponible

En el siguiente ejemplo se crea una cola que no está disponible para recibir mensajes. No se especifica ningún procedimiento almacenado de activación para la cola.

CREATE QUEUE ExpenseQueue WITH STATUS=OFF;

C. Creación de una cola y especificación de información de activación interna

En el siguiente ejemplo se crea una cola que está disponible para recibir mensajes. La cola inicia el procedimiento almacenado expense_procedure cuando un mensaje entra en la cola. El procedimiento almacenado se ejecuta como el usuario ExpenseUser. La cola inicia un máximo de 5 instancias del procedimiento almacenado.

CREATE QUEUE ExpenseQueue
    WITH STATUS=ON,
    ACTIVATION (
        PROCEDURE_NAME = expense_procedure
        , MAX_QUEUE_READERS = 5
        , EXECUTE AS 'ExpenseUser' );

D. Creación de una cola en un grupo de archivos específico

En el siguiente ejemplo se crea una cola en el grupo de archivos ExpenseWorkFileGroup.

CREATE QUEUE ExpenseQueue
    ON ExpenseWorkFileGroup;

E. Creación de una cola con varios parámetros

En el siguiente ejemplo se crea una cola en el grupo de archivos DEFAULT. La cola no está disponible. Los mensajes se retienen en la cola hasta que finaliza la conversación a la que pertenecen. Cuando la cola pasa a estar disponible mediante ALTER QUEUE, la cola inicia el procedimiento almacenado AdventureWorks2022.dbo.expense_procedure para procesar los mensajes. El procedimiento almacenado se ejecuta como el usuario que ejecutó la instrucción CREATE QUEUE. La cola inicia un máximo de 10 instancias del procedimiento almacenado.

CREATE QUEUE ExpenseQueue
    WITH STATUS = OFF
      , RETENTION = ON
      , ACTIVATION (
          PROCEDURE_NAME = AdventureWorks2022.dbo.expense_procedure
          , MAX_QUEUE_READERS = 10
          , EXECUTE AS SELF )
    ON [DEFAULT];

Contenido relacionado

• ALTER QUEUE (Transact-SQL)
• CREATE SERVICE (Transact-SQL)
• DROP QUEUE (Transact-SQL)
• RECEIVE (Transact-SQL)
• EVENTDATA (Transact-SQL)