:include:QUICKLINKS

Properties

Properties for a model are not derived from a database structure, but instead explicitly declared inside your model class definitions. These properties then map (or, if using automigrate, generate) fields in your repository/database.

If you are coming to DataMapper from another ORM framework, such as ActiveRecord, this is a fundamental difference in thinking. However, there are several advantages to defining your properties in your models:

• information about your model is centralized in one place: rather than having to dig out migrations, xml or other configuration files.
• having information centralized in your models, encourages you and the developers on your team to take a model-centric view of development.
• it provides the ability to use Ruby’s access control functions.
• and, because DataMapper only cares about properties explicitly defined in your models, DataMapper plays well with legacy databases, and shares databases easily with other applications.

Declaring Properties

Inside your class, you call the property method for each property you want to add. The only two required arguments are the name and type, everything else is optional.

  class Post
    include DataMapper::Resource
    property :title,   String,    :nullable => false

    property :publish, TrueClass, :default => false

  end

By default, DataMapper supports the following primitive types:

• TrueClass, Boolean
• String
• Text (limit of 65k characters by default)
• Float
• Integer
• BigDecimal
• DateTime
• Date
• Time
• Object (marshalled out during serialization)
• Class (datastore primitive is the same as String. Used for Inheritance)

For more information about available Types, see DataMapper::Type

Limiting Access

Property access control is uses the same terminology Ruby does. Properties are public by default, but can also be declared private or protected as needed (via the :accessor option).

 class Post
  include DataMapper::Resource
   property :title,  String,                  :accessor => :private

   property :body,   Text, :accessor => :protected

 end

Access control is also analogous to Ruby accessors and mutators, and can be declared using :reader and :writer, in addition to :accessor.

 class Post
   include DataMapper::Resource

   property :title, String, :writer => :private

   property :tags,  String, :reader => :protected

 end

Overriding Accessors

The accessor for any property can be overridden in the same manner that Ruby class accessors can be. After the property is defined, just add your custom accessor:

 class Post
   include DataMapper::Resource
   property :title,  String

   def title=(new_title)
     raise ArgumentError if new_title != 'Luke is Awesome'
     @title = new_title
   end
 end

Lazy Loading

By default, some properties are not loaded when an object is fetched in DataMapper. These lazily loaded properties are fetched on demand when their accessor is called for the first time (as it is often unnecessary to instantiate -every- property -every- time an object is loaded). For instance, DataMapper::Types::Text fields are lazy loading by default, although you can over-ride this behavior if you wish:

Example:

 class Post
   include DataMapper::Resource
   property :title,  String                    # Loads normally
   property :body,   DataMapper::Types::Text   # Is lazily loaded by default
 end

If you want to over-ride the lazy loading on any field you can set it to a context or false to disable it with the :lazy option. Contexts allow multipule lazy properties to be loaded at one time. If you set :lazy to true, it is placed in the :default context

 class Post
   include DataMapper::Resource

   property :title,    String

   property :body,     DataMapper::Types::Text, :lazy => false

   property :comment,  String, lazy => [:detailed]

   property :author,   String, lazy => [:summary,:detailed]

 end

Delaying the request for lazy-loaded attributes even applies to objects accessed through associations. In a sense, DataMapper anticipates that you will likely be iterating over objects in associations and rolls all of the load commands for lazy-loaded properties into one request from the database.

Example:

  Widget[1].components

  Widget[1].components.first.body

  Widget[1].components.first.comment

Keys

Properties can be declared as primary or natural keys on a table. You should a property as the primary key of the table:

Examples:

 property :id,        Integer, :serial => true  # auto-incrementing key
 property :legacy_pk, String, :key => true      # 'natural' key

This is roughly equivalent to ActiveRecord’s set_primary_key, though non-integer data types may be used, thus DataMapper supports natural keys. When a property is declared as a natural key, accessing the object using the indexer syntax Class[key] remains valid.

  User[1]

  User['bill']

Indeces

You can add indeces for your properties by using the :index option. If you use true as the option value, the index will be automatically named. If you want to name the index yourself, use a symbol as the value.

  property :last_name,  String, :index => true
  property :first_name, String, :index => :name

You can create multi-column composite indeces by using the same symbol in all the columns belonging to the index. The columns will appear in the index in the order they are declared.

  property :last_name,  String, :index => :name
  property :first_name, String, :index => :name

If you want to make the indeces unique, use :unique_index instead of :index

Inferred Validations

If you require the dm-validations plugin, auto-validations will automatically be mixed-in in to your model classes: validation rules that are inferred when properties are declared with specific column restrictions.

 class Post
   include DataMapper::Resource

   property :title, String, :length => 250

            :minimum => 0, :maximum => 250'

   property :title, String, :nullable => false

   property :email, String, :format => :email_address

   property :title, String, :length => 255, :nullable => false

 end

This functionality is available with the dm-validations gem, part of the dm-more bundle. For more information about validations, check the documentation for dm-validations.

Embedded Values

As an alternative to extraneous has_one relationships, consider using an EmbeddedValue.

Misc. Notes

• Properties declared as strings will default to a length of 50, rather than 255 (typical max varchar column size). To overload the default, pass :length => 255 or :length => 0..255. Since DataMapper does not introspect for properties, this means that legacy database tables may need their String columns defined with a :length so that DM does not apply an un-needed length validation, or allow overflow.
• You may declare a Property with the data-type of Class. see SingleTableInheritance for more on how to use Class columns.