view release on metacpan or  search on metacpan

lib/Dancer2/Plugin/Database.pm  view on Meta::CPAN

    };

    ## This is mostly for the case the user uses 'set plugins' and
    ## changes configuration during runtime. For example in our test suite.
    _load_settings($dsl);

    my ($dbh, $cfg) = Dancer::Plugin::Database::Core::database( arg => $_[0],
                                                                logger => $logger,
                                                                hook_exec => $hook_exec,
                                                                settings => $settings );
    $settings = $cfg;
    return $dbh;
};

register_plugin;

=head1 SYNOPSIS

    use Dancer2;
    use Dancer2::Plugin::Database;

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

    # The handle is a Dancer::Plugin::Database::Core::Handle object, which subclasses
    # DBI's DBI::db handle and adds a few convenience features, for example:
    get '/insert/:name' => sub {
        database->quick_insert('people', { name => params->{name} });
    };

    get '/users/:id' => sub {
        template 'display_user', {
            person => database->quick_select('users', { id => params->{id} }),
        };
    };

    dance;

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


=head1 DESCRIPTION

Provides an easy way to obtain a connected DBI database handle by simply calling
the database keyword within your L<Dancer2> application

Returns a L<Dancer::Plugin::Database::Core::Handle> object, which is a subclass of
L<DBI>'s C<DBI::db> connection handle object, so it does everything you'd expect
to do with DBI, but also adds a few convenience methods.  See the documentation
for L<Dancer::Plugin::Database::Core::Handle> for full details of those.

Takes care of ensuring that the database handle is still connected and valid.
If the handle was last asked for more than C<connection_check_threshold> seconds
ago, it will check that the connection is still alive, using either the 
C<< $dbh->ping >> method if the DBD 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.

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.)

=head1 CONFIGURATION

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

    plugins:
        Database:
            driver: 'mysql'
            database: 'test'
            host: 'localhost'
            port: 3306
            username: 'myusername'
            password: 'mypassword'
            connection_check_threshold: 10
            dbi_params:
                RaiseError: 1
                AutoCommit: 1
            on_connect_do: ["SET NAMES 'utf8'", "SET CHARACTER SET 'utf8'" ]
            log_queries: 1
            handle_class: 'My::Super::Sexy::Database::Handle'

The C<connection_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.

The C<dbi_params> setting is also optional, and if specified, should be settings
which can be passed to C<< DBI->connect >> as its fourth argument; see the L<DBI>
documentation for these.

The optional C<on_connect_do> setting is an array of queries which should be
performed when a connection is established; if given, each query will be
performed using C<< $dbh->do >>.  (If using MySQL, you might want to use this to
set C<SQL_MODE> to a suitable value to disable MySQL's built-in free data loss
'features', for example:

  on_connect_do: "SET SQL_MODE='TRADITIONAL'"

(If you're not familiar with what I mean, I'm talking about the insane default
behaviour of "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".
See L<http://effectivemysql.com/presentation/mysql-idiosyncrasies-that-bite/> for
just one illustration.  In hindsight, I wish I'd made a sensible C<sql_mode> a
default setting, but I don't want to change that now.)

The optional C<log_queries> setting enables logging of queries generated by the
helper functions C<quick_insert> et al in L<Dancer::Plugin::Database::Core::Handle>.