---
title: Diesel reference
description: Reference documentation for Allure Diesel | AllureInstrumentation | install_default | Step naming | Transaction nesting
---

# Allure Diesel reference

## `AllureInstrumentation`

- `AllureInstrumentation::new()` — instrumentation with the default `CaptureOptions`
- `AllureInstrumentation::with_options(options: CaptureOptions)` — see
  [Configuration](/docs/diesel-configuration/)

Implements Diesel's `Instrumentation` trait. Attach it to a connection with
`conn.set_instrumentation(instrumentation)`.

## `install_default`

- `allure_diesel::install_default() -> diesel::QueryResult<()>`

Registers `AllureInstrumentation::new()` (with default `CaptureOptions`) as the default
instrumentation for every Diesel connection established afterward in the current process, via
Diesel's `set_default_instrumentation`. Call it once, before any connections you want captured are
established. There's no built-in way to install default instrumentation with non-default
`CaptureOptions` — use `set_instrumentation` per connection instead if you need that.

## Step naming

A step's name is the query's rendered SQL — the exact text passed to `sql_query(...)`, or Diesel's
own `Debug`-rendered output for typed query-builder calls (uppercase keywords, e.g. `INSERT INTO
...`), which for parameterized queries typically includes a trailing, Diesel-internal `-- binds:
[...]` comment showing the bound values.

When the rendered SQL is longer than `max_sql_preview` characters (1024 by default — see
[Configuration](/docs/diesel-configuration/#control-the-sql-attachment)), the step name is cut to
that many characters with a trailing `…`. This truncation only affects the step **name**; the
`query.sql` attachment (when enabled) always holds the complete, untruncated text.

## Transactions

With transaction capture enabled (the default), a `BEGIN`/`SAVEPOINT` boundary opens a
`transaction (depth N)` step (`N` is Diesel's transaction nesting depth), and every statement run
while it's open — including the closing `COMMIT`/`ROLLBACK` boundary itself — nests inside it as a
sibling step, in execution order.

The `transaction` step's own status and any failure message come from the **boundary
statements**, not from your transaction closure's return value:

- If the opening `BEGIN`/`SAVEPOINT` fails, the `transaction` step closes immediately as `failed`
  with that error, and no closing boundary follows (there's nothing to commit or roll back). Later
  queries are recorded at the top level again, not nested inside the failed transaction step.
- If `BEGIN` succeeds and the transaction later **commits successfully**, the `transaction` step
  is `passed`.
- If `COMMIT` itself fails (for example, a deferred foreign-key constraint that's only checked at
  commit time), the `transaction` step is `failed`, carrying the `COMMIT` error — even though
  every statement inside the transaction succeeded individually.
- If your closure returns `Err` and Diesel issues a `ROLLBACK`, the `transaction` step is
  `passed` as long as the `ROLLBACK` statement itself succeeds — a rollback is a normal,
  successful database operation from the instrumentation's point of view. The `Err` your closure
  returned is never visible to `AllureInstrumentation`; only whether the boundary SQL succeeded is.
  If you want a report to visibly flag "this transaction rolled back," record that yourself (for
  example with a label or a log step) inside the closure.

After a transaction step closes — however it closes — later queries are recorded as top-level
siblings again; the internal step stack always rebalances, even when a boundary statement failed.

## `CaptureOptions`

See [Configuration](/docs/diesel-configuration/) for the full list of builder methods
(`without_transactions`, `with_connection_events`, `without_sql_attachment`,
`with_max_sql_preview`) and their defaults.