> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos de Instrução

> A capability vsql::preview::statement_event executa um handler da extensão após o término de cada consulta, com o texto da consulta, o tempo, a contagem de linhas e a identidade da conexão.

As capabilities desta página estão em Preview: suas APIs não são estáveis, e uma extensão que declara uma delas requer `vsql_allow_preview_extensions = ON` para instalar. Consulte [Capabilities Preview](https://villagesql.com/docs/pt-BR/extensions/build/preview-capabilities) para saber como habilitar o nível Preview e registrar uma capability.

A capability statement event (`vsql::preview::statement_event`) executa um handler
fornecido pela extensão após cada consulta terminar de executar. O servidor invoca
o handler sincronamente na própria thread da consulta e passa metadados de
execução — o texto da consulta, tempo, contagens de linhas, identidade da conexão
e indicadores de qualidade do otimizador. Use-o para registro de consultas lentas,
auditoria ou coleta de métricas.

O nome da capability `VEF_PREVIEW_STATEMENT_EVENT_NAME` é
`"vsql::preview::statement_event"`.

## Declarando a Capability

Declare um `StatementEventCapability`, instanciado sobre a fase de disparo e a sua
função handler, no escopo do arquivo e passe-o para `.with()`:

```cpp theme={null}
#include <villagesql/preview/statement_event.h>
#include <villagesql/vsql.h>

namespace se = vsql::preview_statement_event;

static void on_statement(const se::StatementEventArgs &args,
                         se::StatementEventResult &result) {
  // inspect args; optionally write an advisory message via result
}

static se::StatementEventCapability<VEF_STATEMENT_EVENT_POSTEXECUTE,
                                    &on_statement>
    g_statement_event;

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .with(g_statement_event))
```

O primeiro argumento de template é a fase de disparo, um valor
`vef_statement_event_phase_t`. `VEF_STATEMENT_EVENT_POSTEXECUTE` dispara após uma
consulta terminar de executar, em caso de sucesso ou falha, e é a única fase
implementada nesta versão. Os outros valores de `vef_statement_event_phase_t` são
reservados; declarar um handler para um deles faz o servidor rejeitar o
`INSTALL EXTENSION`.

## Argumentos do Handler

`StatementEventArgs` é um view somente leitura da consulta concluída; na fase
POSTEXECUTE todos os campos estão populados. Acessadores selecionados:

| Acessador | Significado |
| - | - |
| `query()` | Texto da consulta, como um `string_view`. Quando o servidor tem uma forma reescrita da instrução, este é aquela forma — o mesmo texto ofuscado que os logs geral e lento registram. |
| `query_time_secs()` | Tempo real de execução, em segundos. |
| `lock_time_secs()` | Tempo gasto esperando por bloqueios, em segundos. |
| `rows_sent()`, `rows_examined()`, `rows_affected()` | Contadores de linhas. |
| `user()`, `client_ip()`, `connection_id()` | Identidade da conexão. |
| `schema()` | Esquema padrão, ou `NULL` se nenhum estiver selecionado. |
| `status()` | `0` em caso de sucesso, caso contrário o código de erro do MySQL. |
| `warning_count()` | Número de notas e avisos gerados enquanto a instrução era executada; quando a instrução falhou, o número gerado antes do erro. |
| `digest_text()` | Forma normalizada da consulta, para agrupar consultas semelhantes. |
| `no_index_used()` | `true` quando a consulta foi executada sem um índice utilizável. |
| `digest_hash()` | Digest da instrução em 64 caracteres hexadecimais minúsculos — o valor que o `performance_schema` expõe como `DIGEST`. Uma chave compacta para agrupar instruções idênticas; é `NULL` sempre que `digest_text()` for. |
| `read_first()`, `read_last()`, `read_key()`, `read_next()`, `read_prev()`, `read_rnd()`, `read_rnd_next()` | Contadores de acesso a linhas do handler por instrução (os campos `Read_*` do log de consultas lentas). Eles quantificam o método de acesso que `no_index_used()` apenas sinaliza — um `read_rnd_next()` alto, por exemplo, indica uma varredura completa de tabela. |
| `client_pid()`, `client_name()`, `program_name()` | Atributos de conexão fornecidos pelo cliente, enviados uma vez no handshake (`_pid`, `_client_name`, `program_name`): o id do processo do cliente no sistema operacional, a biblioteca do connector/driver (por exemplo, `libmysql`, `mysql-connector-j`) e o nome da aplicação (por exemplo, `mysql`, `mysqldump`). Cada um é `NULL` quando o cliente não enviou aquele atributo. |

Como `query()` retorna a forma reescrita do servidor quando existe uma, as
instruções que carregam credenciais chegam com o segredo ofuscado em vez de em
texto claro, correspondendo à forma como os logs geral e lento já os
ofuscam: `SET PASSWORD`, `CREATE`/`ALTER USER ... IDENTIFIED BY`,
`CHANGE REPLICATION SOURCE ... SOURCE_PASSWORD` e
`CREATE SERVER ... OPTIONS(PASSWORD ...)`. As instruções sem regra de reescrita
são entregues literalmente.

Os acessadores de string como `query()`, `sqlstate()` e `error_message()` apontam
para armazenamento que é válido apenas durante a chamada do handler — copie os
bytes se você precisar deles depois que o handler retornar.

`StatementEventResult::error_msg(fmt, ...)` escreve uma mensagem formatada com
printf. Na fase POSTEXECUTE a mensagem é informativa: o servidor a registra, mas
não a propaga para o cliente.

## Exemplo Completo

Uma forma condensada da extensão de teste
[`vsql_slow_query_log`](https://github.com/villagesql/villagesql-server/tree/main/villagesql/test-extensions/vsql-slow-query-log).
Ela registra cada consulta cujo tempo de
execução excede um limiar, combinando a capability statement event com
[variáveis de sistema](https://villagesql.com/docs/pt-BR/extensions/build/preview-server-variables.md#system-variables) para configuração em tempo de execução:

```cpp theme={null}
#include <cerrno>
#include <cstdio>
#include <cstring>
#include <ctime>
#include <mutex>

#include <villagesql/preview/statement_event.h>
#include <villagesql/preview/sys_var.h>
#include <villagesql/vsql.h>

using namespace vsql;
namespace sv = vsql::preview_sys_var;
namespace se = vsql::preview_statement_event;

static bool g_enabled;
static long long g_threshold_ms;
static char *g_log_filename;
static std::mutex g_log_mutex;

static void slow_query_hook(const se::StatementEventArgs &args,
                            se::StatementEventResult &result) {
  if (!g_enabled) return;
  if (args.query_time_secs() * 1000.0 < static_cast<double>(g_threshold_ms))
    return;

  time_t now = static_cast<time_t>(args.query_start_utime() / 1000000);
  char ts[32];
  struct tm tm_utc;
  gmtime_r(&now, &tm_utc);
  strftime(ts, sizeof(ts), "%Y-%m-%dT%H:%M:%SZ", &tm_utc);

  std::lock_guard<std::mutex> lock(g_log_mutex);
  FILE *f = fopen(g_log_filename, "a");
  if (f == nullptr) {
    result.error_msg("failed to open '%s': %s", g_log_filename,
                     strerror(errno));
    return;
  }

  fprintf(f, "# Time: %s\n", ts);
  fprintf(f, "# User@Host: %s @ %s  Id: %lu\n", args.user() ? args.user() : "",
          args.client_ip() ? args.client_ip() : "", args.connection_id());
  fprintf(f,
          "# Schema: %s  Query_time: %.6f  Lock_time: %.6f"
          "  Rows_sent: %llu  Rows_examined: %llu\n",
          args.schema() ? args.schema() : "", args.query_time_secs(),
          args.lock_time_secs(), (unsigned long long)args.rows_sent(),
          (unsigned long long)args.rows_examined());
  fprintf(f, "SET timestamp=%llu;\n", (unsigned long long)now);
  auto q = args.query();
  fprintf(f, "%.*s;\n", (int)q.size(), q.data());
  fclose(f);
}

static auto SYS_VARS = sv::make_capability({
    sv::make_bool("enabled", "Enable the slow query log", &g_enabled, false),
    sv::make_int("threshold_ms", "Minimum execution time to log, in ms",
                 &g_threshold_ms, 1000, 0, 3600000),
    sv::make_str("log_file", "Path to the slow query log file",
                 &g_log_filename, "/tmp/vsql_slow_query.log")});

static se::StatementEventCapability<VEF_STATEMENT_EVENT_POSTEXECUTE,
                                    &slow_query_hook>
    STATEMENT_EVENT;

VEF_GENERATE_ENTRY_POINTS(
    make_extension().with(SYS_VARS).with(STATEMENT_EVENT))
```

### Habilitando a partir do SQL

Com o nível Preview habilitado (consulte
[Habilitando o Nível Preview](https://villagesql.com/docs/pt-BR/extensions/build/preview-capabilities#enabling-the-preview-tier)), compile a extensão,
copie o seu arquivo `.veb` para o `veb_dir`,
instale-a e configure-a através de suas variáveis de sistema:

```sql theme={null}
INSTALL EXTENSION vsql_slow_query_log;
SET GLOBAL vsql_slow_query_log.enabled = ON;
SET GLOBAL vsql_slow_query_log.threshold_ms = 500;
```

Cada consulta mais lenta que o limiar é anexada ao arquivo de log configurado:

```
# Time: 2026-06-22T22:53:44Z
# User@Host: root @   Id: 27
# Schema:   Query_time: 0.605084  Lock_time: 0.000000  Rows_sent: 1  Rows_examined: 1
SET timestamp=1782168824;
SELECT SLEEP(0.6);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.