The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
ShardedKV-0.20
River stage one • 3 direct dependents • 3 total dependents
1 ++
/ ShardedKV::Storage::MySQL

NAME

ShardedKV::Storage::MySQL - MySQL storage backend for ShardedKV

VERSION

version 0.20

SYNOPSIS

  use ShardedKV;
  use ShardedKV::Storage::MySQL;
  ... create ShardedKV...
  my $storage = ShardedKV::Storage::MySQL->new(
  );
  ... put storage into ShardedKV...
  
  # values are array references
  $skv->set("foo", ["bar"]);
  my $value_ref = $skv->get("foo");

DESCRIPTION

A ShardedKV storage backend that DBI and DBD::mysql to store data in a MySQL table.

Implements the ShardedKV::Storage role.

Each shard (== ShardedKV::Storage::MySQL object) is represented by a single table in some schema on some database server.

PUBLIC ATTRIBUTES

mysql_connector

A callback that must be supplied at object creation time. The storage object will invoke the callback whenever it needs to get a NEW mysql database handle. This means when:

  - first connecting
  - Error matches refresh_mysql_connection_on_error_regex => reconnect

The callback allows users to hook into the connection logic to implement things such as connection caching. If you do use connection caching, then do assert that the dbh is alive (eg. using $dbh->ping() before returning a cached connection.

mysql_endpoint

A callback that should return a unique string that represents the endpoint. In most cases this should be a hostname to allow for debugging connection issues.

The callback allows users to hook into the connection logic and update the string that represents the particular endpoint that this storage instance represents.

mysql_connection

This is the public attribute holding a MySQL database handle (which was created using the mysql_connector). Do not supply this at object creation.

table_name

The name of the table that represents this shard. Must be supplied at object creation.

key_col_name

The name of the column to be used for the key. If ShardedKV::Storage::MySQL creates the shard table for you, then this column is also used as the primary key unless auto_increment_col_name is set (see below).

There can only be one key column.

Defaults to 'keystr'.

key_col_type

The MySQL type of the key column.

Defaults to 'VARBINARY(16) NOT NULL'.

auto_increment_col_name

The name of the column to be used for the auto-increment pimrary key. This is a virtually unused (by ShardedKV) column that, IF DEFINED, will be used as an auto-increment primary key. It is not the column used to fetch rows by, but rather facilitates faster insertion of new records by allowing append instead of insertion at random order within the PK tree.

If ShardedKV::Storage::MySQL creates the shard table for you, then this column is also used as the primary key.

There can only be one auto-increment key column.

Defaults to 'id'.

auto_increment_col_type

The MySQL type of the auto increment column.

Defaults to 'BIGINT UNSIGNED NOT NULL AUTO_INCREMENT'.

value_col_names

An array reference containing the names of all value columns in the shard table. Needs to contain at least one value column.

Defaults to [qw(val last_change)].

value_col_types

An array reference containing the MySQL types of each value column given in value_col_names.

Defaults to: ['MEDIUMBLOB NOT NULL', 'TIMESTAMP NOT NULL'].

extra_indexes

A string that is included verbatim after the PRIMARY KEY line of the CREATE TABLE IF NOT EXISTS statement that this class generates. This can be used to add additional indexes to the shard tables, such as indexes on the last modification (for expiration from the database, not handled by ShardedKV).

max_num_reconnect_attempts

The maximum number of reconnect attempts that the storage object should perform if the MySQL server has gone away. Reconnects are done with exponential back-off (see below).

Defaults to 5.

reconnect_interval

The base interval for reconnection attempts. Do note that exponential reconnect back-off is used, so if the base reconnect_interval is 1 second, then the first reconnect attempt is done immediately, the second after one second, the third after two seconds, the fourth after four seconds, and so on.

Default: 1 second

Can also be fractional seconds.

refresh_mysql_connection_on_error_regex

A regular expression that we'll match MySQL errors against, if it matches the error is considered recoverable and we'll refresh the connection. Set to Undef to disable this feature.

Default: Matches "MySQL server has gone away" and "Lost connection to MySQL server during query" errors. See the source.

PUBLIC METHODS

prepare_table

This method will generate a CREATE TABLE statement from the various properties of the storage object and execute it on the MySQL server to prepare the shard table.

refresh_connection

Explicitly drops the MySQL connection object and calls back into the provided connect handler to get a new connection.

SEE ALSO

AUTHORS

  • Steffen Mueller <smueller@cpan.org>

  • Nick Perez <nperez@cpan.org>

  • Damian Gryski <dgryski@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Steffen Mueller.

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