# perldoc > DBI::Profile

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

## Quick Reference

- `DBI_PROFILE=2 prog.pl` — Enable profiling with default path (statement text) and output on exit
- `$dbh->{Profile} = 2;` — Enable profiling for a database handle (same as DBI_PROFILE=2)
- `$dbh->{Profile} = "6/DBI::Profile";` — Enable profiling grouped by statement then method
- `$dbh->{Profile} = { Path => ['!Statement', '!MethodName'] };` — Explicit path: statement then method
- `print $h->{Profile}->format;` — Format and print current profile data
- `$h->{Profile}->{Data} = undef;` — Discard collected data and restart
- `DBI_PROFILE=1 prog.pl` — Profile with empty path (single total time)

## Name

DBI::Profile — Performance profiling and benchmarking for the DBI

## Synopsis

Enable profiling via environment variable:

shell
DBI_PROFILE=2 prog.pl
Enable profiling in code:

perl
$dbh->{Profile} = 2;                    # same as DBI_PROFILE=2
$dbh->{Profile} = "!Statement:!MethodName/DBI::Profile";
$dbh->{Profile} = { Path => [ '!Statement', '!MethodName' ] };
Output formatted report:

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

### Profile Attribute Values

The `Profile` attribute can be set to a number, string, hash reference, or `DBI::Profile` object.

- `0` or `"0/DBI::Profile"` — Empty path (single merged node)
- `2` or `"!Statement/DBI::Profile"` — Group by statement text (default when DBI_PROFILE=2)
- `6` — Same as `!Statement:!MethodName` (statement then method)
- Negative number — Reverses the path order (e.g., `-6` groups by method then statement)
- String format: `"path/module/args"` — Parsed as `path` (colon-separated), `module` (loaded), `args` (colon-separated passed to `new`)

### Path Elements

The `Path` array controls how profile data is organized in the tree. Each element can be:

- `!Statement` — Use the current statement text (from `Statement` attribute)
- `!MethodName` — Use the name of the DBI method called
- `!MethodClass` — Use the fully qualified method name (e.g., `DBD::_::db::selectrow_arrayref`)
- `!Caller` — Use `filename:line` of the calling code
- `!Caller2` — Use `filename:line` of caller and its caller (skipping DBI/DBD packages)
- `!File` — Same as `!Caller` but only filename
- `!File2` — Same as `!Caller2` but only filenames
- `!Time` — Use current `time()` value
- `!Time~N` — Use `time()` truncated to N-second buckets (e.g., `!Time~60` for minute buckets)
- Code reference — Subroutine returning list of path values; can veto sample by including `\undef`
- `&subname` — Name of subroutine in `DBI::ProfileSubs` (e.g., `&norm_std_n3`)
- `"{AttributeName}"` — Use current value of the named database handle attribute
- Reference to scalar — Use the referenced scalar's current value
- Any other value — Used literally

### Profile Data Node Format

Each leaf node is an array reference:

perl
[ count, total_duration, first_duration, shortest_duration, longest_duration, time_of_first_sample, time_of_last_sample ]
## Examples

### Basic Profiling with Environment Variable

shell
DBI_PROFILE=2 perl my_script.pl
Output on exit:

DBI::Profile: 0.001015s 42.7% (5 calls) my_script.pl @ 2025-01-01 12:00:00
'' =>
    0.000024s / 2 = 0.000012s avg (first 0.000015s, min 0.000009s, max 0.000015s)
'SELECT mode,size,name FROM table' =>
    0.000991s / 3 = 0.000330s avg (first 0.000678s, min 0.000009s, max 0.000678s)
### Enabling Profiling in Code

perl
use DBI;
my $dbh = DBI->connect("dbi:mysql:test", "user", "pass");
$dbh->{Profile} = 2;   # or { Path => ['!Statement', '!MethodName'] }
# ... do queries ...
$dbh->disconnect;      # profile summary printed to STDERR on destruction
### Custom Path with Code Reference

perl
$dbh->{Profile} = {
    Path => [
        sub {
            my ($h, $method) = @_;
            my $stmt = $_;
            # Simplify statement to remove literal values
            $stmt =~ s/\b\d+\b/?/g;
            $stmt =~ s/'(?:[^']|'')*'/'?'/g;
            return ($stmt, $method);
        }
    ]
};
### Adding Extra Samples

perl
use DBI qw(dbi_profile dbi_time);
my $t1 = dbi_time();
# ... code to profile ...
my $t2 = dbi_time();
dbi_profile($h, $statement, $method, $t1, $t2);
### Merging Profile Data

perl
use DBI qw(dbi_profile_merge_nodes);
my $time_in_dbi = dbi_profile_merge_nodes(my $total=[], $Profile->{Data});
$Profile->{Data} = {};   # reset profile data
## See Also

- [DBI::ProfileDumper](http://localhost/phpMan.php/perldoc/DBI%3A%3AProfileDumper/markdown) — More elaborate profiling interface
- [dbiprof](http://localhost/phpMan.php/perldoc/dbiprof/markdown) — Analyzer for DBI::ProfileDumper output
- [DBI::ProfileDumper::Apache](http://localhost/phpMan.php/perldoc/DBI%3A%3AProfileDumper%3A%3AApache/markdown) — For Apache/mod_perl
- [DBI::ProfileSubs](http://localhost/phpMan.php/perldoc/DBI%3A%3AProfileSubs/markdown) — Predefined path subroutines (e.g., `&norm_std_n3`)
- [DBI](http://localhost/phpMan.php/perldoc/DBI/markdown) — Database independent interface for Perl