Mojo::DB::Connector - Create and cache DB connections using common connection info
use Mojo::DB::Connector; # use default connection info or use connection info # set in environment variables my $connector = Mojo::DB::Connector->new; my $connection = $connector->new_connection; my $results = $connection->db->query(...); # pass connection info in (some defaults still used) my $connector = Mojo::DB::Connector->new(host => 'batman.com', userinfo => 'sri:s3cret'); my $connection = $connector->new_connection(database => 'my_s3cret_database'); my $results = $connection->db->query(...); # cache connections using Mojo::DB::Connector::Role::Cache my $connector = Mojo::DB::Connector->new->with_roles('+Cache'); # fresh connection the first time my $connection = $connector->cached_connection(database => 'my_database'); # later somewhere else... # same connection (Mojo::mysql or Mojo::Pg object) as before my $connection = $connector->cached_connection(database => 'my_database');
Mojo::DB::Connector is a thin wrapper around Mojo::mysql and Mojo::Pg that is useful when you want to connect to different databases using slightly different connection info. It also allows you to easily connect using different settings in different environments by using environment variables to connect (see "ATTRIBUTES"). This can be useful when developing using something like Docker, which easily allows you to set different environment variables in dev/prod.
Mojo::DB::Connector is a shell class that just composes Mojo::DB::Connector::Base:
with 'Mojo::DB::Connector::Base';
You may use Mojo::DB::Connector::Base as a starting point for your own DB Connectors, if needed.
See Mojo::DB::Connector::Role::Cache for the ability to cache connections.
my $connector = Mojo::DB::Connector->new(env_prefix => 'MOJO_DB_CONNECTOR_'); my $env_prefix = $connector->env_prefix; $connector = $connector->env_prefix('MOJO_DB_CONNECTOR_');
The prefix that will be used for environment variables names when checking for default values. The prefix will go before:
SCHEME
USERINFO
HOST
PORT
DATABASE
OPTIONS
URL
STRICT_MODE
"env_prefix" allows you to use different Mojo::DB::Connector objects to easily generate connections for different connection settings.
Default is MOJO_DB_CONNECTOR_.
MOJO_DB_CONNECTOR_
my $scheme = $connector->scheme; $connector = $connector->scheme('postgresql');
The "scheme" in Mojo::URL that will be used for generating the connection URL. Allowed values are mariadb, mysql, and postgresql. The scheme will determine whether a Mojo::mysql or Mojo::Pg instance is returned. mariadb and mysql indicate Mojo::mysql, and postgresql indicates Mojo::Pg.
mariadb
mysql
postgresql
This can also be derived from "scheme" in Mojo::URL via "url" or set with the environment variable MOJO_DB_CONNECTOR_SCHEME.
MOJO_DB_CONNECTOR_SCHEME
Default is first derived from "scheme" in Mojo::URL via $ENV{MOJO_DB_CONNECTOR_URL}, then $ENV{MOJO_DB_CONNECTOR_SCHEME}, and then falls back to postgresql.
$ENV{MOJO_DB_CONNECTOR_URL}
$ENV{MOJO_DB_CONNECTOR_SCHEME}
my $userinfo = $connector->userinfo; $connector = $connector->userinfo('sri:s3cret');
The "userinfo" in Mojo::URL that will be used for generating the connection URL.
This can also be derived from "userinfo" in Mojo::URL via "url" or set with the environment variable MOJO_DB_CONNECTOR_USERINFO.
MOJO_DB_CONNECTOR_USERINFO
Default is first derived from "userinfo" in Mojo::URL via $ENV{MOJO_DB_CONNECTOR_URL}, then $ENV{MOJO_DB_CONNECTOR_USERINFO}, and then falls back to no userinfo (empty string).
$ENV{MOJO_DB_CONNECTOR_USERINFO}
userinfo
my $host = $connector->host; $connector = $connector->host('localhost');
The "host" in Mojo::URL that will be used for generating the connection URL.
This can also be derived from "host" in Mojo::URL via "url" or set with the environment variable MOJO_DB_CONNECTOR_HOST.
MOJO_DB_CONNECTOR_HOST
Default is first derived from "host" in Mojo::URL via $ENV{MOJO_DB_CONNECTOR_URL}, then $ENV{MOJO_DB_CONNECTOR_HOST}, and then falls back to localhost.
$ENV{MOJO_DB_CONNECTOR_HOST}
localhost
my $port = $connector->port; $connector = $connector->port(5432);
The "port" in Mojo::URL that will be used for generating the connection URL.
This can also be derived from "port" in Mojo::URL via "url" or set with the environment variable MOJO_DB_CONNECTOR_PORT.
MOJO_DB_CONNECTOR_PORT
Default is first derived from "port" in Mojo::URL via $ENV{MOJO_DB_CONNECTOR_URL}, then $ENV{MOJO_DB_CONNECTOR_PORT}, and then falls back to 5432.
$ENV{MOJO_DB_CONNECTOR_PORT}
5432
my $database = $connector->database; $connector = $connector->database('my_database');
The database that will be used for generating the connection URL. This will be used as "path" in Mojo::URL.
This can also be derived from "path" in Mojo::URL via "url" or set with the environment variable MOJO_DB_CONNECTOR_DATABASE.
MOJO_DB_CONNECTOR_DATABASE
Default is first derived from "path" in Mojo::URL via $ENV{MOJO_DB_CONNECTOR_URL}, then $ENV{MOJO_DB_CONNECTOR_DATABASE}, and then falls back to no database (empty string).
$ENV{MOJO_DB_CONNECTOR_DATABASE}
database
my $options = $connector->options; $connector = $connector->options([PrintError => 1, RaiseError => 0]); # hashref also accepted $connector = $connector->options({PrintError => 1, RaiseError => 0});
The options that will be used as the parameters (Mojo::Parameters) for generating the connection URL. This will be used as "query" in Mojo::URL. This accepts any valid input for "query" in Mojo::URL except a list.
This can also be derived from "query" in Mojo::URL via "url" or set with the environment variable MOJO_DB_CONNECTOR_OPTIONS.
MOJO_DB_CONNECTOR_OPTIONS
When set with the environment variable MOJO_DB_CONNECTOR_OPTIONS, "options" must be specified in valid URL parameter syntax:
$ENV{MOJO_DB_CONNECTOR_OPTIONS} = 'PrintError=1&RaiseError=0';
Default is first derived from "query" in Mojo::URL via $ENV{MOJO_DB_CONNECTOR_URL}, then $ENV{MOJO_DB_CONNECTOR_OPTIONS}, and then falls back to [] (no options).
$ENV{MOJO_DB_CONNECTOR_OPTIONS}
[]
my $url = $connector->url; $connector = $connector->url('postgres://sri:s3cret@localhost/db3?PrintError=1&RaiseError=0');
The connection URL from which all other attributes can be derived (except "strict_mode"). "url" must be specified before the first call to "new_connection" is made, otherwise it will have no effect on setting the defaults.
This can also be set with the environment variable MOJO_DB_CONNECTOR_URL.
MOJO_DB_CONNECTOR_URL
Default is $ENV{MOJO_DB_CONNECTOR_URL} and then falls back to undef (no URL).
undef
my $strict_mode = $connector->strict_mode; $connector = $connector->strict_mode(1);
"strict_mode" determines if connections should be created in "strict_mode" in Mojo::mysql.
Note that this only applies to Mojo::mysql and does not apply to Mojo::Pg. If a Mojo::Pg connection is created, this will have no effect.
This can also be set with the environment variable MOJO_DB_CONNECTOR_STRICT_MODE.
MOJO_DB_CONNECTOR_STRICT_MODE
Default is $ENV{MOJO_DB_CONNECTOR_STRICT_MODE} and falls back to 1
$ENV{MOJO_DB_CONNECTOR_STRICT_MODE}
1
# use environment variables or defaults my $connection = $connector->new_connection; my $results = $connection->db->query(...); # provide attribute overrides just for this call my $connection = $connector->new_connection(database => 'my_database', host => 'batman.com'); my $results = $connection->db->query(...);
"new_connection" creates a new connection (Mojo::mysql or Mojo::Pg instance) using either the connection info in "ATTRIBUTES", or any override values passed.
Any override values that are passed will completely replace any values in "ATTRIBUTES":
my $connection = $connector->new_connection(database => 'my_database', host => 'batman.com'); my $results = $connection->db->query(...);
Except for "options". "options" follows the same format as "query" in Mojo::URL:
# merge with existing options in attribute options by using a hashref my $connection = $connector->new_connection(options => {merge => 'to'}); # append to existing options in attribute options by using an arrayref my $connection = $connector->new_connection(options => [append => 'with']); # replace existing options completely by passing replace_options => 1 # must provide an arrayref for replace_options my $connection = $connector->new_connection(options => [append => 'with'], replace_options => 1);
replace_options is needed because you cannot pass a list for the options value. If replace_options is provided, the options parameter must be an arrayref.
replace_options
options
See "options" in Mojo::mysql or "options" in Mojo::Pg.
Mojo::DB::Connector::Base
Mojo::DB::Connector::Role::Cache
Mojo::DB::Connector::Role::ResultsRoles
Apply roles to Mojo database results from Mojo::DB::Connector connections.
Mojo::mysql
Mojo::Pg
This software is copyright (c) 2020 by Adam Hopkins
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Adam Hopkins <srchulo@cpan.org>
To install Mojo::DB::Connector, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojo::DB::Connector
CPAN shell
perl -MCPAN -e shell install Mojo::DB::Connector
For more information on module installation, please visit the detailed CPAN module installation guide.