O que é SQL Detail e seus exemplos - PolarDB: Central de Documentação do Alibaba Cloud

O SQL detail audita operações de DDL e bloqueio em bancos de dados e tabelas do PolarDB for MySQL. Ele captura o contexto de execução de cada instrução e remove automaticamente registros anteriores ao período de retenção configurado. Diferentemente do recurso de log de auditoria completo — que audita todas as instruções SQL com uma sobrecarga significativa — o SQL detail foca exclusivamente em eventos de alteração de esquema e bloqueio. Isso o torna ideal para equipes de O&M (operações e manutenção) que precisam de trilhas de auditoria leves e direcionadas.

Como funciona

Quando uma instrução de DDL ou bloqueio inicia a execução, o SQL detail grava um registro na tabela de sistema sys.hist_sqldetail. Após a conclusão da instrução, o PolarDB atualiza o registro com o estado final e as métricas de desempenho. Registros mais antigos que o período de retenção configurado são removidos automaticamente.

O que o SQL detail captura:

Operações de DDL: alterações de esquema, como criação de tabelas, adição de colunas e modificação de índices
Operações de bloqueio: instruções LOCK TABLE e LOCK DB

O que o SQL detail não captura:

Instruções DML (INSERT, UPDATE, DELETE, SELECT) são intencionalmente excluídas. O SQL detail foi projetado para auditoria de alterações de esquema com baixa sobrecarga, não para registro geral de consultas. Para auditar instruções DML, ative o recurso de log de auditoria completo.

Armazenamento

Cada registro de auditoria consome 1 KB de armazenamento. Por exemplo, 1.024 operações de DDL ou bloqueio por dia, com um período de retenção de 30 dias, consomem aproximadamente 30 MB.

Pré-requisitos

Antes de começar, confirme se seu cluster atende a um dos seguintes requisitos de versão:

PolarDB for MySQL 8.0.1, versão de revisão 8.0.1.1.31 ou posterior
PolarDB for MySQL 8.0.2, versão de revisão 8.0.2.2.12 ou posterior

Para verificar a versão de revisão do seu cluster, consulte Consultar a versão do mecanismo.

Ativar o SQL detail

Configure os seguintes parâmetros no console. Para obter instruções, consulte Especificar parâmetros de cluster e nó.

Parâmetro	Nível	Padrão	Valores válidos	Descrição
`loose_awr_sqldetail_enabled`	Global	OFF	ON, OFF	Ativa ou desativa o SQL detail
`loose_awr_sqldetail_switch`	Global	`ddl`: ON; `lock_db_table`: ON	`ddl`: ON/OFF; `lock_db_table`: ON/OFF	Controla quais tipos de operação são auditados. `ddl` abrange instruções DDL; `lock_db_table` abrange instruções LOCK TABLE e LOCK DB
`loose_awr_sqldetail_retention`	Global	2592000	0–18446744073709551615	Período de retenção para registros de auditoria, em segundos. Registros mais antigos que esse valor são removidos automaticamente

Tabela sys.hist_sqldetail

O PolarDB for MySQL cria automaticamente a tabela de sistema sys.hist_sqldetail durante a inicialização. Não é necessária criação manual.

