NAME

Dancer::Plugin::Database - easy database connections for Dancer

SYNOPSIS

use Dancer;
use Dancer::Plugin::Database;

# Calling the database keyword will get you a connected DBI handle:
get '/widget/view/:id' => sub {
    my $sth = database->prepare(
        'select * from widgets where id = ?',
        {}, params->{id}
    );
    $sth->execute;
    template 'display_widget', { widget => $sth->fetchrow_hashref };
};

dance;

Database connection details are read from your Dancer application config - see below.

DESCRIPTION

Provides an easy way to obtain a connected DBI database handle by simply calling the database keyword within your Dancer application.

Takes care of ensuring that the database handle is still connected and valid. If the handle was last asked for more than connection_check_threshold seconds ago, it will perform a simple no-op query against the database and check that it worked; if not, a new connection will be obtained. This avoids any problems for a long-running script where the connection to the database might go away.

CONFIGURATION

Connection details will be taken from your Dancer application config file, and should be specified as, for example:

plugins:
    database:
        driver: mysql
        database: test'
        host: localhost
        username: 'myusername'
        password: 'mypassword'
        connectivity-check-threshold: 10

The connectivity-check-threshold 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.

Calling database 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 DBI object.

If you prefer, you can also supply a pre-crafted DSN; 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 DBI driver which requires a peculiar DSN.

AUTHOR

David Precious, <davidp@preshweb.co.uk>

CONTRIBUTING

This module is developed on Github at:

http://github.com/bigpresh/Dancer-Plugin-Database

Feel free to fork the repo and submit pull requests!

BUGS

Please report any bugs or feature requests to bug-dancer-plugin-database at rt.cpan.org, 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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Dancer::Plugin::Database

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010 David Precious.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

SEE ALSO

Dancer

DBI