DBIx::QueryLog(3pm)

💅 DBIx::QueryLog — bestie edition ✨

okay so this is the DBIx::QueryLog(3pm) page, and honestly? it's a little icon. it logs your queries for DBI. that's the whole vibe. let's get into it 🫶

---

✨ NAME ✨

DBIx::QueryLog — logging queries for DBI, periodt 💅

---

🌸 SYNOPSIS 🌸

use DBIx::QueryLog;
my $row = $dbh->selectrow_hashref('SELECT * FROM people WHERE user_id = ?', undef, qw/1986/);
# => SELECT * FROM people WHERE user_id = '1986';

like, it literally shows you the real query with the placeholders filled in. slay 🔥

---

🦋 DESCRIPTION 🦋

DBIx::QueryLog logs each execution time and the actual query. no cap, that's the whole job.

Currently, it works with DBD::mysql, DBD::Pg and DBD::SQLite. those three. that's the squad 💜

---

👑 CLASS METHODS 👑

⭐ threshold

If you set this, only the queries that take more time than this threshold get logged (default is undef, aka no filtering, aka log everything).

DBIx::QueryLog->threshold(0.1); # sec

You can also specify this with the DBIX_QUERYLOG_THRESHOLD environment variable. env var girlies rise 🙈

⭐ probability

If you set this, the logger logs only once per a defined value (default is undef).

DBIx::QueryLog->probability(100); # about 1/100

You can also specify this with the DBIX_QUERYLOG_PROBABILITY environment variable.

⭐ logger

Sets a logger class (e.g. Log::Dispach).

The logger class must have a log method, which should work like the one of Log::Dispatch (but see also the OUTPUT section below 👀).

DBIx::QueryLog->logger($logger);

⭐ skip_bind

If set, DBIx::QueryLog runs faster, but placeholders are not processed. speed vs. detail, the eternal struggle 😭

DBIx::QueryLog->skip_bind(1);
my $row = $dbh->do(...);
# => 'SELECT * FROM people WHERE user_id = ?' : [1986]

You can also specify this with the DBIX_QUERYLOG_SKIP_BIND environment variable.

⭐ color

If set, log messages will be colored with Term::ANSIColor. aesthetic logging only 💖

DBIx::QueryLog->color('green');

You can also specify this with the DBIX_QUERYLOG_COLOR environment variable.

⭐ useqq

If set, DBIx::QueryLog uses $Data::Dumper::Useqq.

DBIx::QueryLog->useqq(1);

You can also specify this with the DBIX_QUERYLOG_USEQQ environment variable.

⭐ compact

If set, log messages will be compact. it's giving "declutter my life" ✨

DBIx::QueryLog->compact(1);
#  FROM: SELECT          *  FROM      foo WHERE bar = 'baz'
#  TO  : SELECT * FROM foo WHERE bar = 'baz'

You can also specify this with the DBIX_QUERYLOG_COMPACT environment variable.

⭐ explain

EXPERIMENTAL — like, it's still in its testing era, ok?

If set, DBIx::QueryLog logs the result of an EXPLAIN statement.

DBIx::QueryLog->explain(1);
my $row = $dbh->do(...);
# => SELECT * FROM peaple WHERE user_id = '1986'
#  .----------------------------------------------------------------------------------------------.
#  | id | select_type | table  | type  | possible_keys | key     | key_len | ref   | rows | Extra |
#  +----+-------------+--------+-------+---------------+---------+---------+-------+------+-------+
#  |  1 | SIMPLE      | peaple | const | PRIMARY       | PRIMARY |       4 | const |    1 |       |
#  '----+-------------+--------+-------+---------------+---------+---------+-------+------+-------'