CREATE TABLE `hist_sqldetail` (
  `Id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  `State` varchar(16) COLLATE utf8mb4_bin DEFAULT NULL,
  `Thread_id` bigint(20) unsigned DEFAULT NULL,
  `Host` varchar(60) COLLATE utf8mb4_bin NOT NULL DEFAULT '',
  `User` varchar(32) COLLATE utf8mb4_bin NOT NULL DEFAULT '',
  `Client_ip` varchar(60) COLLATE utf8mb4_bin DEFAULT NULL,
  `Db` varchar(64) COLLATE utf8mb4_bin DEFAULT NULL,
  `Sql_text` mediumtext COLLATE utf8mb4_bin NOT NULL,
  `Server_command` varchar(32) COLLATE utf8mb4_bin DEFAULT NULL,
  `Sql_command` varchar(64) COLLATE utf8mb4_bin DEFAULT NULL,
  `Start_time` timestamp(6) NULL DEFAULT NULL,
  `Exec_time` bigint(20) DEFAULT NULL,
  `Wait_time` bigint(20) DEFAULT NULL,
  `Error_code` int(11) DEFAULT NULL,
  `Rows_sent` bigint(20) DEFAULT NULL,
  `Rows_examined` bigint(20) DEFAULT NULL,
  `Rows_affected` bigint(20) DEFAULT NULL,
  `Logical_read` bigint(20) DEFAULT NULL,
  `Phy_sync_read` bigint(20) DEFAULT NULL,
  `Phy_async_read` bigint(20) DEFAULT NULL,
  `Process_info` text COLLATE utf8mb4_bin,
  `Extra` text COLLATE utf8mb4_bin,
  `Create_time` timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
  `Update_time` timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
  PRIMARY KEY (`Id`),
  KEY `i_start_time` (`Start_time`),
  KEY `i_update_time` (`Update_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

Referência de colunas

Coluna	Descrição
`Id`	ID de registro com incremento automático
`State`	Estado da operação no momento da gravação do registro
`Thread_id`	ID da thread que executou a instrução
`Host`	Host associado ao usuário em execução
`User`	Nome de usuário usado para executar a instrução
`Client_ip`	Endereço IP do cliente
`Db`	Banco de dados onde a instrução foi executada
`Sql_text`	Texto completo da instrução SQL
`Server_command`	Tipo de comando do servidor (por exemplo, `Query`)
`Sql_command`	Tipo de instrução (por exemplo, `create_table`, `alter_table`, `lock_tables`)
`Start_time`	Timestamp de início da execução (precisão de microssegundos)
`Exec_time`	Duração da execução, em microssegundos. Use este valor para identificar operações de DDL excepcionalmente lentas
`Wait_time`	Tempo de espera da instrução antes do início da execução, em microssegundos. Valores altos podem indicar contenção de bloqueio
`Error_code`	Código de erro. Um valor diferente de zero indica falha na instrução; use este campo para rastrear alterações de esquema malsucedidas
`Rows_sent`	Número de linhas retornadas
`Rows_examined`	Número de linhas verificadas
`Rows_affected`	Número de linhas afetadas
`Logical_read`	Número de leituras lógicas
`Phy_sync_read`	Número de leituras físicas síncronas
`Phy_async_read`	Número de leituras físicas assíncronas
`Process_info`	Informações estendidas de processamento
`Extra`	Informações estendidas adicionais
`Create_time`	Timestamp de criação do registro
`Update_time`	Timestamp da última atualização do registro

Exemplo

Este exemplo demonstra como o SQL detail captura operações de DDL e bloqueio, ignorando instruções DML.

Etapa 1: Defina loose_awr_sqldetail_enabled como ON no console e execute as seguintes instruções:

create table t(c1 int);
-- Query OK, 0 rows affected (0.02 sec)

create table t(c1 int);
-- ERROR 1050 (42S01): Table 't' already exists

alter table t add column c2 int;
-- Query OK, 0 rows affected (0.02 sec)
-- Records: 0  Duplicates: 0  Warnings: 0

lock tables t read;
-- Query OK, 0 rows affected (0.00 sec)

unlock tables;
-- Query OK, 0 rows affected (0.00 sec)

insert into t values(1, 2);
-- Query OK, 1 row affected (0.00 sec)

Etapa 2: Consulte os registros de auditoria:

select * from sys.hist_sqldetail\G

Saída esperada:

*************************** 1. row ***************************
            Id: 1
         State: FINISH
     Thread_id: 18
          Host: localhost
          User: root
     Client_ip: 127.0.0.1
            Db: test
      Sql_text: create table t(c1 int)
Server_command: Query
   Sql_command: create_table
    Start_time: 2023-01-13 16:18:21.840435
     Exec_time: 17390
     Wait_time: 318
    Error_code: 0
     Rows_sent: 0
 Rows_examined: 0
 Rows_affected: 0
  Logical_read: 420
 Phy_sync_read: 0
Phy_async_read: 0
  Process_info: NULL
         Extra: NULL
   Create_time: 2023-01-13 16:18:22.391407
   Update_time: 2023-01-13 16:18:22.391407
*************************** 2. row ***************************
            Id: 2
         State: FINISH
     Thread_id: 18
          Host: localhost
          User: root
     Client_ip: 127.0.0.1
            Db: test
      Sql_text: create table t(c1 int)
Server_command: Query
   Sql_command: create_table
    Start_time: 2023-01-13 16:18:22.416321
     Exec_time: 822
     Wait_time: 229
    Error_code: 1050
     Rows_sent: 0
 Rows_examined: 0
 Rows_affected: 0
  Logical_read: 55
 Phy_sync_read: 0
Phy_async_read: 0
  Process_info: NULL
         Extra: NULL
   Create_time: 2023-01-13 16:18:23.393071
   Update_time: 2023-01-13 16:18:23.393071
*************************** 3. row ***************************
            Id: 3
         State: FINISH
     Thread_id: 18
          Host: localhost
          User: root
     Client_ip: 127.0.0.1
            Db: test
      Sql_text: alter table t add column c2 int
Server_command: Query
   Sql_command: alter_table
    Start_time: 2023-01-13 16:18:34.123947
     Exec_time: 16420
     Wait_time: 245
    Error_code: 0
     Rows_sent: 0
 Rows_examined: 0
 Rows_affected: 0
  Logical_read: 778
 Phy_sync_read: 0
Phy_async_read: 0
  Process_info: NULL
         Extra: NULL
   Create_time: 2023-01-13 16:18:34.394067
   Update_time: 2023-01-13 16:18:34.394067
*************************** 4. row ***************************
            Id: 4
         State: FINISH
     Thread_id: 18
          Host: localhost
          User: root
     Client_ip: 127.0.0.1
            Db: test
      Sql_text: lock tables t read
Server_command: Query
   Sql_command: lock_tables
    Start_time: 2023-01-13 16:19:49.891559
     Exec_time: 145
     Wait_time: 129
    Error_code: 0
     Rows_sent: 0
 Rows_examined: 0
 Rows_affected: 0
  Logical_read: 0
 Phy_sync_read: 0
Phy_async_read: 0
  Process_info: NULL
         Extra: NULL
   Create_time: 2023-01-13 16:19:50.399585
   Update_time: 2023-01-13 16:19:50.399585
*************************** 5. row ***************************
            Id: 5
         State: FINISH
     Thread_id: 18
          Host: localhost
          User: root
     Client_ip: 127.0.0.1
            Db: test
      Sql_text: unlock tables
Server_command: Query
   Sql_command: unlock_tables
    Start_time: 2023-01-13 16:19:56.924648
     Exec_time: 98
     Wait_time: 0
    Error_code: 0
     Rows_sent: 0
 Rows_examined: 0
 Rows_affected: 0
  Logical_read: 0
 Phy_sync_read: 0
Phy_async_read: 0
  Process_info: NULL
         Extra: NULL
   Create_time: 2023-01-13 16:19:57.400294
   Update_time: 2023-01-13 16:19:57.400294

A saída contém cinco registros — um para cada instrução de DDL e bloqueio. A instrução insert into t values(1, 2) não foi registrada porque o SQL detail não captura operações DML.

A linha 2 exibe Error_code: 1050 referente à tentativa duplicada de CREATE TABLE. O SQL detail registra tanto instruções bem-sucedidas quanto malsucedidas, fornecendo à equipe de O&M um histórico completo das tentativas de alteração de esquema, incluindo aquelas que falharam.