Ruby for Newbies: Working with DataMapper

Ruby is a one of the most popular languages used on the web. We've started a new Session here on Nettuts+ that will introduce you to Ruby, as well as the great frameworks and tools that go along with Ruby development. Today, we'll look at the DataMapper gems to get up and running with a database in Ruby.

Prefer a Video Tutorial?

Step 0: Introducing DataMapper

DataMapper is an ORM: an Object-Relational Mapping. Basically, it’s a library that lets you work with your database from object-oriented code. There’s absolutely no SQL in this tutorial at all. However, an ORM uses a regular database under the covers; we’ll be using sqlite3 today, but you could just use a different adapter to work with a mysql, postgresql or other database.

In Singing with Sinatra - The Recall App, Dan Harper introduced you to DataMapper. In this tutorial, we’re going to take a deeper dive in to working with the library.

Step 1: Installing the Right Gems

The first step is installing the required gems. The DataMapper functionality is broken into many different gems, so you’ll have to install several different parts. Of course, we’re not going to work with it all; but these are the gems you’ll have to install.

sqlite3: This is the database gem.
dm-core: This is the core functionality of DataMapper.
dm-migrations: This gem does the database migration.
dm-validations: As you’ll guess, this offers data validation functionality.
dm-timestamps: Helps with timestamping database records.
dm-sqlite-adapter: This is the adapter that connects DataMapper to your database; we’ll be using sqlite here, but you can use the dm-postgres-adapter, dm-mysql-adapter, or whatever suits your fancy.

Once you’ve got all those gems installed (see the last chapter if you need to know how to install gems), we’re ready to go.

Step 2: Creating a Basic Model

Let’s start by creating a basic model. Models are defined in classes. However, we first have to connect to our database.

Actually, the very first thing is requiring our libraries at the top of our file.

require 'dm-core'
require 'dm-timestamps'
require 'dm-validations'
require 'dm-migration'

So now that we have DataMapper in the environment, let’s connect to the database.

DataMapper.setup :default, "sqlite://#{Dir.pwd}/database.db"

The first parameter tells DataMapper to use the default adapter for the database type. The second is the link / URL for the database. Since we’re using sqlite, we’re just linking to a database file. Note that we don’t have to create this file; DataMapper will create it for us.

Now we’re ready to create the model. As you know, this is a class.

class User
    include DataMapper::Resource
    
    property :id       , Serial
    property :username , String
    property :email    , String
end

The first step is to include the DataMapper::Resource module. This gives you the custom methods you’ll use in your class. The most important method here is property. Here, we’re using it to create three different properties: an id, a username, and an email. As you see, the first parameter in property is a symbol that’s the name of the property. The second is the type. You understand String, of course, but what’s serial. Actually, property :id, Serial is DataMapper’s shorthand for the primary key; ‘serial’ is an auto-incrementing integer. That’s your primary key!

Step 3: Migrating the Database

Now that we’ve created our model, we need to migrate the database. If you’re not familiar with migrating a database, it’s the process of changing the schema of the database. This could be adding a column, renaming a column, or changing properties of a column. DataMapper offers two ways to do this:

DataMapper.auto_migrate!
DataMapper.auto_upgrade!

The difference here is that auto_migrate! will clear all the data from the database; the auto_upgrade! methods tries to reconcile what’s in the database already with the changes you want to make. The way this works is that after your model class, you’ll call one of these methods. You don’t want to be running auto_migrate! every time you load the model, of course, but you might want to run auto_upgrade! on every reload in development. I’ve done it this way in Sinatra:

configure :development do
    DataMapper.auto_upgrade!
end

You’ll notice that so far, we haven’t had to touch a single SQL query; that’s the point of using on ORM is that you can write normal code and have that work with relational databases.

Step 4: Adding some Advanced Attributes

Now that we have our feet wet with DataMapper, let’s take our model to another level. Let’s start with timestamps.

Timestamps

We’re requiring the dm-timestamps gem, so why not use it? If we add ‘created_at’ and ‘updated_at’ properties to the model, this gem will automatically update those fields.

property :created_at, DateTime
property :updated_at, DateTime

Of course, you don’t need to add both, if you don’t want them.

Options

There are several options that you can add to each field. For example, if you want a field to be required, or unique, or have a default value, you can do that there. Let’s create a post model to showcase some of this:

class Post
    include DataMapper::Resource

    property :slug       , String   , key: true, unique_index: true, default: lambda { |resource,prop| resource.title.downcase.gsub " ", "-" }
    property :title      , String   , required: true
    property :body       , Text     , required: true
    property :created_at , DateTime
    property :updated_at , DateTime
