• Stars
    star
    1,390
  • Rank 33,811 (Top 0.7 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 15 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Object-Hash Mapping for Redis

Ohm ΰ₯

Object-hash mapping library for Redis.

Description

Ohm is a library for storing objects in Redis, a persistent key-value database. It has very good performance.

Community

Join the mailing list: http://groups.google.com/group/ohm-ruby

Meet us on IRC: #ohm on freenode.net

Related projects

These are libraries in other languages that were inspired by Ohm.

  • Ohm for Crystal, created by soveran
  • JOhm for Java, created by xetorthio
  • Lohm for Lua, created by slact
  • ohm.lua for Lua, created by amakawa
  • Nohm for Node.js, created by maritz
  • Redisco for Python, created by iamteem
  • redis3m for C++, created by luca3m
  • Ohmoc for Objective-C, created by seppo0010
  • Sohm for Lua, compatible with Twemproxy

Articles and Presentations

Getting started

Install Redis. On most platforms it's as easy as grabbing the sources, running make and then putting the redis-server binary in the PATH.

Once you have it installed, you can execute redis-server and it will run on localhost:6379 by default. Check the redis.conf file that comes with the sources if you want to change some settings.

If you don't have Ohm, try this:

$ [sudo] gem install ohm

Or you can grab the code from http://github.com/soveran/ohm.

Now, in an irb session you can test the Redis adapter directly:

>> require "ohm"
=> true
>> Ohm.redis.call "SET", "Foo", "Bar"
=> "OK"
>> Ohm.redis.call "GET", "Foo"
=> "Bar"

Connecting to a Redis database

Ohm uses a lightweight Redis client called Redic. To connect to a Redis database, you will need to set an instance of Redic, with an URL of the form redis://:<passwd>@<host>:<port>/<db>, through the Ohm.redis= method, e.g.

require "ohm"

Ohm.redis = Redic.new("redis://127.0.0.1:6379")

Ohm.redis.call "SET", "Foo", "Bar"

Ohm.redis.call "GET", "Foo"
# => "Bar"

Ohm defaults to a Redic connection to "redis://127.0.0.1:6379". The example above could be rewritten as:

require "ohm"

Ohm.redis.call "SET", "Foo", "Bar"

Ohm.redis.call "GET", "Foo"
# => "Bar"

All Ohm models inherit the same connection settings from Ohm.redis. For cases where certain models need to connect to different databases, they simple have to override that, i.e.

require "ohm"

Ohm.redis = Redic.new(ENV["REDIS_URL1"])

class User < Ohm::Model
end

User.redis = Redic.new(ENV["REDIS_URL2"])

Models

Ohm's purpose in life is to map objects to a key value datastore. It doesn't need migrations or external schema definitions. Take a look at the example below:

Example

class Event < Ohm::Model
  attribute :name
  reference :venue, :Venue
  set :participants, :Person
  counter :votes

  index :name
end

class Venue < Ohm::Model
  attribute :name
  collection :events, :Event
end

class Person < Ohm::Model
  attribute :name
end

All models have the id attribute built in, you don't need to declare it.

This is how you interact with IDs:

event = Event.create :name => "Ohm Worldwide Conference 2031"
event.id
# => 1

# Find an event by id
event == Event[1]
# => true

# Update an event
event.update :name => "Ohm Worldwide Conference 2032"
# => #<Event:0x007fb4c35e2458 @attributes={:name=>"Ohm Worldwide Conference"}, @_memo={}, @id="1">

# Trying to find a non existent event
Event[2]
# => nil

# Finding all the events
Event.all.to_a
# => [<Event:1 name='Ohm Worldwide Conference 2032'>]

This example shows some basic features, like attribute declarations and querying. Keep reading to find out what you can do with models.

Attribute types

Ohm::Model provides 4 attribute types:

  • Ohm::Model.attribute,
  • Ohm::Model.set
  • Ohm::Model.list
  • Ohm::Model.counter

and 2 meta types:

  • Ohm::Model.reference
  • Ohm::Model.collection.

attribute

An attribute is just any value that can be stored as a string. In the example above, we used this field to store the event's name. You can use it to store numbers, but be aware that Redis will return a string when you retrieve the value.

set

A set in Redis is an unordered list, with an external behavior similar to that of Ruby arrays, but optimized for faster membership lookups. It's used internally by Ohm to keep track of the instances of each model and for generating and maintaining indexes.

list

A list is like an array in Ruby. It's perfectly suited for queues and for keeping elements in order.

counter

A counter is like a regular attribute, but the direct manipulation of the value is not allowed. You can retrieve, increase or decrease the value, but you can not assign it. In the example above, we used a counter attribute for tracking votes. As the increment and decrement operations are atomic, you can rest assured a vote won't be counted twice.

reference

It's a special kind of attribute that references another model. Internally, Ohm will keep a pointer to the model (its ID), but you get accessors that give you real instances. You can think of it as the model containing the foreign key to another model.

collection

Provides an accessor to search for all models that reference the current model.

Tracked keys

Besides the provided attribute types, it is possible to instruct Ohm to track arbitrary keys and tie them to the object's lifecycle.

For example:

class Log < Ohm::Model
  track :text
  
  def append(msg)
    redis.call("APPEND", key[:text], msg)
  end
  
  def tail(n = 100)
    redis.call("GETRANGE", key[:text], -(n), -1)
  end
end

log = Log.create
log.append("hello\n")

assert_equal "hello\n", log.tail

log.append("world\n")

assert_equal "world\n", log.tail(6)

When the log object is deleted, the :text key will be deleted too. Note that the key is scoped to that particular instance of Log, so if log.id is 42 then the key will be Log:42:text.

Persistence strategy

The attributes declared with attribute are only persisted after calling save.

Operations on attributes of type list, set and counter are possible only after the object is created (when it has an assigned id). Any operation on these kinds of attributes is performed immediately. This design yields better performance than buffering the operations and waiting for a call to save.

For most use cases, this pattern doesn't represent a problem. If you are saving the object, this will suffice:

if event.save
  event.comments.add(Comment.create(body: "Wonderful event!"))
end

Working with Sets

Given the following model declaration:

class Event < Ohm::Model
  attribute :name
  set :attendees, :Person
end

You can add instances of Person to the set of attendees with the add method:

event.attendees.add(Person.create(name: "Albert"))

# And now...
event.attendees.each do |person|
  # ...do what you want with this person.
end

Sorting

Since attendees is a Ohm::Model::Set, it exposes two sorting methods: Ohm::Model::Collection#sort returns the elements ordered by id, and Ohm::Model::Collection#sort_by receives a parameter with an attribute name, which will determine the sorting order. Both methods receive an options hash which is explained below:

:order

Order direction and strategy. You can pass in any of the following:

  1. ASC
  2. ASC ALPHA (or ALPHA ASC)
  3. DESC
  4. DESC ALPHA (or ALPHA DESC)

It defaults to ASC.

Important Note: Starting with Redis 2.6, ASC and DESC only work with integers or floating point data types. If you need to sort by an alphanumeric field, add the ALPHA keyword.

:limit

The offset and limit from which we should start with. Note that this is 0-indexed. It defaults to 0.

Example:

limit: [0, 10] will get the first 10 entries starting from offset 0.

:by

Key or Hash key with which to sort by. An important distinction with using Ohm::Model::Collection#sort and Ohm::Model::Collection#sort_by is that sort_by automatically converts the passed argument with the assumption that it is a hash key and it's within the current model you are sorting.

Post.all.sort_by(:title)     # SORT Post:all BY Post:*->title
Post.all.sort(by: :title) # SORT Post:all BY title

Tip: Unless you absolutely know what you're doing, use sort when you want to sort your models by their id, and use sort_by otherwise.

:get

A key pattern to return, e.g. Post:*->title. As is the case with the :by option, using Ohm::Model::Collection#sort and Ohm::Model::Collection#sort_by has distinct differences in that sort_by does much of the hand-coding for you.

Post.all.sort_by(:title, get: :title)
# SORT Post:all BY Post:*->title GET Post:*->title

Post.all.sort(by: :title, get: :title)
# SORT Post:all BY title GET title

Associations

Ohm lets you declare references and collections to represent associations.

class Post < Ohm::Model
  attribute :title
  attribute :body
  collection :comments, :Comment
end

class Comment < Ohm::Model
  attribute :body
  reference :post, :Post
end

After this, every time you refer to post.comments you will be talking about instances of the model Comment. If you want to get a list of IDs you can use post.comments.ids.

References explained

Doing a Ohm::Model.reference is actually just a shortcut for the following:

# Redefining our model above
class Comment < Ohm::Model
  attribute :body
  attribute :post_id
  index :post_id

  def post=(post)
    self.post_id = post.id
  end

  def post
    Post[post_id]
  end
end

The only difference with the actual implementation is that the model is memoized.

The net effect here is we can conveniently set and retrieve Post objects, and also search comments using the post_id index.

Comment.find(post_id: 1)

Collections explained

The reason a Ohm::Model.reference and a Ohm::Model.collection go hand in hand, is that a collection is just a macro that defines a finder for you, and we know that to find a model by a field requires an Ohm::Model.index to be defined for the field you want to search.

# Redefining our post above
class Post < Ohm::Model
  attribute :title
  attribute :body

  def comments
    Comment.find(post_id: self.id)
  end
end

The only "magic" happening is with the inference of the index that was used in the other model. The following all produce the same effect:

# easiest, with the basic assumption that the index is `:post_id`
collection :comments, :Comment

# we can explicitly declare this as follows too:
collection :comments, :Comment, :post

# finally, we can use the default argument for the third parameter which
# is `to_reference`.
collection :comments, :Comment, to_reference

# exploring `to_reference` reveals a very interesting and simple concept:
Post.to_reference == :post
# => true

Modules

If your models are defined inside a module, you will have to define the references and collections as in the following example:

module SomeNamespace
  class Foo < Ohm::Model
    attribute :name
  end
  
  class Bar < Ohm::Model
    reference :foo, 'SomeNamespace::Foo'
  end
end

Indices

An Ohm::Model.index is a set that's handled automatically by Ohm. For any index declared, Ohm maintains different sets of objects IDs for quick lookups.

In the Event example, the index on the name attribute will allow for searches like Event.find(name: "some value").

Note that the methods Ohm::Model::Set#find and Ohm::Model::Set#except need a corresponding index in order to work.

Finding records

You can find a collection of records with the find method:

# This returns a collection of users with the username "Albert"
User.find(username: "Albert")

Filtering results

# Find all users from Argentina
User.find(country: "Argentina")

# Find all active users from Argentina
User.find(country: "Argentina", status: "active")

# Find all active users from Argentina and Uruguay
User.find(status: "active").combine(country: ["Argentina", "Uruguay"])

# Find all users from Argentina, except those with a suspended account.
User.find(country: "Argentina").except(status: "suspended")

# Find all users both from Argentina and Uruguay
User.find(country: "Argentina").union(country: "Uruguay")

Note that calling these methods results in new sets being created on the fly. This is important so that you can perform further operations before reading the items to the client.

For more information, see SINTERSTORE, SDIFFSTORE and SUNIONSTORE

Uniques

Uniques are similar to indices except that there can only be one record per entry. The canonical example of course would be the email of your user, e.g.

class User < Ohm::Model
  attribute :email
  unique :email
end

u = User.create(email: "[email protected]")
u == User.with(:email, "[email protected]")
# => true

User.create(email: "[email protected]")
# => raises Ohm::UniqueIndexViolation

Ohm Extensions

Ohm is rather small and can be extended in many ways.

A lot of amazing contributions are available at Ohm Contrib make sure to check them if you need to extend Ohm's functionality.

Upgrading

Ohm 2 breaks the compatibility with previous versions. If you're upgrading an existing application, it's nice to have a good test coverage before going in. To know about fixes and changes, please refer to the CHANGELOG file.

More Repositories

1

cuba

Rum based microframework for web development.
Ruby
1,438
star
2

micromachine

Minimal Finite State Machine
Ruby
522
star
3

clac

Command-line, stack-based calculator with postfix notation
C
350
star
4

map

Map lines from stdin to commands
C
221
star
5

mote

Minimum Operational Template
Ruby
217
star
6

nest

Generate nested namespaced keys for key-value databases.
Ruby
185
star
7

ost

Redis based queues and workers.
Ruby
166
star
8

toro

Tree oriented routing
Crystal
144
star
9

syro

Simple router for web applications
Ruby
135
star
10

cargo

Require libraries without cluttering your namespace.
Ruby
127
star
11

scrivener

Validation frontend for models.
Ruby
124
star
12

clap

Command line argument parsing
Ruby
90
star
13

ohm-crystal

Ohm for Crystal
Crystal
71
star
14

disque-rb

Disque client for Ruby
Ruby
68
star
15

gs

Gemset management
Ruby
67
star
16

totp

Time-based One-Time Passwords
Ruby
44
star
17

mailcat

Fake SMTP server that prints emails to stdout
C
38
star
18

chen

Change directory entries with your text editor
C
37
star
19

spawn

A ridiculously simple fixtures replacement for your web framework of choice.
Ruby
36
star
20

finist

Redis based Finite State Machine
Ruby
36
star
21

redisurl

Connect to Redis using a REDIS_URL and the redigo client.
Go
33
star
22

hart

Hash router
Ruby
24
star
23

stal-ruby

Set algebra solver for Redis
Ruby
22
star
24

redisent

Sentinels aware Redis client.
Ruby
22
star
25

relay

Relay commands over SSH
Ruby
21
star
26

resp

Lightweight RESP client for Lua
Lua
21
star
27

lomo

Apply a lomo filter to your pictures from the command line using ImageMagick.
Ruby
19
star
28

terco

Obstinate DNS
Ruby
16
star
29

override

The as-simple-as-possible-but-not-simpler stubbing library.
Ruby
16
star
30

ox

Skeleton for a Cuba-based JSON API.
Ruby
16
star
31

nido

Structured keys helper
Ruby
14
star
32

syro-demo

Demo application with Syro
Ruby
14
star
33

resp-crystal

Lightweight RESP client
Crystal
14
star
34

mt

Mail tester daemon.
Ruby
13
star
35

stringent

Generate a string with a target entropy
Ruby
12
star
36

rediscan

Scanner for Redis keyspace
Ruby
12
star
37

hypertext

Hypertext authoring with Ruby
Ruby
11
star
38

filmo

A single page presentation tool.
11
star
39

cuba-book

Cuba Book
11
star
40

sc

List of HTTP status codes.
Ruby
11
star
41

finist.lua

Redis based Finite State Machine
Lua
10
star
42

drawer

Ultra slim file-based cache
Ruby
10
star
43

nest-crystal

Object Oriented Keys for Redis
Crystal
9
star
44

basica

Basic authentication library.
Ruby
8
star
45

rino

Remove a file by its inode number
C
7
star
46

seg.rb

Segment matcher for paths
Ruby
7
star
47

seg

Segment matcher for paths
Crystal
7
star
48

trim

Read from stdin and remove a prefix from each line
C
7
star
49

tas

Trees as strings
Ruby
6
star
50

stal

Set algebra solver for Redis
Lua
6
star
51

pac

Package management for Lua libraries.
Shell
6
star
52

prep

Read from stdin and prepend a string to each line while preserving identation.
C
6
star
53

m4s2

Static Site Generator
HTML
5
star
54

contract

Contract helper
Ruby
5
star
55

stal-crystal

Set algebra solver for Redis
Crystal
5
star
56

loco

Lines of code counter
C
4
star
57

ook

Object Oriented Keys for Redis
Ruby
4
star
58

walk

Walk a directory tree and print the name of every regular file
C
4
star
59

rel

Ruby client for the Bandicoot database.
Ruby
4
star
60

textorama

Text slides for the terminal
Shell
4
star
61

homebrew-tools

Formulae for Homebrew
Ruby
4
star
62

rediscan.lua

Scanner for Redis keyspace in Lua
Lua
3
star
63

seg.go

Segment matcher for paths
Go
3
star
64

look

Add a vendor directory to your load path.
Ruby
3
star
65

app

Cuba application template for gn, the file generator.
Ruby
2
star
66

packer

Require different versions of the same Cargo-compatible gem
Ruby
2
star
67

tele.sh

2
star
68

ers

AWK script easy replacements in templates
Awk
2
star
69

soveran.github.io

2
star
70

filter

Workflow template for gn.
Ruby
1
star
71

remoto

Ruby
1
star
72

gem

Gem template for gn, the file generator.
Ruby
1
star
73

ohm-scripts

Lua scripts for Ohm compatible libraries
Lua
1
star
74

ostgo

Ost client.
Go
1
star
75

miga

Breadcrumb name of the working directory
C
1
star