ALTER QUEUE (Transact-SQL)

Se aplica a:SQL ServerAzure SQL Managed Instance

Cambia las propiedades de una cola.

Convenciones de sintaxis de Transact-SQL

Sintaxis

ALTER QUEUE <object>   
   queue_settings  
   | queue_action  
[ ; ]  
  
<object> : :=  
{ database_name.schema_name.queue_name | schema_name.queue_name | queue_name }
  
<queue_settings> : :=  
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 } ]  
       |  DROP }  
          ) [ , ]]  
         [ POISON_MESSAGE_HANDLING (  
          STATUS = { ON | OFF } )  
         ]   
  
<queue_action> : :=  
   REBUILD [ WITH <query_rebuild_options> ]  
   | REORGANIZE [ WITH (LOB_COMPACTION = { ON | OFF } ) ]  
   | MOVE TO { file_group | "default" }  
  
<procedure> : :=  
{ database_name.schema_name.stored_procedure_name | schema_name.stored_procedure_name | stored_procedure_name }
  
<queue_rebuild_options> : :=  
{  
   ( MAXDOP = max_degree_of_parallelism )  
}  

Argumentos

database_name (object)
Es el nombre de la base de datos que contiene la cola que se va a cambiar. Si no se proporciona database_name, el valor predeterminado es la base de datos actual.

schema_name (object)
Nombre del esquema al que pertenece la nueva cola. Si no se proporciona schema_name, se usa el esquema predeterminado del usuario actual.

queue_name
Es el nombre de la cola que se va a cambiar.

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.

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 hasta que las conversaciones finalicen. Esto permite retener mensajes con fines de auditoría o para realizar transacciones de compensación si se produce un error.

ACTIVATION
Especifica información acerca del procedimiento almacenado que se activa para procesar mensajes que llegan a esta cola.

STATUS (activación)
Especifica si una cola activa o no 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 activa el procedimiento almacenado.

REBUILD [ WITH <queue_rebuild_options> ]
Válido para : SQL Server 2016 (13.x) y versiones posteriores.

Vuelve a compilar todos los índices de la tabla interna de colas. Use esta función cuando experimente problemas de fragmentación debido a una carga elevada. MAXDOP es la única opción de recompilación de cola admitida. REBUILD siempre es una operación sin conexión.

REORGANIZE [ WITH ( LOB_COMPACTION = { ON | OFF } ) ]
Válido para : SQL Server 2016 (13.x) y versiones posteriores.

Vuelve a organizar todos los índices de la tabla interna de colas.
A diferencia de REORGANIZE en tablas de usuario, REORGANIZE en una cola siempre se realiza como una operación sin conexión porque los bloqueos de nivel de página se deshabilitan explícitamente en las colas.

MOVE TO { file_group | "default" }
Válido para : SQL Server 2016 (13.x) y versiones posteriores.

Mueve la tabla interna de colas (con sus índices) a un grupo de archivos especificado por el usuario. El nuevo grupo de archivos no debe ser de solo lectura.

PROCEDURE_NAME = <procedimiento>
Especifica el nombre del procedimiento almacenado que se va a activar cuando la cola contiene mensajes para procesar. 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 tiene la propiedad del procedimiento almacenado.

stored_procedure_name
Es el nombre del procedimiento almacenado.

MAX_QUEUE_READERS =max_reader
Especifica el número máximo de instancias del procedimiento almacenado de activación que la cola inicia simultáneamente. El valor de max_readers debe ser un número comprendido entre 0 y 32 767.

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. Para un usuario de dominio de Windows, SQL Server debe estar conectado al dominio y debe poder validar los permisos del usuario especificado cuando se active el procedimiento o la activación genere un error. 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 ALTER QUEUE.

'user_name'
Es el nombre de usuario con el que se ejecuta el procedimiento almacenado. user_name debe ser un usuario válido de SQL Server especificado como un 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.

DROP
Elimina toda la información de activación asociada a la cola.

POISON_MESSAGE_HANDLING
Especifica si se ha habilitado controlar 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.

Observaciones

Cuando una cola que tiene especificado un procedimiento almacenado de activación contiene mensajes, al cambiar el estado de activación de OFF a ON, se activa inmediatamente el procedimiento almacenado de activación. Cambiar el estado de activación de ON a OFF impide que el agente active instancias del procedimiento almacenado, pero las instancias que están en ejecución no se detienen.

