1. Computing

A Quick Introduction to DataMapper

A Quick Introduction to DataMapper

By

DataMapper is a "Object/Relational Mapper" or ORM. In other words, it maps Ruby objects to database records that makes with objects from a database a snap. If this sounds familiar then you may be thinking of ActiveRecord, the ORM library used in Ruby on Rails. If you're familiar with ActiveRecord already, picking up DataMapper will be quite easy.

Installing DataMapper

Installing DataMapper is not quite so easy. First, DataMapper is modular, and is broken up into many smaller gems. The most important of these is dm-core, the core of the DataMapper library. This is a pure-Ruby gem with no external dependencies, so installing this is the same as installing any other gem.

$ sudo gem install dm-core

But dm-core by itself isn't very useful. To actually use DataMapper, you need a DataObject, the piece that will tell DataMapper how to talk to the database. To do this, you'll need to install a gem with native code. This means you'll need both GCC and the development libraries installed for whatever database you're going to be using. In this article, we use the SQLite 3 driver. To get ready for this, you'll need to install the libsqlite3-dev package (or equivalent) on your OS. After that, install the do_sqlite3 gem.

$ sudo apt-get install libsqlite3-dev
$ sudo gem install dm-sqlite-adapter

If all went well then you're ready to proceed. If you prefer another database (SQLite is great, but it doesn't always cut it), there are also drivers for MySQL and Postgres, among others.

Setting Up

To begin using DataMapper, you must require the dm-core gem and connect to a database using the DataMapper.setup method. The setup method takes a string in URL format describing the database to open. Here, the "protocol" is the DataObject to use (in our case, sqlite3). The rest of the URL is the path to the database file. Note that this is the full path, not the relative path to the database file.

#!/usr/bin/env ruby
require 'rubygems'
require 'dm-core'
require 'dm-migrations'

# Open the database test1.db
DataMapper.setup( :default, "sqlite3://#{Dir.pwd}/test1.db" )

Defining Models

Now that you're set up, you can jump right in and define some models. This is one area that DataMapper really differs from ActiveRecord. You don't define models in ActiveRecord, you simply define the class and it picks up the fields from the database. The only place you "define" models in ActiveRecord is in migrations. However, this model you're defining for DataMapper is both the model definition and the migration.

This sample model will store a database about people. Fields are first name, last name and email. Note that all models must have at least one key. The key is used for fast searching and, among other things, must be unique. If no suitable field exists for a key, add an id field of the type Serial. It will automatically be a key, and will generate unique IDs for each row in the database.

Also, after creating your models you can call DataMapper.auto_migrate!. This is a simple migration method that will create any tables necessary and, if the table already exists, add or remove any columns needed. This is quite destructive though, one wrong move and it could wipe out all of your data. DataMapper does have more sophisticated migrations, but they're not covered in this article.

# Define the Person model
class Person
  include DataMapper::Resource

  property :firstname, String
  property :lastname, String
  property :email, String, :key => true
end

# Automatically create the tables if they don't exist
DataMapper.auto_migrate!

Working With Objects

Now that you have a database connection established and a model defined, you can start creating, reading, updating and destroying records from the database. The following shows a few examples of how to do a variety of actions with DataMapper.

# Create a new record
p = Person.new
p.attributes = {
  :firstname => 'John',
  :lastname => 'Doe',
  :email => 'john.doe@email.com'
}

# Save it to the database
p.save

# Make some changes to the object
p.lastname = 'Smith'
p.save

# Create a new object and destroy it
p2 = Person.new
p2.email = 'testing@testing.com'
p2.save

p2.destroy

# Find a record from the database
p3 = Person.get('john.doe@email.com')
puts p3.inspect

There is, of course, a lot more to DataMapper. It can be used just fine in this simplistic way, or in more sophisticated ways. For more information, refer to the DataMapper documentation.

  1. About.com
  2. Computing
  3. Ruby
  4. Tutorials
  5. Sinatra
  6. A Quick Introduction to DataMapper

©2014 About.com. All rights reserved.