trace property

The trace callback currently registered on this database, if any.

The callback is invoked synchronously for statement trace events, as reported by sqlite3_trace_v2. It runs while the traced statement is running - in particular, it is invoked before the call running the statement (e.g. execute or select) returns. Events are always reported in the order in which they occur; use SqliteTraceWithStatement.statementAddress to correlate events belonging to the same statement.

Only the event categories enabled through SqliteTraceCallback.statement, SqliteTraceCallback.row and SqliteTraceCallback.profile are reported. As this property mirrors the underlying C interface, a database only supports a single trace callback: assigning a new callback (or enabling different categories) replaces the previous registration. Applications observing the same database from multiple places can fan events out in their callback.

As the callback runs as part of running statements, it must not modify the database. Exceptions thrown by the callback are ignored (they cannot be propagated through sqlite's native frames); the value it returns is passed back to sqlite, which currently ignores it. Note that durations reported by SqliteTraceProfile events include the overhead of invoking the callback itself.

While a callback is registered, statements report events by invoking it synchronously - one invocation per enabled event. In particular, enabling SqliteTraceCallback.row adds overhead proportional to the number of rows returned by statements, so unless row-level events are needed, prefer a smaller set of categories such as SqliteTraceCallback.statement and SqliteTraceCallback.profile.

Assigning a callback throws an UnsupportedError if the sqlite3 library in use doesn't support tracing, e.g. because an outdated sqlite3.wasm bundle is being used. All native sqlite3 libraries shipped with releases of this package support tracing.

Implementation

Implementation

Database class