Log::H...ut::DBI(3pm)

💖 Log::Handler::Output::DBI 💖

okay bestie, listen up — this is Log::Handler::Output::DBI, a lil Perl module that shoves your log messages straight into a database table. yes, fr fr, your logs are going in the DB. slay.

---

✨ NAME ✨

Log::Handler::Output::DBI — Log messages to a database. that's the whole vibe. 💅

---

🦋 SYNOPSIS 🦋

setting it up, bestie:

use Log::Handler::Output::DBI;

my $db = Log::Handler::Output::DBI->new(
    # database source
    database    => "database",
    driver      => "mysql",
    host        => "127.0.0.1",
    port        => 3306,

    # or with "dbname" instead of "database"
    dbname      => "database",
    driver      => "Pg",
    host        => "127.0.0.1",
    port        => 5432,

    # or with data_source
    data_source => "dbi:mysql:database=database;host=127.0.0.1;port=3306",

    # Username and password
    user        => "user",
    password    => "password",

    # debugging
    debug       => 1,

    # table, columns and values (as string)
    table       => "messages",
    columns     => "level ctime cdate pid hostname progname message",
    values      => "%level %time %date %pid %hostname %progname %message",

    # table, columns and values (as array reference)
    table       => "messages",
    columns     => [ qw/level ctime cdate pid hostname progname message/ ],
    values      => [ qw/%level %time %date %pid %hostname %progname %message/ ],

    # table, columns and values (your own statement)
    statement   => "insert into messages (level,ctime,cdate,pid,hostname,progname,message) values (?,?,?,?,?,?,?)",
    values      => [ qw/%level %time %date %pid %hostname %progname %message/ ],

    # if you like persistent connections and want to re-connect
    persistent  => 1,
);

my %message = (
    level       => "ERROR",
    time        => "10:12:13",
    date        => "1999-12-12",
    pid         => $$,
    hostname    => "localhost",
    progname    => $0,
    message     => "an error here"
);

$db->log(\%message);

literally copy that and adjust ur connection info. 💖

---

🌸 DESCRIPTION 🌸

With this output you can insert messages into a database table. that's it, that's the whole job, and it does it gorgeously. 👑

---

💅 METHODS 💅

new()

Call new() to create a new Log::Handler::Output::DBI object. main character constructor energy.

The following options are possible:

• data_source — Set the dsn (data source name). You can use this parameter instead of database, driver, host and port. iykyk, it's the all-in-one route.
• database or dbname — Pass the database name. two names, same job, pick whichever hits.
• driver — Pass the database driver.
• host — Pass the hostname where the database is running.
• port — Pass the port where the database is listened. yes bestie, the DB has to be listening on something.
• user — Pass the database user for the connect.
• password — Pass the users password. (keep it secret, keep it safe 🔐)
• table and columns — With this options you can pass the table name for the insert and the columns. You can pass the columns as string or as array. Example:

# the table name
table => "messages",

# columns as string
columns => "level, ctime, cdate, pid, hostname, progname, message",

# columns as array
columns => [ qw/level ctime cdate pid hostname progname message/ ],

The statement would created as follows

insert into message (level, ctime, cdate, pid, hostname, progname, mtime, message)
             values (?,?,?,?,?,?,?)

• statement — With this option you can pass your own statement if you don't want to you the options table and columns. craft it urself, chef's kiss:

statement => "insert into message (level, ctime, cdate, pid, hostname, progname, mtime, message)"
             ." values (?,?,?,?,?,?,?)"

• values — With this option you have to set the values for the insert.

values => "%level, %time, %date, %pid, %hostname, %progname, %message",

# or

values => [ qw/%level %time %date %pid %hostname %progname %message/ ],

The placeholders are identical with the pattern names that you have to pass with the option message_pattern from Log::Handler. the lore ✨:

• %L — level
• %T — time
• %D — date
• %P — pid
• %H — hostname
• %N — newline
• %C — caller
• %p — package
• %f — filename
• %l — line
• %s — subroutine
• %S — progname
• %r — runtime
• %t — mtime
• %m — message

Take a look to the documentation of Log::Handler for all possible patterns. 📖

• persistent — With this option you can enable or disable a persistent database connection and re-connect if the connection was lost. This option is set to 1 on default.
• dbi_params — This option is useful if you want to pass arguments to DBI. The default is set to

{
    PrintError => 0,
    AutoCommit => 1
}

PrintError is deactivated because this would print error messages as warnings to STDERR. not the vibe, so it's off by default.

You can pass your own arguments - and overwrite it - with

dbi_params => { PrintError => 1, AutoCommit => 0 }

• debug — With this option it's possible to enable debugging. The information can be intercepted with $SIG{__WARN__}.

---

log()

Log a message to the database. the moment we've all been waiting for 🎀

my $db = Log::Handler::Output::DBI->new(
    database   => "database",
    driver     => "mysql",
    user       => "user",
    password   => "password",
    host       => "127.0.0.1",
    port       => 3306,
    table      => "messages",
    columns    => [ qw/level ctime message/ ],
    values     => [ qw/%level %time %message/ ],
    persistent => 1,
);

$db->log(
    message => "your message",
    level   => "INFO",
    time    => "2008-10-10 10:12:23",
);

Or you can connect to the database yourself. You should notice that if the database connection lost then the logger can't re-connect to the database and would return an error. Use dbi_handle at your own risk.

🚨 bestie listen: hand it your own handle and if the connection drops, there's no re-connect — you just get an error. use dbi_handle at your own risk. fr.

my $dbh = DBI->connect(...);

my $db = Log::Handler::Output::DBI->new(
    dbi_handle => $dbh,
    table      => "messages",
    columns    => [ qw/level ctime message/ ],
    values     => [ qw/%level %time %message/ ],
);

---

connect()

Connect to the database. 🔌

---

disconnect()

Disconnect from the database. bye bye 👋

---

validate()

Validate a configuration. vibe check on ur config.

---

reload()

Reload with a new configuration.

---

errstr()

This function returns the last error message. when something goes wrong, this tells u what. 😭

---

🎀 PREREQUISITES 🎀

Carp
Params::Validate
DBI
your DBI driver you want to use

---

🌈 EXPORTS 🌈

No exports. nothing, nada. clean. ✨

---

🐛 REPORT BUGS 🐛

Please report all bugs to <jschulz.cpan(at)bloonix.de>.

If you send me a mail then add Log::Handler into the subject. don't forget bestie, or it gets lost in the inbox void 💀

---

👑 AUTHOR 👑

Jonny Schulz <jschulz.cpan(at)bloonix.de>.

---

💜 COPYRIGHT 💜

Copyright (C) 2007-2009 by Jonny Schulz. All rights reserved.

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

---

and that's the whole page, bestie 🫶 this was the manpage for Log::Handler::Output::DBI from perl v5.36.0, dated 2022-08-28. go forth and log, icon. periodt. 💖✨