# info > DBI::Profile

---
type: CommandReference
command: DBI::Profile
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `DBI_PROFILE=2 prog.pl` — profile by statement text
- `DBI_PROFILE=6 prog.pl` — profile by statement and method name
- `$dbh->{Profile} = 2` — enable profiling on a handle
- `$dbh->{Profile} = "!Statement:!MethodName"` — custom path with colon-separated values
- `$dbh->{Profile} = { Path => [ '!Statement', '!MethodName' ] }` — equivalent to string form
- `print $h->{Profile}->format` — output formatted profile data
- `$h->{Profile}->{Data} = undef` — reset profile data
- `dbi_profile($h, $statement, $method, $t1, $t2)` — add a custom sample

## Name

[DBI::Profile](https://metacpan.org/pod/DBI::Profile) — Performance profiling and benchmarking for the DBI

## Synopsis

The easiest way to enable DBI profiling is to set the `DBI_PROFILE` environment variable to 2 and then run your code:

shell
DBI_PROFILE=2 prog.pl
This profiles the program and outputs a textual summary grouped by query on exit. Profiling can also be enabled by setting the `Profile` attribute of any DBI handle:

perl
$dbh->{Profile} = 2;
Then the summary is printed when the handle is destroyed.

Many other values are possible — see "Options".

## Options

### Profile Attribute Values

The `Profile` attribute accepts:

- **Integer** — bitmask to select common path values:
  - `1` — `DBI`
  - `2` — `!Statement`
  - `4` — `!MethodName`
  - `8` — `!MethodClass`
  - `16` — `!Caller2`
  - Common shorthands: `2` (statement only), `6` (statement + method), `-6` (method then statement).
- **String** — format: `path/module/args`. The path part is colon-separated special constants; module defaults to `DBI::Profile`; args are passed to `new()`.
- **Hash reference** — keys: `Path` (array ref), `Data` (hash ref to collect profile data), and other options.
- **Blessed object** — any object that provides a `DESTROY` method to dump data.

### Path Elements

The `Path` array controls how profile data is grouped. Each element can be:

- **Special constants**:
  - `!Statement` — current statement text
  - `!MethodName` — method name
  - `!MethodClass` — fully qualified method name (package + method)
  - `!Caller` — `filename:line` of caller
  - `!Caller2` — two levels of caller info
  - `!File` — filename only
  - `!File2` — two filenames
  - `!Time` — unix timestamp
  - `!Time~N` — timestamp rounded to nearest N seconds
- **Code reference** — receives `($handle, $method_name)`; `$_` contains the statement. Returns a list of values for the path. Can veto a sample by including `\undef`.
- **Subroutine specifier** — string starting with `&` (e.g., `&norm_std_n3`) to load from `DBI::ProfileSubs`.
- **Attribute specifier** — string in braces (e.g., `"{Username}"`) to use the value of a handle attribute.
- **Reference to a scalar** — use the current value of that scalar.
- **Other values** — used literally.

### Profile Object Methods

- `format()` — returns formatted summary string.
- `as_node_path_list($node, $path)` — returns list of `[leaf, path...]` for each leaf.
- `as_text(\%options)` — returns formatted text; options: `node`, `path`, `separator` (default ` > `), `format` (sprintf with explicit indices), `sortsub` (code ref to sort nodes).

## Examples

### Enable profiling via environment variable

shell
DBI_PROFILE=2 perl -e 'use DBI; my $dbh = DBI->connect(...); ...'
### Enable profiling on a handle

perl
$dbh->{Profile} = 6;
# or equivalently:
$dbh->{Profile} = "!Statement:!MethodName";
$dbh->{Profile} = { Path => [ '!Statement', '!MethodName' ] };
### Use a custom path with code reference

perl
$dbh->{Profile} = {
    Path => [
        sub {
            my ($h, $method) = @_;
            local $_ = $_;
            return $h->{Statement} =~ /^SELECT/i ? 'SELECT' : $_;
        },
        '!MethodName'
    ]
};
### Reset and re-use profile data

perl
$h->{Profile}->{Data} = undef;
### Add custom samples

perl
use DBI::Profile qw(dbi_profile dbi_time);

my $t1 = dbi_time();
# ... code to profile ...
my $t2 = dbi_time();
dbi_profile($h, $statement, $method, $t1, $t2);
### Format profile data

perl
print $h->{Profile}->format;
## See Also

- [DBI::ProfileDumper](https://metacpan.org/pod/DBI::ProfileDumper) — more elaborate profiling for larger programs
- [DBI::ProfileDumper::Apache](https://metacpan.org/pod/DBI::ProfileDumper::Apache) — Apache/mod_perl integration
- [DBI::ProfileSubs](https://metacpan.org/pod/DBI::ProfileSubs) — pre-defined path subroutines (e.g., `&norm_std_n3`)
- [dbiprof](https://metacpan.org/pod/dbiprof) — command-line tool to analyse profile dumps
- [DBI](https://metacpan.org/pod/DBI) — the underlying database interface

## Exit Codes

None documented.