--- name: "Log::Handler::Output::DBI" section: "3pm" platform: "linux" package: "liblog-handler-perl" version: "0.90-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Log::Handler::Output::DBI" --- # Log::Handler::Output::DBI(3pm) Log messages to a database. ## NAME Log::Handler::Output::DBI - Log messages to a database. ## SYNOPSIS ``` 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); ``` ## DESCRIPTION With this output you can insert messages into a database table. ## METHODS ### new() Call `"new()"` to create a new Log::Handler::Output::DBI object. 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"`. - **database** or **dbname** Pass the database name. - **driver** Pass the database driver. - **host** Pass the hostname where the database is running. - **port** Pass the port where the database is listened. - **user** Pass the database user for the connect. - **password** Pass the users password. - **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"`. ``` 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. ``` %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. 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. ``` 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. ``` 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. ### validate() Validate a configuration. ### reload() Reload with a new configuration. ### errstr() This function returns the last error message. ## PREREQUISITES ``` Carp Params::Validate DBI your DBI driver you want to use ``` ## EXPORTS No exports. ## REPORT BUGS Please report all bugs to \. If you send me a mail then add Log::Handler into the subject. ## AUTHOR Jonny Schulz \. ## 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.