ApsaraDB RDS:SQL throttling (rds_ccl)

Cenários

Chame esta função apenas na instância primária para criar uma regra de limitação de SQL.

Sintaxe

• Sintaxe 1: Limite uma instrução SQL específica.

  SELECT rds_add_ccl_rule(
  	query_string varchar,
  	node_tag int,
  	max_concurrency int,
  	max_waiting int,
  	is_enabled boolean,
  	comment varchar,		-- Optional
  	search_path varchar		-- Optional
  );

• Sintaxe 2: Limite com base em um query_id específico.

  SELECT rds_add_ccl_rule_with_query_id(
    query_id		bigint,
    node_tag		int,
    max_concurrency	int,
    max_waiting		int,
    is_enabled		boolean,
    query_string		varchar,	-- Optional
    comment		varchar,	-- Optional
    search_path           varchar		-- Optional (Supported in version 1.2 and later)
  );

Parâmetros

-- Use $$ to wrap the SQL statement.
    $$SELECT * FROM my_table;$$

    -- If the SQL statement already contains $$, use $ccl$ to wrap the SQL statement.
    $ccl$SELECT * FROM my_table WHERE my_column = $$hello$$;$ccl$

Observações de uso

• Na Sintaxe 1, caso não configure os parâmetros comment e search_path, defina-os como uma string vazia (''). Se defini-los como NULL, a função não realiza nenhuma operação e retorna imediatamente.

• Na Sintaxe 2:

  • Se não configurar os parâmetros query_string e comment, defina-os como uma string vazia (''). Se defini-los como NULL, a função não realiza nenhuma operação e retorna imediatamente.

  • Caso configure tanto query_id quanto query_string, o kernel AliPG aplica a limitação de SQL com base em query_id.

• Esta função retorna um ccl_id, que é o identificador exclusivo da regra de limitação no banco de dados atual.

Exemplos de SQL

Suponha que exista uma tabela chamada ccl_tbl no banco de dados ccl_test da instância primária. Crie uma regra de limitação de SQL que atenda aos seguintes requisitos:

1. Limite todas as instruções SELECT * FROM ccl_tbl. Suponha que o query_id delas seja 1.

2. Permita a execução simultânea de no máximo três instruções SQL desse tipo.

3. Permita que no máximo duas instruções SQL desse tipo fiquem em espera.

4. A regra deve entrar em vigor imediatamente após a criação.

• Sintaxe 1:

  SELECT rds_add_ccl_rule(
    $$SELECT * FROM ccl_tbl;$$,		-- The SQL statement to be throttled, wrapped in $$.
    1,					-- Throttles the primary instance only.
    3,					-- Allows a maximum of 3 such SQL statements to execute concurrently.
    2,					-- Allows a maximum of 2 such SQL statements to wait.
    true,					-- The rule takes effect immediately.
    'limit constant select',		-- The rule description.
    ''					-- Uses the default search_path.
  );

• Sintaxe 2:

  SELECT rds_add_ccl_rule_with_query_id(
    1,					-- The query_id of the SQL statement to be throttled.
    1,					-- Throttles the primary instance only.
    3,					-- Allows a maximum of 3 such SQL statements to execute concurrently.
    2,					-- Allows a maximum of 2 such SQL statements to wait.
    true,					-- The rule takes effect immediately.
    '',					-- The text of the SQL statement. This is not specified in this example.
    'limit constant select',		-- The rule description.
    'public'                              -- The search_path.
  );

Cenários

Execute este comando em uma instância primária ou somente leitura para consultar as regras de limitação de SQL criadas.

Sintaxe

• Para visualizar todas as regras de limitação de SQL em todos os bancos de dados da instância atual:

  SELECT * FROM rds_enabled_ccl_rule;

  Nota

  • No resultado da consulta deste comando, os valores de query_string e comment são truncados para 200 caracteres devido a limitações de exibição. Para visualizar as informações completas, execute o comando SELECT * FROM rds_show_current_db_ccl_rule();.

  • A versão 1.2 e posteriores do rds_ccl suportam o retorno de search_path.

• Para consultar todas as regras de limitação de SQL no banco de dados atual:

  SELECT * FROM rds_show_current_db_ccl_rule();

Cenários

