Events

What it is

Events makes the otherwise-opaque inside of a DuckDB process observable. Instead of instrumenting application code or scraping logs after the fact, you get a structured JSON line for every query, transaction, and connection the process handles. That stream is the raw material for audit trails (every statement with timestamps and error status), error alerting (page on has_error), per-session cost attribution, and transaction forensics — but the extension itself is deliberately small: it emits events, and what you do with them lives entirely in the handler you point it at.

How it works

The extension hooks DuckDB's internal event surface, launches the program at events_destination as a long-lived child process, and writes one JSON object per event to its stdin. There is no SQL function to call — configuration is entirely PRAGMA-driven, so wiring up event capture is a few SET statements.

• • Configure with PRAGMAs: events_destination is a fully-qualified executable path (invoked directly, not via a shell — python3 handler.py won't work; point at a shebang script or the interpreter binary). events_types picks which events to capture, events_session_name tags every event, and events_async switches delivery mode.
• • Seven event types: connection_opened, connection_closed, query_begin, query_end, transaction_begin, transaction_commit, and transaction_rollback. The default capture is ['query_begin', 'query_end'] — the smallest set that still gives query-level audit visibility, two events per statement.
• • JSON lines on stdin: Every event is one line of JSON. A common envelope (event, timestamp in ISO 8601, database_path, session_name, connection_id, process_id) carries per-type fields on top — query_id (pairs query_begin/query_end), transaction_id, has_error, error_message, error_type, and attached_databases[]. The handler can be a shell script, a Python service, a Go binary — anything that reads stdin a line at a time.
• • Sync or fire-and-forget delivery: Synchronous (the default) writes the event and waits for the handler to consume it before the originating query returns — reliable, but adds latency to every query. SET events_async = TRUE is fire-and-forget: no blocking, but events are dropped silently if the handler stalls, dies, or can't keep up. There's no in-between mode; pick one per session.

Production caveats

What to know before pointing this at a production database.

• • Process-scoped, not durable: Configuration lives in the running DuckDB process — restart and it's gone. Set the PRAGMAs at session start or wrap them in a startup script. The destination can be durable (file, S3, Kafka, syslog); the configuration is not. Same caveat as the sibling cronjob extension — both are operate-your-DuckDB-process tools, observable only while the process is up.
• • One handler per session: Only one destination at a time. For fan-out — file plus Kafka plus alerting — point events_destination at a small dispatcher that reads stdin and forks the stream itself (tee, a Python script, vector, etc.). There's also no per-query filter at the extension layer; every event of an enabled type is emitted, so filter downstream in the handler.
• • Sync mode blocks queries: In the default synchronous mode the handler is on the critical path — a 50 ms-per-event handler adds 50 ms to every query, and a hung handler holds up everything. Add timeouts and a fast path, or accept the trade-off and switch to events_async = TRUE.
• • Handler runs with DuckDB's privileges: The destination program is launched by the DuckDB process and inherits its privileges and environment. Treat the events_destination path as security-sensitive — point it at a fully-qualified file that's write-protected from the database user.

Configure where events go and what to capture

SET events_destination = '/usr/local/bin/event-handler.py';
SET events_types = ['query_begin', 'query_end'];

Optional: don't block queries on the handler

SET events_async = TRUE;

Optional: tag every event with a session name

SET events_session_name = 'analytics-replica';