NAME

Prancer::Plugin::Database

SYNOPSIS

This plugin enables connections to a database and exports a keyword to access those configured connections.

It's important to remember that when running your application in a single- threaded, single-process application server like, say, Twiggy, all users of your application will use the same database connection. If you are using callbacks then this becomes very important and you will want to take care to avoid crossing transactions or expecting a database connection or transaction to be in the same state it was before a callback.

To use a database connector, add something like this to your configuration file:

database:
    connection-name:
        driver: Prancer::Plugin::Database::Driver::DriverName
        options:
            username: test
            password: test
            database: test
            hostname: localhost
            port: 5432
            autocommit: true
            charset: utf8
            connection_check_threshold: 10
            dsn_extra:
                RaiseError: 0
                PrintError: 1
            on_connect:
                - SET search_path=public

The "connection-name" can be anything you want it to be. This will be used when requesting a connection from the plugin to determine which connection to return. If only one connection is configured and no specific connection name is requested then the only configured connection will be returned. If more than one connection is configured and no specific connection name is requested then any connection that is named "default" will be used. Otherwise an error will be thrown. For example:

use Prancer::Plugin::Database qw(database);

Prancer::Plugin::Database->load();

# if only one connection is configured then this will return that
# connection
my $dbh = database;

# if multiple connections are configured and one of them is called
# "default" then this will return the connection named "default" or throw
# an error if no connection is named "default"
my $dbh = database;

# this will return a configured connection named "foo" or throw an error if
# no connections are named "foo"
my $dbh = database("foo");

OPTIONS

database

REQUIRED The name of the database to connect to.

username

The username to use when connecting. If this option is not set then the default is the user running the application server or the current user.

password

The password to use when connecting. If this option is not set then the default is to connect with no password.

hostname

The host name of the database server. If this option is not set then the default is to connect to localhost.

port

The port number on which the database server is listening. If this option is not set then the default is to connect on the database's default port.

autocommit

If set to a true value -- like 1, yes, or true -- then this will enable autocommit. If set to a false value -- like 0, no, or false -- then this will disable autocommit. By default, autocommit is enabled.

charset

The character set to connect to the database with. If this is set to "utf8" then the database connection will attempt to make UTF8 data Just Work if available.

connection_check_threshold

This sets the number of seconds that must elapse between calls to get a database handle before performing a check to ensure that a database connection still exists and will reconnect if one does not. This handles cases where the database handle hasn't been used in a while and the underlying connection has gone away. If this is not set then it will default to 30 seconds.

dsn_extra

If you have any further connection parameters that need to be appended to the dsn then you can put them in the configuration as a hash. This hash will be merged into the default parameters and overwrite any that are duplicated. The dsn parameters set by default are AutoCommit to 1, RaiseError to 1, and PrintError to 0. This option will take precedence over the autocommit flag above.

on_connect

This can be an array of commands execute on a successful connection. These will be executed on every connection so if the connection goes away but is re- established then these commands will be run again.

CREDIT

This module is derived from Dancer::Plugin::Database. Thank you to David Precious.

COPYRIGHT

Copyright 2014, 2015 Paul Lockaby. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

• Prancer