Modificar una cola para agregar un procedimiento almacenado de activación no afecta al estado de activación de la cola. Modificar el procedimiento almacenado de activación de la cola no afecta a las instancias del procedimiento almacenado de activación que se estén ejecutando en el momento actual.

Service Broker comprueba el número máximo de lectores de cola como parte del proceso de activación. Por tanto, si se modifica una cola para aumentar el número máximo de lectores de cola, Service Broker iniciará inmediatamente más instancias del procedimiento almacenado de activación. Modificar una cola para reducir el número máximo de lectores de cola no afecta a las instancias del procedimiento almacenado de activación que se estén ejecutando en el momento actual. No obstante, Service Broker no inicia ninguna nueva instancia del procedimiento almacenado hasta que el número de instancias del procedimiento almacenado de activación sea inferior al número máximo configurado.

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. La vista de catálogo sys.transmission_queue proporciona una vista de la cola de transmisión.

Si las instrucciones RECEIVE o GET CONVERSATION GROUP especifican una cola que no está disponible, generarán un error de Transact-SQL.

Permisos

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

Ejemplos

A. Hacer que una cola no esté disponible

En el ejemplo siguiente se hace que la cola de ExpenseQueue no esté disponible para recibir mensajes.

ALTER QUEUE ExpenseQueue WITH STATUS = OFF ;  

B. Cambiar el procedimiento almacenado de activación

En el siguiente ejemplo se muestra cómo cambiar el procedimiento almacenado iniciado por la cola. El procedimiento almacenado se ejecuta como el usuario que ejecutó la instrucción ALTER QUEUE.

ALTER QUEUE ExpenseQueue  
    WITH ACTIVATION (  
        PROCEDURE_NAME = new_stored_proc,  
        EXECUTE AS SELF) ;  

C. Cambiar el número de lectores de cola

En el ejemplo siguiente se establece en 7 el número máximo de instancias de procedimiento almacenado que inicia Service Broker para esta cola.

ALTER QUEUE ExpenseQueue WITH ACTIVATION (MAX_QUEUE_READERS = 7) ;  

D. Cambiar el procedimiento almacenado de activación y la cuenta EXECUTE AS

En el ejemplo siguiente se cambia el procedimiento almacenado iniciado por Service Broker. El procedimiento almacenado se ejecuta como el usuario SecurityAccount.

ALTER QUEUE ExpenseQueue  
    WITH ACTIVATION (  
        PROCEDURE_NAME = AdventureWorks2022.dbo.new_stored_proc ,  
        EXECUTE AS 'SecurityAccount') ;  

E. Configurar la cola para retener mensajes

En el siguiente ejemplo se muestra cómo configurar la cola para retener mensajes. La cola retiene todos los mensajes enviados a o desde los servicios que utilizan la cola hasta que la conversación que contiene el mensaje finaliza.

ALTER QUEUE ExpenseQueue WITH RETENTION = ON ;  

F. Quitar la activación de una cola

En el siguiente ejemplo se muestra cómo quitar toda la información de activación de la cola.

ALTER QUEUE ExpenseQueue WITH ACTIVATION (DROP) ;  

G. Recompilar índices de cola

Válido para : SQL Server 2016 (13.x) y versiones posteriores.

En el ejemplo siguiente se recompilan índices de cola.

ALTER QUEUE ExpenseQueue REBUILD WITH (MAXDOP = 2)   

H. Reorganizar índices de cola

Válido para : SQL Server 2016 (13.x) y versiones posteriores.

En el ejemplo siguiente se reorganizan índices de cola.

ALTER QUEUE ExpenseQueue REORGANIZE   

I: Mover una tabla interna de colas a otro grupo de archivos

Válido para : SQL Server 2016 (13.x) y versiones posteriores.

ALTER QUEUE ExpenseQueue MOVE TO [NewFilegroup]   

Consulte también

CREATE QUEUE (Transact-SQL)
DROP QUEUE (Transact-SQL)
EVENTDATA (Transact-SQL)
sys.dm_db_index_physical_stats (Transact-SQL)