.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dancer::Plugin::Database 3pm"
.TH Dancer::Plugin::Database 3pm "2022-06-12" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dancer::Plugin::Database \- easy database connections for Dancer applications
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Dancer;
\&    use Dancer::Plugin::Database;
\&
\&    # Calling the database keyword will get you a connected database handle:
\&    get \*(Aq/widget/view/:id\*(Aq => sub {
\&        my $sth = database\->prepare(
\&            \*(Aqselect * from widgets where id = ?\*(Aq,
\&        );
\&        $sth\->execute(params\->{id});
\&        template \*(Aqdisplay_widget\*(Aq, { widget => $sth\->fetchrow_hashref };
\&    };
\&
\&    # The handle is a Dancer::Plugin::Database::Core::Handle object, which subclasses
\&    # DBI\*(Aqs DBI::db handle and adds a few convenience features, for example:
\&    get \*(Aq/insert/:name\*(Aq => sub {
\&        database\->quick_insert(\*(Aqpeople\*(Aq, { name => params\->{name} });
\&    };
\&
\&    get \*(Aq/users/:id\*(Aq => sub {
\&        template \*(Aqdisplay_user\*(Aq, {
\&            person => database\->quick_select(\*(Aqusers\*(Aq, { id => params\->{id} }),
\&        };
\&    };
\&
\&    dance;
.Ve
.PP
Database connection details are read from your Dancer application config \- see
below.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides an easy way to obtain a connected \s-1DBI\s0 database handle by simply calling
the database keyword within your Dancer application
.PP
Returns a Dancer::Plugin::Database::Core::Handle object, which is a subclass of
\&\s-1DBI\s0's \f(CW\*(C`DBI::db\*(C'\fR connection handle object, so it does everything you'd expect
to do with \s-1DBI,\s0 but also adds a few convenience methods.  See the documentation
for Dancer::Plugin::Database::Core::Handle for full details of those.
.PP
Takes care of ensuring that the database handle is still connected and valid.
If the handle was last asked for more than \f(CW\*(C`connection_check_threshold\*(C'\fR seconds
ago, it will check that the connection is still alive, using either the 
\&\f(CW\*(C`$dbh\->ping\*(C'\fR method if the \s-1DBD\s0 driver supports it, or performing a simple
no-op query against the database if not.  If the connection has gone away, a new
connection will be obtained and returned.  This avoids any problems for
a long-running script where the connection to the database might go away.
.PP
Care is taken that handles are not shared across processes/threads, so this
should be thread-safe with no issues with transactions etc.  (Thanks to Matt S
Trout for pointing out the previous lack of thread safety.  Inspiration was
drawn from DBIx::Connector.)
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
Connection details will be taken from your Dancer application config file, and
should be specified as, for example:
.PP
.Vb 10
\&    plugins:
\&        Database:
\&            driver: \*(Aqmysql\*(Aq
\&            database: \*(Aqtest\*(Aq
\&            host: \*(Aqlocalhost\*(Aq
\&            port: 3306
\&            username: \*(Aqmyusername\*(Aq
\&            password: \*(Aqmypassword\*(Aq
\&            connection_check_threshold: 10
\&            dbi_params:
\&                RaiseError: 1
\&                AutoCommit: 1
\&            on_connect_do: ["SET NAMES \*(Aqutf8\*(Aq", "SET CHARACTER SET \*(Aqutf8\*(Aq" ]
\&            log_queries: 1
\&            handle_class: \*(AqMy::Super::Sexy::Database::Handle\*(Aq
.Ve
.PP
The \f(CW\*(C`connection_check_threshold\*(C'\fR setting is optional, if not provided, it
will default to 30 seconds.  If the database keyword was last called more than
this number of seconds ago, a quick check will be performed to ensure that we
still have a connection to the database, and will reconnect if not.  This
handles cases where the database handle hasn't been used for a while and the
underlying connection has gone away.
.PP
The \f(CW\*(C`dbi_params\*(C'\fR setting is also optional, and if specified, should be settings
which can be passed to \f(CW\*(C`DBI\->connect\*(C'\fR as its fourth argument; see the \s-1DBI\s0
documentation for these.
.PP
The optional \f(CW\*(C`on_connect_do\*(C'\fR setting is an array of queries which should be
performed when a connection is established; if given, each query will be
performed using \f(CW\*(C`$dbh\->do\*(C'\fR.  (If using MySQL, you might want to use this to
set \f(CW\*(C`SQL_MODE\*(C'\fR to a suitable value to disable MySQL's built-in free data loss
\&'features', for example:
.PP
.Vb 1
\&  on_connect_do: "SET SQL_MODE=\*(AqTRADITIONAL\*(Aq"
.Ve
.PP
(If you're not familiar with what I mean, I'm talking about the insane default
behaviour of \*(L"hmm, this bit of data won't fit the column you're trying to put it
in.. hmm, I know, I'll just munge it to fit, and throw a warning afterwards \-
it's not like you're relying on me to, y'know, store what you ask me to store\*(R".
See <http://effectivemysql.com/presentation/mysql\-idiosyncrasies\-that\-bite/> for
just one illustration.  In hindsight, I wish I'd made a sensible \f(CW\*(C`sql_mode\*(C'\fR a
default setting, but I don't want to change that now.)
.PP
The optional \f(CW\*(C`log_queries\*(C'\fR setting enables logging of queries generated by the
helper functions \f(CW\*(C`quick_insert\*(C'\fR et al in Dancer::Plugin::Database::Core::Handle.
If you enable it, generated queries will be logged at 'debug' level.  Be aware
that they will contain the data you're passing to/from the database, so be
careful not to enable this option in production, where you could inadvertently
log sensitive information.
.PP
If you prefer, you can also supply a pre-crafted \s-1DSN\s0 using the \f(CW\*(C`dsn\*(C'\fR setting;
in that case, it will be used as-is, and the driver/database/host settings will 
be ignored.  This may be useful if you're using some \s-1DBI\s0 driver which requires 
a peculiar \s-1DSN.\s0
.PP
The optional \f(CW\*(C`handle_class\*(C'\fR defines your own class into which database handles
should be blessed.  This should be a subclass of
Dancer::Plugin::Database::Core::Handle (or DBI::db directly, if you just want to
skip the extra features).
.PP
You will require slightly different options depending on the database engine
you're talking to.  For instance, for SQLite, you won't need to supply
\&\f(CW\*(C`hostname\*(C'\fR, \f(CW\*(C`port\*(C'\fR etc, but will need to supply \f(CW\*(C`database\*(C'\fR as the name of the
SQLite database file:
.PP
.Vb 4
\&    plugins:
\&        Database:
\&            driver: SQLite
\&            database: \*(Aqfoo.sqlite\*(Aq
.Ve
.PP
For Oracle, you may want to pass \f(CW\*(C`sid\*(C'\fR (system \s-1ID\s0) to identify a particular
database, e.g.:
.PP
.Vb 5
\&    plugins:
\&        Database:
\&            driver: Oracle
\&            host: localhost
\&            sid: ABC12
.Ve
.PP
If you have any further connection parameters that need to be appended
to the dsn, you can put them in as a hash called dsn_extra. For
example, if you're running mysql on a non-standard socket, you could
have
.PP
.Vb 6
\&   plugins:
\&       Database:
\&           driver: mysql
\&           host: localhost
\&           dsn_extra:
\&               mysql_socket: /tmp/mysql_staging.sock
.Ve
.SS "\s-1DEFINING MULTIPLE CONNECTIONS\s0"
.IX Subsection "DEFINING MULTIPLE CONNECTIONS"
If you need to connect to multiple databases, this is easy \- just list them in
your config under \f(CW\*(C`connections\*(C'\fR as shown below:
.PP
.Vb 10
\&    plugins:
\&        Database:
\&            connections:
\&                foo:
\&                    driver: "SQLite"
\&                    database: "foo.sqlite"
\&                bar:
\&                    driver: "mysql"
\&                    host: "localhost"
\&                    ....
.Ve
.PP
Then, you can call the \f(CW\*(C`database\*(C'\fR keyword with the name of the database
connection you want, for example:
.PP
.Vb 2
\&    my $foo_dbh = database(\*(Aqfoo\*(Aq);
\&    my $bar_dbh = database(\*(Aqbar\*(Aq);
.Ve
.SH "RUNTIME CONFIGURATION"
.IX Header "RUNTIME CONFIGURATION"
You can pass a hashref to the \f(CW\*(C`database()\*(C'\fR keyword to provide configuration
details to override any in the config file at runtime if desired, for instance:
.PP
.Vb 1
\&    my $dbh = database({ driver => \*(AqSQLite\*(Aq, database => $filename });
.Ve
.PP
(Thanks to Alan Haggai for this feature.)
.SH "AUTOMATIC UTF\-8 SUPPORT"
.IX Header "AUTOMATIC UTF-8 SUPPORT"
As of version 1.20, if your application is configured to use \s-1UTF\-8\s0 (you've
defined the \f(CW\*(C`charset\*(C'\fR setting in your app config as \f(CW\*(C`UTF\-8\*(C'\fR) then support for
\&\s-1UTF\-8\s0 for the database connection will be enabled, if we know how to do so for
the database driver in use.
.PP
If you do not want this behaviour, set \f(CW\*(C`auto_utf8\*(C'\fR to a false value when
providing the connection details.
.SH "GETTING A DATABASE HANDLE"
.IX Header "GETTING A DATABASE HANDLE"
Calling \f(CW\*(C`database\*(C'\fR will return a connected database handle; the first time it is
called, the plugin will establish a connection to the database, and return a
reference to the \s-1DBI\s0 object.  On subsequent calls, the same \s-1DBI\s0 connection
object will be returned, unless it has been found to be no longer usable (the
connection has gone away), in which case a fresh connection will be obtained.
.PP
If you have declared named connections as described above in '\s-1DEFINING MULTIPLE
CONNECTIONS\s0', then calling the \fBdatabase()\fR keyword with the name of the
connection as specified in the config file will get you a database handle
connected with those details.
.PP
You can also pass a hashref of settings if you wish to provide settings at
runtime.
.SH "CONVENIENCE FEATURES"
.IX Header "CONVENIENCE FEATURES"
The handle returned by the \f(CW\*(C`database\*(C'\fR keyword is a
Dancer::Plugin::Database::Core::Handle object, which subclasses the \f(CW\*(C`DBI::db\*(C'\fR \s-1DBI\s0
connection handle.  This means you can use it just like you'd normally use a \s-1DBI\s0
handle, but extra convenience methods are provided.
.PP
There's extensive documentation on these features in
Dancer::Plugin::Database::Core::Handle, including using the \f(CW\*(C`order_by\*(C'\fR, \f(CW\*(C`limit\*(C'\fR,
\&\f(CW\*(C`columns\*(C'\fR options to sort / limit results and include only specific columns.
.SH "HOOKS"
.IX Header "HOOKS"
This plugin uses Dancer's hooks support to allow you to register code that
should execute at given times \- for example:
.PP
.Vb 4
\&    hook \*(Aqdatabase_connected\*(Aq => sub {
\&        my $dbh = shift;
\&        # do something with the new DB handle here
\&    };
.Ve
.PP
Currrently defined hook positions are:
.ie n .IP """database_connected""" 4
.el .IP "\f(CWdatabase_connected\fR" 4
.IX Item "database_connected"
Called when a new database connection has been established, after performing any
\&\f(CW\*(C`on_connect_do\*(C'\fR statements, but before the handle is returned.  Receives the
new database handle as a parameter, so that you can do what you need with it.
.ie n .IP """database_connection_lost""" 4
.el .IP "\f(CWdatabase_connection_lost\fR" 4
.IX Item "database_connection_lost"
Called when the plugin detects that the database connection has gone away.
Receives the no-longer usable handle as a parameter, in case you need to extract
some information from it (such as which server it was connected to).
.ie n .IP """database_connection_failed""" 4
.el .IP "\f(CWdatabase_connection_failed\fR" 4
.IX Item "database_connection_failed"
Called when an attempt to connect to the database fails.  Receives a hashref of
connection settings as a parameter, containing the settings the plugin was using
to connect (as obtained from the config file).
.ie n .IP """database_error""" 4
.el .IP "\f(CWdatabase_error\fR" 4
.IX Item "database_error"
Called when a database error is raised by \f(CW\*(C`DBI\*(C'\fR.  Receives two parameters: the
error message being returned by \s-1DBI,\s0 and the database handle in question.
.PP
If you need other hook positions which would be useful to you, please feel free
to suggest them!
.SH "AUTHOR"
.IX Header "AUTHOR"
David Precious, \f(CW\*(C`<davidp@preshweb.co.uk>\*(C'\fR
.SH "CONTRIBUTING"
.IX Header "CONTRIBUTING"
This module is developed on Github at:
.PP
<http://github.com/bigpresh/Dancer\-Plugin\-Database>
.PP
Feel free to fork the repo and submit pull requests!  Also, it makes sense to 
watch the repo <https://github.com/bigpresh/Dancer-Plugin-Database/toggle_watch> 
on GitHub for updates.
.PP
Feedback and bug reports are always appreciated.  Even a quick mail to let me
know the module is useful to you would be very nice \- it's nice to know if code
is being actively used.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Igor Bujna
.PP
Franck Cuny
.PP
Alan Haggai
.PP
Christian Sánchez
.PP
Michael Stiller
.PP
Martin J Evans
.PP
Carlos Sosa
.PP
Matt S Trout
.PP
Matthew Vickers
.PP
Christian Walde
.PP
Alberto Simões
.PP
James Aitken (LoonyPandora)
.PP
Mark Allen (mrallen1)
.PP
Sergiy Borodych (bor)
.PP
Mario Domgoergen (mdom)
.PP
Andrey Inishev (inish777)
.PP
Nick S. Knutov (knutov)
.PP
Nicolas Franck (nicolasfranck)
.PP
mscolly
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to \f(CW\*(C`bug\-dancer\-plugin\-database at rt.cpan.org\*(C'\fR, or through
the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dancer\-Plugin\-Database>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc Dancer::Plugin::Database
.Ve
.PP
You can also look for information at:
.IP "\(bu" 4
\&\s-1RT: CPAN\s0's request tracker
.Sp
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Dancer\-Plugin\-Database>
.IP "\(bu" 4
AnnoCPAN: Annotated \s-1CPAN\s0 documentation
.Sp
<http://annocpan.org/dist/Dancer\-Plugin\-Database>
.IP "\(bu" 4
\&\s-1CPAN\s0 Ratings
.Sp
<http://cpanratings.perl.org/d/Dancer\-Plugin\-Database>
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
<http://search.cpan.org/dist/Dancer\-Plugin\-Database/>
.PP
You can find the author on \s-1IRC\s0 in the channel \f(CW\*(C`#dancer\*(C'\fR on <irc.perl.org>.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2010\-2016 David Precious.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Dancer
.PP
\&\s-1DBI\s0
.PP
Dancer::Plugin::SimpleCRUD