Skip to main content
The capabilities on this page are in preview: their APIs are not stable, and an extension that declares one requires vsql_allow_preview_extensions = ON to install. See Preview Capabilities for how to enable the preview tier and register a capability. The statement event capability (vsql::preview::statement_event) runs an extension-provided handler after each query finishes executing. The server invokes the handler synchronously on the query’s own thread and passes execution metadata — the query text, timing, row counts, connection identity, and optimizer quality indicators. Use it for slow-query logging, auditing, or metrics collection. The capability name VEF_PREVIEW_STATEMENT_EVENT_NAME is "vsql::preview::statement_event".

Declaring the Capability

Declare a StatementEventCapability, instantiated on the firing phase and your handler function, at file scope and pass it to .with():
The first template argument is the firing phase, a vef_statement_event_phase_t value. VEF_STATEMENT_EVENT_POSTEXECUTE fires after a query finishes executing, on success or failure, and is the only phase implemented in this version. The other vef_statement_event_phase_t values are reserved; declaring a handler for one of them causes the server to reject INSTALL EXTENSION.

Handler Arguments

StatementEventArgs is a read-only view of the completed query; at the POSTEXECUTE phase every field is populated. Selected accessors: Because query() returns the server’s rewritten form when one exists, credential-bearing statements arrive with the secret obfuscated rather than in cleartext, matching how the general and slow logs already redact them: SET PASSWORD, CREATE/ALTER USER ... IDENTIFIED BY, CHANGE REPLICATION SOURCE ... SOURCE_PASSWORD, and CREATE SERVER ... OPTIONS(PASSWORD ...). Statements with no rewrite rule are delivered verbatim. String accessors such as query(), sqlstate(), and error_message() point into storage that is valid only for the duration of the handler call — copy the bytes if you need them after the handler returns. StatementEventResult::error_msg(fmt, ...) writes a printf-formatted message. At the POSTEXECUTE phase the message is advisory: the server logs it but does not propagate it to the client.

Complete Example

A condensed form of the vsql_slow_query_log test extension. It logs each query whose execution time exceeds a threshold, combining the statement event capability with system variables for runtime configuration:

Enabling from SQL

With the preview tier enabled (see Enabling the Preview Tier), build the extension, copy its .veb file into veb_dir, install it, and configure it through its system variables:
Each query slower than the threshold is appended to the configured log file: