StoredHash - Minimalistic, yet fairly complete DBI Persister with a definite NoSQL feel to it
use StoredHash;
use DBI;
use Data::Dumper;
my $dbh = DBI->connect("dbi:SQLite:dbname=/tmp/zoo.db");
# Lightweight demonstration of StoredHash in action (with SQLite)
$dbh->do("CREATE TABLE animals (speciesid INTEGER NOT NULL PRIMARY KEY, name CHAR(16), limbcnt INTEGER, family CHAR(16))");
my $shp = StoredHash->new('table' => 'animals', 'pkey' => ['speciesid'],
'autoid' => 1, 'dbh' => $dbh, 'debug' => 0);
# Hash object to be stored
my $monkey = {'name' => 'Common Monkey', 'limbcnt' => 5, 'family' => 'mammal',};
# Happens to return numeric id (because of auto-increment pkey / autoid)
my $spid = $shp->insert($monkey);
print("Created by: id=$spid\n");
# Load entry
my $ent = $shp->load([$spid]);
print("Fetched (by $spid): ".Dumper($ent)."\n");
# Get: {'name' => 'Common Monkey', 'speciesid' => 469, 'limbcnt' => 5,'family' => 'mammal',}
# Fix error in entry (don't count tail to be limb)
$ent->{'limbcnt'} = 4;
# Update (with some redundant attributes that do not change)
print("Update $ent->{'speciesid'}\n");
$shp->update($ent, [$ent->{'speciesid'}]);
# Could reduce / optimize change to bare minimum:
my %change = ('limbcnt' => 4);
print("Reduce property value on $spid\n");
$shp->update(\%change, [$spid]);
# Later ... (species dies extinct ?)
#$shp->delete([$spid]);
# Test if we need to insert / update (based on presence in DB)
my $id = 5987;
my $invals = {'name' => 'Crow', 'limbcnt' => 4, 'family' => 'birds'};
print("Test Presence of Animal '$id'\n");
if ($shp->exists([$id])) {$shp->update($invals, [$id]);}
else {$shp->insert($invals);}
##### Easy loading of sets / collections
# Load all the animals
my $animarr = $shp->loadset();
print("All Animals: ".Dumper($animarr)."\n");
# Load only mammals (by filter)
my $mammarr = $shp->loadset({'family' => 'mammal'});
print("Mammals: ".Dumper($mammarr)."\n");
Allow DB Persistence operations (insert(), load(), update(), delete(), exists()) on a plain old hash (unblessed or blessed) without writing classes, persistence code or SQL.
Optionally StoredHash allows your classes to inherit peristence capability from StoredHash allowing your objects to call StoredHash persistence methoda via object directly.
Above principles are consistent across persistence methods. These details will be not repeated in method documentation.
Create new instance of StoredHash Persister.
Keyword parameters in %opts:
Access error string that method may leave to object. Notice that many methods throw exception (by die()) with error message rather than leave it within object.
Store entry %$e (hash) inserting it as a new entry to a database.
Returns an array of ID values for the entry that got stored (array of one element for numeric primary key, multiple for composite key).
Update an existing entry by ID(s) ($ids) in the database with values in hash %$e.
Return true for success, false for failure (direct $ok values from underlying $sth->execute() for 'autoid' => 1 ),
Delete an entry from database by passing one of the following:
Note that passing $filter haphazardly can cause massive destruction. Try to stick with passing $ids.
Test if an entry exists in the DB table with ID values passed in @$ids (array). Returns 1 (entry exists) or 0 (does not exist) under normal conditions.
Load entry from DB table by its IDs passed in @$ids (array, single id typical sequece autoid pkey, multiple for composite primary key).
Entry will be loaded from single table passed at construction (never as result of join from multiple tables). Return entry as a hash (ref).
Load a set of Entries from persistent storage. Optionally provide simple "where filter hash" ($filter), whose key-value criteria is ANDed together to form the filter. Allow attibutes (in $sort, arrayref) to define sorting for entry set. Allow %opts to contain 'attrs' (arrayref) to explicitly to define ettributes to load for each entry. Return set / collection of entries as array of hashes (AoH).
Sample Column names from (current) DB table. Return (ref to) array with field names in it.
%opts may contain KW parameter 'full' to get full DBI column_info() structure (See DBI for details).
Get Count of all or a filtered set of entries (by optional $filter) in table. Return (scalar) count of entries.
These methods you should not need working on the high level. However for the curious they are outlined here.
Return Primary key values (as "real" array, not ref to one) from hash %$e. undef values are produced for non-existing keys. Mostly used for internal operations (and possibly debugging).
Generate SQL WHERE Clause for update() (or delete() or load() or exists()) based on primary keys of current (table) type. Return WHERE clause with id-attribute(s) and placeholder(s) (idkey = ?, ...), without the WHERE keyword. Mostly called for internal operations. You should not need this.