end

We’re mixing things up a bit here; our ‘title’ and ‘body’ are required fields. We’re defining the ‘slug’ property as the primary key, and saying that it must be a unique index. Don’t get scared off by the default value of ‘slug.’ Of course, you can just use a raw value of whatever type your property is, but we’re doing something more. Ruby (and other languages) has lambdas, which you could think of as a small function. It’s something that can take “parameters” and return a value, just like a function. If we use a lambda as the value of the ‘default’ property, DataMapper will pass it the resource (or database record you’re working with) and the property itself (in this case, ‘slug’). So here, what we’re doing is taking the value in resource.title (the title property), putting it in lowercase, and using gsub method (think global substitution) to switch every space to a dash. This way, something like this:

"This is a Title"

Will become this:

"this-is-a-title"

Note: Don’t get confused with how we’re using options here. First of all, remember that when a hash is the last parameter of a method, we don’t need to add the curly braces. Also, with Ruby 1.9, there’s a new hash syntax. Previously, hashes looked like this:

{ :key => "value" }

You can still do this in 1.9, and you have to if you you’re not using symbols as your keys. But, if you are using symbols as keys, you can do this instead:

{ key: "value" }

Basically, you just move the colon to the end of the symbol (no space!) and remove the rocket.

Validations

There’s a lot you can do with validation in DataMapper, and you can read all about it here. However, let’s take a look at the basics.

There are two ways to do validations; we’re going to use the method that adds your validations to the options hash. For the email property in the User model, we’ll set the format validation:

property :email, String, format: :email_address

In this case, we’re using a built-in regex that DataMapper offers; we could put a custom regex there if we wanted something else.

Let’s require a certain length on the password:

property :password, String, length: 10..255

If you’re not familiar with the 10..255 notation, that’s a Ruby range. We're saying that the password must be between 10 and 255 characters long.

Associations

How about foreign keys? DataMapper makes this real easy. Let’s associate our User and Post models. We want a user to be able to have many posts, and a post to belong to a user.

In the User model, add this line

has n, :posts

Then, in the Post model, do this:

belongs_to :user

In the database, this adds a user_id property to a post table. In practice, it’s really easy; we’ll see this soon.

Custom Property Accessors

If you want to customize the input for a given property, you can add custom property accessors. For example, let’s say we want to make sure a user’s username is always stored in lowercase. We can add property accessor methods similar to the way you would in a normal class. This way, we take the value the user is trying to store and fix it up. Let’s do this:

def username= new_username
    super new_username.downcase
end

We’re defining the username=, so when the username is assigned, it will be lowercased. The super part just passes our value to this method's super method, which is the one we are overriding.

Note: According to the documentation (see both here and here), we should be able to do @username = new_username.downcase in the method above. This is what I did in the screencast, and as you know, it didn't work as expected. Since recording the screencast I've discovered that the documentation is wrong, and that super is the way to do this.

Step 5: Creating and Finding Records

Well, now that our models are created, let’s add a few records to test them out. We can do this a few ways. First, we can create a record with the new method, passing a hash of attributes, or assigning them individually.

user = User.new username: "JoeSchmo", firstname: "Joe", lastname: "Schmo", email: "[email protected]", password: "password_12345"
user.save

user = User.new
user.username = "Andrew"
# etc.
user.save

When using User#new, you have to call the save method to actually put the record in the database. If there’s an error (remember those validations?), the save method will return false. Then, you can go to the errors property to see the errors; it’s a DataMapper::Validations::ValidationsErrors object, but you can iterate over the errors with the each method.

user.errors.each do |error|
    puts error
end

If you want to make and save a record in one fell swoop, use the create method, of course passing it an attributes hash.

User.create username: "joeschmo", firstname: "Joe", lastname: "Schmo", email: "[email protected]", password: "password_!@#$%"

Boom: created and saved!

How about finding a record in the database? If you know the key of the record you’re looking for, just use the get method:

User.get(1) 

Post.get("this-is-a-title")

Yes, you’re seeing that this works with both normal integer keys and other types of keys. Since we said the slug was the key in the Post model, we can get by slug.

What about those fields that could be the same for multiple records? You’ve got three options for that: first, last, and all. Just pass them a hash, and they get the records for you

User.first firstname: "Andrew"

User.last( :lastname => "Schmo")

User.all  #gets all the post

Conclusion: Learning More

There’s a lot more you can do with DataMapper; check out the documentation for more! Hit the question box if you have any questions.

HIGHLIGHTS OF THE DAY