/ 
Mojo-DB-Connector-0.03
River stage zero No dependents
/ Mojo::DB::Connector::Role::Cache

STATUS

Coverage Status

NAME

Mojo::DB::Connector::Role::Cache - Cache Mojo::DB::Connector connections

SYNOPSIS

use Mojo::DB::Connector;

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');

# caching works with options
my $connection = $connector->cached_connection(database => 'my_database', options => [PrintError => 1, RaiseError => 0]);

# same connection as above, because options are sorted by key then value
# before being used in the cache URL key as parameters
my $connection = $connector->cached_connection(database => 'my_database', options => [RaiseError => 0, PrintError => 1]);

DESCRIPTION

Mojo::DB::Connector::Role::Cache allows you to easily cache connections based on the connection settings and options. A Mojo::URL is created for each new or cached connection, and this is the cache key. A connection URL may look like:

mysql://batman:s3cret@localhost/db3

And if this connection URL is seen again, the same connection object (Mojo::mysql) will be returned. This caching even works with options ("options" in Mojo::mysql, "options" in Mojo::Pg) because the options are sorted by key and then value before generating the URL:

my $connection = $connector->cached_connection(database => 'my_database', options => [RaiseError => 0, PrintError => 1]);

# the cache key for the above connection
# note that RaiseError and PrintError have switched their order
mysql://batman:s3cret@localhost/my_database?PrintError=1&RaiseError=0

ATTRIBUTES

cache

my $cache  = $connector->cache;
$connector = $connector->cache(Mojo::Cache->new);

# set max number of connections to cache
$connector->cache->max_keys(50);

"cache" is a Mojo::Cache that is used to cache connections. By default it will cache 100 connections based on the default of "max_keys" in Mojo::Cache.

METHODS

cached_connection

my $connection = $connector->cached_connection(database => 'my_database');

# works with options because options are sorted by key then value
# before being used in the cache URL key as parameters
my $connection = $connector->cached_connection(database => 'my_database', options => [RaiseError => 0, PrintError => 1]);

"cached_connection" will return a cached connection if one is available, or generate and cache a new connection to return. The cache key is a stringified Mojo::URL (using "to_unsafe_string" in Mojo::URL) that is based on the connection settings and options. For example, different databases will generate different connections:

my $connection       = $connector->cached_connection(database => 'my_database');
my $other_connection = $connector->cached_connection(database => 'my_other_database');

And so will different options:

my $connection       = $connector->cached_connection(database => 'my_database');
my $other_connection = $connector->cached_connection(database => 'my_database', options => [RaiseError => 0]);

"cached_connection" works with options ("options" in Mojo::mysql, "options" in Mojo::Pg) because the options are sorted by key and then value before generating the URL.

"userinfo" in Mojo::URL is hashed using "sha1_sum" in Mojo::Util before being used in the cache key to ensure that username and password information do not sit in memory.

See "cache" for how to set "max_keys" in Mojo::Cache to control how many connections are cached.

SEE ALSO

LICENSE

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.

AUTHOR

Adam Hopkins <srchulo@cpan.org>