Chame esta função apenas na instância primária. Ela se aplica aos seguintes cenários:

• Se definiu o parâmetro is_enabled como false ao criar uma regra de limitação de SQL, use esta função para ativar a regra.

• Também é possível usar esta função para ativar uma regra desativada anteriormente.

Sintaxe

SELECT rds_enable_ccl_rule(ccl_id int);

Parâmetros

Observações de uso

Nenhuma.

Exemplo de SQL

SELECT rds_enable_ccl_rule(1);

Cenários

Chame esta função em uma instância primária ou somente leitura para carregar uma regra de limitação de SQL. Apenas regras carregadas podem ser usadas para limitação de SQL.

Esta função se aplica aos seguintes cenários:

• Instância primária:

  • Ao criar uma regra de limitação de SQL, se is_enabled estiver definido como true, a regra é carregada automaticamente na instância primária. Nesse caso, não é necessário chamar esta função.

  • Ao criar uma regra de limitação de SQL, se is_enabled estiver definido como false, a regra é carregada automaticamente na instância primária quando você chama a função rds_enable_ccl_rule para ativá-la. Nesse caso, não é necessário chamar esta função.

  • Se a instância primária for reiniciada, chame esta função manualmente para carregar a regra.

• Instância somente leitura:

  Se uma regra precisar entrar em vigor em uma instância somente leitura, crie a regra na instância primária e defina o parâmetro node_tag como 2 ou 3. Em seguida, chame esta função na instância somente leitura para carregar a regra manualmente.

Sintaxe

SELECT rds_load_ccl_rule(ccl_id int);

Parâmetros

Observações de uso

• Carregue uma regra em uma instância somente leitura apenas depois que a regra de limitação de SQL for criada na instância primária chamando a função rds_add_ccl_rule com o parâmetro node_tag definido como 2 ou 3.

• Regras desativadas não podem ser carregadas. Para carregar uma regra desativada em uma instância somente leitura, primeiro ative a regra na instância primária. Para mais informações, consulte Enable an SQL throttling rule.

Exemplo de SQL

SELECT rds_load_ccl_rule(1);

Cenários

Chame esta função apenas na instância primária para alterar a concorrência máxima e a contagem máxima de espera em uma regra de limitação de SQL.

Sintaxe

SELECT rds_update_ccl_rule(
	ccl_id int,
	new_max_concurrency int,
	new_max_waiting int
);

Parâmetros

Observações de uso

• As atualizações em uma regra de limitação de SQL entram em vigor imediatamente.

• É possível alterar apenas a concorrência máxima e a contagem máxima de espera em uma regra de limitação de SQL.

Exemplo de SQL

SELECT rds_update_ccl_rule(
 2,     -- ccl_id
 4,     -- The new maximum concurrency is 4.
 5      -- The new maximum waiting count is 5.
);

Cenários

Chame esta função apenas na instância primária para desativar uma regra de limitação de SQL. Após a desativação, a regra deixa de limitar instruções SQL.

Sintaxe

• Para desativar uma regra de limitação de SQL específica:

  SELECT rds_disable_ccl_rule(ccl_id int);

• Para desativar todas as regras de limitação de SQL no banco de dados atual:

  SELECT rds_disable_all();

Parâmetros

Observações de uso

• Regras desativadas não podem ser carregadas. Para carregar uma regra desativada em uma instância somente leitura, primeiro ative a regra na instância primária. Para mais informações, consulte Enable an SQL throttling rule.

• Ao desativar uma regra de limitação de SQL, ela é descarregada automaticamente da instância primária e deixa de limitar instruções SQL.

Exemplo de SQL

SELECT rds_disable_ccl_rule(1);

Cenários

Chame esta função em uma instância primária ou somente leitura para descarregar uma regra de limitação de SQL. Uma regra descarregada deixa de limitar instruções SQL.

Esta função se aplica aos seguintes cenários:

• Instância primária:

  • Se chamar a função rds_disable_ccl_rule ou rds_disable_all na instância primária para desativar uma regra, ela será descarregada automaticamente da instância primária. Nesse caso, não é necessário chamar esta função.

  • Se chamar a função rds_del_ccl_rule na instância primária para excluir uma regra, ela será descarregada automaticamente da instância primária. Nesse caso, não é necessário chamar esta função.

  • Também é possível chamar esta função para descarregar manualmente a regra da instância primária.