(yes, peaple — that's how it's written in the example, we don't touch it 💀)

You can also specify this with the DBIX_QUERYLOG_EXPLAIN environment variable.

⭐ show_data_source

if set, the DBI data_source will be added to the log messages. receipts included 🧾

$dbh->do('SELECT * FROM sqlite_master');
# [2012-03-09T00:58:23] [main] [0.000953] SELECT * FROM sqlite_master at foo.pl line 34

DBIx::QueryLog->show_data_source(1);
$dbh->do('SELECT * FROM sqlite_master');
# [2012-03-09T00:58:23] [main] [0.000953] [SQLite:dbname=/tmp/TrSATdY3cc] SELECT * FROM sqlite_master at foo.pl line 56

You can also specify this with the DBIX_QUERYLOG_SHOW_DATASOURCE environment variable.

⭐ guard

Returns a guard object. it's a scoped little guy — lives only inside the block 🎀

use DBIx::QueryLog ();
{
    my $guard = DBIx::QueryLog->guard;
    # ... do something
}

The following code does the same:

use DBIx::QueryLog ();

DBIx::QueryLog->enable;
# ... do something
DBIx::QueryLog->disable;

⭐ ignore_trace

Returns a guard object and disables tracing while the object is alive. so like, quiet mode but only in this block 🤫

use DBIx::QueryLog;

# enabled
$dbh->do(...);

{
    my $guard = DBIx::QueryLog->ignore_trace;
    # disable
    $dbh->do(...);
}

# enabled
$dbh->do(...)

⭐ is_enabled

Returns whether DBIx::QueryLog is enabled or not.

use DBIx::QueryLog ();

say DBIx::QueryLog->is_enabled;

DBIx::QueryLog->disable;

See also the Localization section. 💜

---

🌈 TIPS 🌈

🎀 Localization

If you want to log only in a specific scope — like, main character energy but only for one scene:

use DBIx::QueryLog (); # or require DBIx::QueryLog;

DBIx::QueryLog->begin; # or DBIx::QueryLog->enable
my $row = $dbh->do(...);
DBIx::QueryLog->end;   # or DBIx::QueryLog->disable

DBIx::QueryLog logs only between begin and end. boundaries, bestie 🫶

🎀 LOG_LEVEL

When you set a logger, you might also want to change a log level.

$DBIx::QueryLog::LOG_LEVEL = 'info'; # default 'debug'

🎀 OUTPUT

If you want to change where to output:

open my $fh, '>', 'dbix_query.log';
$DBIx::QueryLog::OUTPUT = $fh;

You can also specify a code reference:

$DBIx::QueryLog::OUTPUT = sub {
    my %params = @_;

    my $format = << 'FORMAT';
localtime  : %s       # ISO-8601 without timezone
level      : %s       # log level ($DBIx::QueryLog::LOG_LEVEL)
time       : %f       # elasped time
data_source: $s       # data_source
sql        : %s       # executed query
bind_params: %s       # bind parameters
pkg        : %s       # caller package
file       : %s       # caller file
line       : %d       # caller line
FORMAT

    printf $format,
        @params{qw/localtime level pkg time data_source sql/},
        join(', ', @{$params{bind_params}}),
        @params{qw/file line/};

    printf "AutoCommit?: %d\n", $params->{dbh}->{AutoCommit} ? 1 : 0;
};

(yes, $s and elasped are in there — we're preserving them exactly, character for character, no editing the source 💀)

You can also use this if you want to use a logger that doesn't have a log method like the one of <Log::Dispatch>.

$DBIx::QueryLog::OUTPUT = sub {
    my %params = @_;
    my $logger = Log::Any->get_logger;
    $logger->debug("$params{message}");
};

Note that this only works when "<logger"> is not set.

Default $OUTPUT is "STDERR". classic, reliable, iconic 💅

---

💖 AUTHOR 💖

xaicron <xaicron {at} cpan.org>

🫶 THANKS TO 🫶

• tokuhirom
• yibe
• kamipo
• tomi-ru
• riywo
• makamaka

the whole friend group showed up for this one 🥹

🐛 BUG REPORTING 🐛

Plese use github issues: <https://github.com/xaicron/p5-DBIx-QueryLog/issues>. (and yes — "Plese" is exactly how it's spelled, we stan a typo that's been there since 2010 💀)

📜 COPYRIGHT 📜

Copyright 2010 - xaicron

⚖️ LICENSE ⚖️

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🔗 SEE ALSO 🔗

• DBI

---

okay and last thing, the official footer receipt: this is perl v5.32.1, dated 2022-01-21 💜 go log something cute, bestie, and remember — every query is a moment ✨🔥