Provided by: liblog-handler-perl_0.82-1_all bug

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 <jschulz.cpan(at)bloonix.de>.

       If you send me a mail then add Log::Handler into the subject.

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.