• Instância somente leitura:

  Se não quiser que uma regra limite instruções SQL em uma instância somente leitura, chame esta função para descarregá-la manualmente da instância somente leitura.

Sintaxe

SELECT rds_unload_ccl_rule(ccl_id int, db_name varchar default '');

Parâmetros

Observações de uso

Após o descarregamento, a regra deixa de limitar instruções SQL. Para usar a regra novamente, recarregue-a. Para mais informações, consulte Load an SQL throttling rule.

Exemplo de SQL

SELECT rds_unload_ccl_rule(1,'');

Cenários

Chame esta função apenas na instância primária para excluir uma regra de limitação de SQL. Quando uma regra é excluída, ela é descarregada automaticamente da instância primária.

Sintaxe

SELECT rds_del_ccl_rule(ccl_id int);

Parâmetros

Observações de uso

Nenhuma.

Exemplo de SQL

SELECT rds_del_ccl_rule(1);

Resultado de exemplo:

   rds_del_ccl_rule   
----------------------
 -7851264404688445170
(1 row)

• Um query_id é um identificador especial para instruções SQL no PostgreSQL. Instruções SQL semelhantes compartilham o mesmo query_id.

  Exemplo:

  -- The following two SQL statements have the same query_id.
  SELECT * FROM tbl WHERE a = 1;
  SELECT * FROM tbl WHERE a = 2;

• Um query_id contém informações sobre os objetos em uma instrução SQL, baseadas no identificador de objeto (oid). Tabelas com o mesmo nome são consideradas objetos diferentes se estiverem em bancos de dados ou schemas diferentes. Portanto, instruções SQL idênticas têm valores de query_id diferentes se referenciarem objetos diferentes.

• Se o objeto acessado em uma instrução SQL for uma tabela global ou uma função global, o query_id será o mesmo independentemente do banco de dados em que a instrução for executada.

  • Exemplo 1: pg_database é uma tabela global. O query_id é o mesmo quando esta tabela é consultada a partir de bancos de dados diferentes.

    • Execute a seguinte instrução no banco de dados ccl_test:

      SELECT rds_get_query_id($$SELECT * FROM pg_database;$$);

      Resultado de exemplo:

         rds_get_query_id   
      ----------------------
       -8733244708994363681
      (1 row)

    • Execute a seguinte instrução no banco de dados ccl_test2:

      SELECT rds_get_query_id($$SELECT * FROM pg_database;$$);

      Resultado de exemplo:

         rds_get_query_id   
      ----------------------
       -8733244708994363681
      (1 row)

  • Exemplo 2: pg_sleep é uma função global. O query_id é o mesmo quando esta função é chamada a partir de bancos de dados diferentes.

    • Execute a seguinte instrução no banco de dados ccl_test:

      SELECT rds_get_query_id($$SELECT pg_sleep(1);$$);

      Resultado de exemplo:

        rds_get_query_id  
      --------------------
       440101247839410938
      (1 row)

    • Execute a seguinte instrução no banco de dados ccl_test2:

      SELECT rds_get_query_id($$SELECT pg_sleep(1);$$);

      Resultado de exemplo:

        rds_get_query_id  
      --------------------
       440101247839410938
      (1 row)

• Ao chamar uma função, o query_id muda se o tipo de parâmetro mudar ou se uma cláusula FROM for adicionada ou removida.

  Por exemplo, ao chamar a função pg_sleep, o query_id retornado difere com base no contexto.

  • Sem uma cláusula FROM:

    SELECT rds_get_query_id($$SELECT pg_sleep(1);$$);

    Resultado de exemplo:

      rds_get_query_id  
    --------------------
     440101247839410938
    (1 row)

  • Com uma cláusula FROM:

    SELECT rds_get_query_id($$SELECT * FROM pg_sleep(1);$$);

    Resultado de exemplo:

       rds_get_query_id   
    ----------------------
     -3404018605099167039
    (1 row)

  • Se o tipo de parâmetro mudar:

    select rds_get_query_id($$SELECT * FROM pg_sleep(1.0);$$);

    Resultado de exemplo:

      rds_get_query_id   
    ---------------------
     3073869725037049158
    (1 row)