view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Dancer2::Plugin::Database - easy database connections for Dancer
    applications

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.

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

    Returns a Dancer::Plugin::Database::Core::Handle object, which is a subclass
    of DBI's `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 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
    `connection_check_threshold' seconds ago, it will check that the
    connection is still alive, using either the `$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.)

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 `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 `dbi_params' setting is also optional, and if specified, should be
    settings which can be passed to `DBI->connect' as its fourth argument;
    see the DBI documentation for these.

    The optional `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 `$dbh->do'. (If using MySQL, you might want to use
    this to set `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
    http://effectivemysql.com/presentation/mysql-idiosyncrasies-that-bite/
    for just one illustration. In hindsight, I wish I'd made a sensible
    `sql_mode' a default setting, but I don't want to change that now.)

    The optional `log_queries' setting enables logging of queries generated
    by the helper functions `quick_insert' et al in