/ 
Redis-Object-0.1.0
River stage zero No dependents
/ Redis::Object

NAME

Redis::Object - Use Redis with an ORMish interface

DESCRIPTION

Implements a scaled down ORM-like interface to access Redis as a database. If you want to use Redis as a cache, use Redis instead.

SYNOPSIS

package MyRedisDatabase;

use Moose;
extends qw/ Redis::Object /;

has tables => ( isa => 'ArrayRef[Str]', is => 'ro', default => sub { [ qw/
    SomeTable
/ ] } );

__PACKAGE__->make_immutable;

package MyRedisDatabase::SomeTable;

use Moose;
with qw/ Redis::Object::Table /;

has attrib1 => ( isa => 'Str', is => 'rw', default => 'Something' );
has attrib2 => ( isa => 'Int', is => 'rw' );
has attrib3 => ( isa => 'HashRef', is => 'rw' );
has attrib4 => ( isa => 'ArrayRef', is => 'rw' );

sub INDEX_ATTRIBUTES { qw/ attrib1 / }

__PACKAGE__->make_immutable;

package main;

# init database
my $db = MyRedisDatabase->new(
    server => '127.0.0.1:6379'
);

# create item
my $item = $db->create( SomeTable => {
    attrib1 => "Hello",
    attrib2 => 123,
    attrib3 => { something => "serializeable" },
    attrib4 => [ 1..99 ]
} );
print "Created ". $item->id;

# fetch item by id
my $item = $db->find( SomeTable => $id );
print $item->attrib1. "\n";

# search items
my $result = $db->search( SomeTable => {
    attrib1 => "Hello",
    attrib2 => 123
} );
while( my $item = $result->next ) {
    print "Found ". $item->id. "\n";
}

# update item
$item->attrib1( "bla" );
$db->update( $item, {
    attrib2 => 333
} );
$item->update( {
    attrib1 => "Hallo"
} );

# remove an item
$db->remove( $item );
$item->remove;

# clear a table (remvoe all entries!)
$db->truncate( 'SomeTable' );

YOU SHOULD KNOW

Searching / Sorting

Redis is more than a simple key-value store - but it is no relational database, by any means. So limit your expectations towards complex searching or sorting.

This interface implements searching by primary key (an integer ID, which is automatically assigened to each "row" in the database), searching indexed String values with compare- and prefix-search. All search capability aside from this results in a full "table" scan.

Indices

This interface allows you to define certain columes as indexed. Those columes should always be strings - not numbers, nor even more complex data strucutres. Those strings you can search with wildcars, such as "word*" or "w*rd*"

Structure

This interface will store your instances, represented by Redis::Object::Table-objects, in a distinct strucuture. Do not try to use this interface with pre-existing data!

The structure relates to the Moose attributes of your classes. Assuming the following table-class:

package MyDB::MyTable;

use Moose;
with qw/ Redis::Object::Table /;

has somekey => ( isa => "Str", is => "rw", required => 1 );
has otherkey => ( isa => "Int", is => "rw", required => 1 );

sub INDEX_ATTRIBUTES { qw/ somekey / }

The resulting "rows" would look something like this

# contains the an ID timestamp, used for certain lookups
mytable:1:_

# contains the values of both attributres
mytable:1:somekey
mytable:1:otherkey

# indexed key "somekey" for fast lookup
mytable:1:_:somekey:The_Value

There is also a special key/value per table, which contains an incrementing integer for the primary key

mytable:_id

SUBTYPES

StrIndexed

Indexed String type

has attrib => ( isa => "StrIndexed", is => "rw", required => 1 );

StrIndexedSafe

Indexed String type, with constraints to assure/increase proability that it will not create errors with Redis (StrIndexed is more loose, and you can save any value)

has attrib => ( isa => "StrIndexed", is => "rw", required => 1 );

ATTRIBUTES

server

Defaults to 127.0.0.1:6379

tables

Array of table names

prefix

Optional prefix for all key names in Redis

METHODS

new %args

%args

  • server

    The Redis server and port, defaults to '127.0.0.1:6379'

  • tables

    Arrayref of table names. A table has to be implemented as a perl module with the same name.

create $table_name, $create_ref

Create new item

$table_name

The name of the table

$create_ref

The attributes of the object to be created

update $item, [$update_ref]

Update existing item into database

find $table_name, $item_id

Finds a single item by id

$table_name

Name of the table

$item_id

ID of the item

search $table_name, $filter, [$args_ref]

Search multiple items by attribute filter.

You can

$table_name

Name of the table

$filter

The search condition can have multiple shapes:

SubRef

A ref to a grep-like sub. Example:

my $sub_filter = sub {
    my ( $item ) = @_;
    
    # add item to list
    return 1
        if ( $item->attribute eq "something" );
    
    # drop item
    return 0;
};

HashRef

A subset of keys and value constraints, Example:

# this is an AND-filter: all constraints have to fit
my $filter_ref = {
    
    # simple string matching
    attribute1 => 'something',
    
    # string matches one
    attribute1 => 'something',
    
    # regex filter
    attribute2 => qr/^123/,
    
    # custom filter
    attribute3 => sub {
        my ( $value) = @_;
        return $value =~ /^xx/ && length( $value ) > 99;
    }
}

$args_ref

  • or_search

    Perform an or-search instead (default: and-search)

Example

my $result = $db->search( TableName => {
    attrib => "bla"
} );
while( my $item = $result->next ) {
    # ..
}

remove $search_or_item

Remove a single or multiple items

Single usage

$db->remove( $item );

Multie usage

$db->remove( $table => $search_ref );

truncate

Empties a whole table. ID will be reset. Use with caution.

count

Returns amount of entries in a tbale

AUTHOR

Ulrich Kautz <uk@fortrabbit.de>

COPYRIGHT

Copyright (c) 2011 the "AUTHOR" as listed above

LICENCSE

Same license as Perl itself.