Datamapper.org News and Notes

DataMapper 1.2.0 released

2011-10-13T00:00:00-07:00

DataMapper 1.2.0 released

I'm pleased to announce that we have released DataMapper 1.2.0.

This release is focused on bug fixes, performance improvements, internal refactoring and Rails 3.1 compatibility. Please give it a try and in case of any issues please report them on Github.

Installation

DataMapper can be installed with a one-line command:

$ gem install data_mapper dm-sqlite-adapter

The above command assumes you are using SQLite, but if you plan to use MySQL, PostgreSQL or something else replace dm-sqlite-adapter your preferred adapter gem.

IMPORTANT:

If you're not using Rails then remember to call DataMapper.finalize after loading the models!

Changes

dm-core:

STI queries no longer include the top-level class name
UnderscoredAndPluralizedWithoutLeadingModule naming convention was added
belongs_to supports :unique option
Validation of property names was improved
Resource[] and Resource[]= no longer fail when property name is not known
Redundant usage of chainable was removed resulting in a better performance
Boolean property typecasting was refactored
Various issues with setting default Property options were fixed
Resource#attributes= no longer use public_method_defined? - this is a security fix preventing possible DDOS attacks
Problems with auto-migrations in multiple repositories were fixed
Encoding problems with Binary property are fixed

dm-adjust:

Support for InMemoryAdapter
Add COALESCE to default NULL columns to 0
Fixed a bug with loading dm-adjust after the dm-do-adapter

dm-constraints:

Total rewrite
Fixed for Oracle

dm-do-adapter:

Warning from DO is gone now

dm-migrations:

alter table is fixed for postgres
Property options (such as :length) are now correctly used in migrations
Support to specify table options when creating a table was added (for things like db engines in mysql etc.)
Fix bug related to migrating custom types derived from builtin types

dm-rails:

Support for Rails 3.1.0
Storage create/drop tasks are by default noops in case an adapter doesn't support it
Support for field_naming_convention option
Support for resource_naming_convention option
You can now set a custom repository scope for the repository in the IdentityMap middleware

dm-serializer:

Should work with psych

dm-types:

Support for Resource#dirty? upon indirect property mutation was added (this is huge, more info here: https://github.com/datamapper/dm-types/commit/3d96b1cd2b270a3843877a5...)
Issues with Paranoid properties and STI were fixed
JSON property uses multi_json now

dm-validations:

valid? is always called even if a resource is not dirty
Issues with JRuby and unicode were fixed
Massive internal clean-up towards future rewrite that will make validations even more awesome

dm-oracle-adapter:

Many bug fixes
Important: on MRI it requires ruby-oci8 gem (it's not specified in the gemspec, you need to add it to your gemfiles)

DataMapper 1.1.0 released

2011-03-17T00:00:00-07:00

DataMapper 1.1.0 released

I'm pleased to announce that we have released DataMapper 1.1.

This has been one of the most enjoyable releases in recent memory. The community rallied together and compared to the previous release we had at least 3-4x more people submitting patches and working together to get this release ready.

DataMapper 1.1 brings several minor API changes, warranting the minor version bump, and closes 52 tickets in Lighthouse. There have been many performance improvements, some closing bottlenecks that result in as much as a 20x speedup from the 1.0.2 behaviour.

As part of the bug fixing process we've refactored some of the objects we use internally to group relationships and dependencies and removed methods and classes that were deprecated in 1.0.

Installation

DataMapper can be installed with a one-line command:

$ gem install datamapper dm-sqlite-adapter --no-ri --no-rdoc

The above command assumes you are using SQLite, but if you plan to use MySQL, PostgreSQL or something else replace dm-sqlite-adapter your preferred adapter gem.

Changes

Here's a full list of the tickets we've resolved for 1.1.

Highlights:

ActiveSupport / Extlib dependency is removed. If your code relies on one of these libs then just add a dependency on your own.
DataMapper::Type is gone now in favour of DataMapper::Property. The Type API was deprecated in 1.0 but if you still have some Types floating around read how to upgrade them in this thread.
RelationshipSet and PropertySet are now subclasses of a new SubjectSet class. Please be aware that previously RelationshipSet and PropertySet inherited from Hash and Array, respectively.
The property class finder is now improved and it is possible to declare properties that aren't defined in DataMapper::Property namespace without providing the full const path. For instance you can have YourApp::Properties::FooBar and you can declare it as property :foo_bar, FooBar. There's a convention that if your property class has the same name as one of the other properties from DataMapper::Property namespace then you have to provide the full const path, otherwise your property won't be found.

Removed deprecated methods:

DataMapper::Collection#add (replaced by #<<)
DataMapper::Collection#build (replaced by #new)
DataMapper::IdentityMap#get (replaced by #[])
DataMapper::IdentityMap#set (replaced by #[]=)
DataMapper::PropertySet#has_property? (replaced by #named?)
DataMapper::PropertySet#slice (replaced by #values_at)
DataMapper::PropertySet#add (replaced by #<<)
DataMapper::Query::Conditions::Comparison#property (replaced by #subject)
DataMapper::Query::Direction#property (replaced by #subject)
DataMapper::Query::Direction#direction (replaced by #operator)
DataMapper::Property#unique (replaced by #unique?)
DataMapper::Property#nullable? (replaced by #allow_nil?)
DataMapper::Property#value (replaced by #dump)
DataMapper::Resource#new_record? (replaced by #new?)

How to report issues

Please report any issues you find in IRC, on the mailing list, or in the bug tracker:

DataMapper 1.0.2 released

2010-09-07T00:00:00-07:00

DataMapper 1.0.2 released

I'm pleased to announce that we released DataMapper 1.0.2 this afternoon.

This fixes a few small bugs discovered since the 1.0.0 release.

Earlier today I shipped 1.0.1, but there were some bugs discovered in the docs that caused rdoc and YARD to output some really nasty looking warnings. Rather than just telling people to ignore them, I decided to work-around the problems as much as I could. Even still, I'm going to recommend that you use --no-ri --no-rdoc to install the gems because some of the errors are inside YARD and rdoc themselves, and the authors need time to fix the bugs that I can't work around.

Installation

Install dm-core:

$ gem install dm-core --no-ri --no-rdoc

The next thing you want to do is decide which adapter you want to use. For example if you want to use sqlite, do:

$ gem install dm-sqlite-adapter --no-ri --no-rdoc

It's likely you'll want to use migrations (for classic or auto-migrations), and transactions when using sqlite, so to install them do:

$ gem install dm-migrations dm-transactions --no-ri --no-rdoc

There is also a metagem which combines several gems into a single package:

$ gem install data_mapper --no-ri --no-rdoc

This pulls a nice base stack for DM development. The gems included are:

dm-core
dm-aggregates
dm-constraints
dm-migrations
dm-transactions
dm-serializer
dm-timestamps
dm-validations
dm-types

So putting this all together you can do:

$ gem install data_mapper dm-sqlite-adapter --no-ri --no-rdoc

Changes

Here's a list of the tickets we've resolved since 1.0.0:

http://datamapper.lighthouseapp.com/projects/20609/milestones/75769

How to report issues

Please report any issues you find in IRC, on the mailing list, or in the bug tracker:

DataMapper 1.0 released

2010-06-12T00:00:00-07:00

DataMapper 1.0 released

DataMapper 1.0 (Vermouth) was released earlier this week, coinciding with Dirkjan Bussink's presentation at Railsconf 2010 (his slides are posted as well).

The transition from the 0.10.x series to 1.0 does involve several changes regarding how users will interact with DataMapper. Unfortunately we have no had time to update all of our documentation on the site, so please bear with us while we get everything in order. Read on for further details regarding these changes, and users are always welcome in #datamapper on irc.freenode.net and we strive to any answer questions promptly.

Thank you to everyone in the community, especially this mailing list and the IRC channel. There's no way we could've reached this milestone without your encouragement and assistance. It's extremely rewarding to see DM hit 1.0, but at the same time it also sets a baseline for future development to build on. In some ways we're only just getting started, the future we have planned for DM is even more ambitious.

Before you install

The installation process for DM 1.0 is pretty similar to what it was previously in 0.10.x and 0.9.x with a few exceptions:

Using auto-migration and auto-upgrading require dm-migrations rather than just dm-core. The reason for this is that dm-migrations should share a lot of code with auto-migrations, but they don’t, and in an attempt to DRY things up we’ve centralized all the code in one package and will begin refactoring the code over the coming months.
Transactions require the use of the dm-transactions gem.
It is no longer necessary to gem install data_objects or any do_* gem directly. Each DO based adapter has been extracted into their own gems, and installing them will setup the dependencies on dm-core and the appropriate DO gem(s). The new adapters are:
dm-sqlite-adapter
dm-postgres-adaper
dm-mysql-adapter
dm-oracle-adapter
dm-sqlserver-adapter

Installation

Install dm-core:

$ gem install dm-core

The next thing you want to do is decide which adapter you want to use. For example if you want to use sqlite, do:

$ gem install dm-sqlite-adapter

This should pull in data_objects and do_sqlite3 automatically, so no need to specify either of those explicitly anymore. It’s likely you’ll want to use migrations (for classic or auto-migrations), and transactions when using sqlite, so to install them do:

$ gem install dm-migrations dm-transactions

There is also a metagem which combines several gems into a single package:

$ gem install data_mapper

This pulls a nice base stack for DM development. The gems included are:

dm-core
dm-aggregates
dm-constraints
dm-migrations
dm-transactions
dm-serializer
dm-timestamps
dm-validations
dm-types

So putting this all together you can do:

$ gem install data_mapper dm-sqlite-adapter

Changes

A lot of tickets have been addressed during the release candidate cycle and you can refer to the earlier RC notes for change details (RC2, RC3). You should also refer to the list of 61 tickets we've resolved for the 1.0 milestone:

http://datamapper.lighthouseapp.com/projects/20609/milestones/62234-0103

How to report issues

Please report any issues you find in IRC, on the mailing list, or inthe tracker:

DataMapper 1.0.0 rc3 released

2010-05-27T00:00:00-07:00

DataMapper 1.0.0 rc3 released

Today I released DataMapper 1.0.0 rc3. It includes several bugs fixes for issues found in rc2, as well as a few other tickets in the queue.

How do I install rc3?

Since the installation process is pretty similar to rc2, I'm going to give you the abbreviated version. Click here if you would like to see the release notes.

1) Install dm-core:

$ gem install dm-core --pre

2) Install an adapter:

$ gem install dm-sqlite-adapter --pre

3a) Install supporting gems:

$ gem install dm-migrations dm-transactions --pre

3b) OR install a metagem with several well tested supporting gems:

$ gem install data_mapper --pre

This pulls a nice base stack for DM development. The gems included are:

dm-core
dm-aggregates
dm-constraints
dm-migrations
dm-transactions
dm-serializer
dm-timestamps
dm-validations
dm-types

Or use this one-liner to install everything in one go:

$ gem install data_mapper dm-sqlite-adapter --pre

What's changed?

To see more information about the tickets we've closed since 0.10.2 check out the current milestone status on Lighthouse.

How to report issues

Please report any issues you find in IRC, on the mailing list, or in the tracker:

DataMapper 1.0.0 rc2 released

2010-05-20T00:00:00-07:00

DataMapper 1.0.0 rc2 released

I just wanted to give you the heads up that we've just released DataMapper 1.0.0 rc2.

With RailsConf coming up, and the launch of DM 1.0, we are starting the RC process now to make sure the installation process is solid and that the API is stable beforehand.

Installation Changes

The installation process for DM 1.0 is pretty similar to what it was previously in 0.10.x and 0.9.x with a few exceptions:

Using auto-migration and auto-upgrading require dm-migrations rather than just dm-core. The reason for this is that dm-migrations should share alot of code with auto-migrations, but they don't, and in an attempt to DRY things up we've centralized all the code in one package and will begin refactoring the code over the coming months.
Transactions require the use of the dm-transactions gem.
It is no longer necessary to gem install data_objects or any do_* gem directly. Each DO based adapter has been extracted into their own gems, and installing them will setup the dependencies on dm-core and the appropriate DO gem(s). The new adapters are:
dm-sqlite-adapter
dm-postgres-adaper
dm-mysql-adapter
dm-oracle-adapter
dm-sqlserver-adapter

How do I install the RC?

The first step is to make sure you've installed extlib 0.9.15:

$ gem install extlib -v0.9.15

Note that this will go away in the next RC. I forgot to add extlib 0.9.15 as a dependency for rc2, which is why it's required explicitly at the moment.

Since this is a prerelease gem you have to install dm-core with the -- pre option, eg:

$ gem install dm-core --pre

If you don't specify --pre, rubygems will download the last stable version of DM, which is 0.10.2.

The next thing you want to do is decide which adapter you want to use. For example if you want to use sqlite, do:

$ gem install dm-sqlite-adapter --pre

This should pull in data_objects and do_sqlite3 automatically, so no need to specify either of those explicitly anymore.

It's likely you'll want to use migrations (for classic or auto- migrations), and transactions when using sqlite, so to install them do:

$ gem install dm-migrations dm-transactions --pre

There is also a metagem which combines several gems into a single package:

$ gem install data_mapper --pre

This pulls a nice base stack for DM development. The gems included are:

So putting this all together you can do:

$ gem install extlib -v0.9.15
$ gem install data_mapper dm-sqlite-adapter --pre

Again, the extlib installation step will not be necessary in the next RC.

What are the changes?

There are alot of internal refactorings, some bug fixes, but for the most part 1.0.0 should be quite similar to 0.10.2. We decided to launch 1.0 because DM has been in a relatively stable state for the last 6 months, and there aren't any really major API changes left. Anything that's planned are more additions rather than changes to existing functionality, so we decided it was better to freeze the current API at 1.0 and release for RailsConf.

There are some simplifications in the Property/Type API you should be aware of. Some custom types you have may require slight modifications to work with 1.0.0 rc2. Piotr Solnica will be posting some information about how to do the modification, but for now look at the Property subclasses in dm-types as well as inside dm-core to get an idea of how it works.

As mentioned, the other large change is how auto-migrations have been moved to dm-migrations, as well as transactions to dm-transactions. The main reason we moved those from the core is that only a small fraction of DM adapters support migrations and transactions, and it didn't seem right for the core layer to know anything about those concerns. I felt that having them in a separate package allows us to eliminate some duplcation (in the case of migrations), and ensure transactions gets more attention than if it was part of core.

Where was rc1?

You might be asking yourself "where was rc1?". Well... I decided to do a soft launch of the first rc and just announce it to people in the #datamapper IRC channel on freenode. It's been a few months since we did any kind of release, and with the new gem organization I wasn't sure if we'd have all the kinks worked out. There was one small issue actually, so we bumped to rc2 and released the same day. We also added the latest DO as a dependency, which has a number of improvements/bug fixes, so I think this was a good thing overall.

How to report issues

Please report any issues you find in IRC, on the mailing list, or in the tracker:

DataMapper 0.10.2 is Released

2009-12-11T00:00:00-08:00

DataMapper 0.10.2 is Released

This release adds new Set operations, fixes multiple bugs, and even more of the public API is specced.

Read the Release Announcement for more info

DataMapper at RubyEnRails Amsterdam 2009

2009-12-07T00:00:00-08:00

DataMapper at RubyEnRails Amsterdam 2009

ReR09 - DirkjanBussink from Interbureau Holder on Vimeo.

At this year's RubyEnRails 2009, Dirkjan Bussink presented the current 0.10.x series of DataMapper and gave a preview of what lies ahead for the 1.0 release.

DataMapper

View more documents from Dirkjan Bussink.

DataMapper 0.10 is Released

2009-09-15T00:00:00-07:00

DataMapper 0.10 is Released

DataMapper 0.10 is ready for release. We've worked on it for the past 11 months, pushed 1250 commits, written 3000+ specs, and fixed 140 tickets in the process.

DataMapper Presented at RailsConf 2008

2008-06-10T00:00:00-07:00

DataMapper Presented at RailsConf 2008

Yehuda Katz (wycats) gave an updated version of his "DataMapper - The Persistence Framework" presentation at Rails Conf 2008. Though video isn't available for the talk, he was nice enough to share his slides.

| View | Upload your own

They're available for download and review direct from SlideShare at http://www.slideshare.net/wycats/datamapper/.

Adam French (afrench) was in attendance and participated in the 'Birds Of A Feather' discussion panel on Rails Alternatives and You led by Mark Bates.

DataMapper 0.9 is Released

2008-05-27T00:00:00-07:00

DataMapper 0.9 is Released

DataMapper 0.9 is ready for the world. It brings with it a massive overhaul of the internals of DataMapper, a shift in terminology, a dramatic bump in speed, improved code-base organization, and support for more than just database data-stores.

To install it:

sudo gem install addressable english rspec
sudo gem install data_objects do_mysql do_postgres do_sqlite3
sudo gem install dm-core

This is NOT a backwards compatible release. Code written for DataMapper 0.3 will not function with DataMapper 0.9.* due to syntactical changes and library improvements.

REPEAT: This is NOT a backwards compatible release.

	DataMapper 0.3	DataMapper 0.9
Creating a class	`class Post < DataMapper::Base end`	`class Post include DataMapper::Resource end`
Keys	`# Key was not mandatory # Automatically added +id+ if missing # # Natural Key property :name, :string, :key => true # # Composite Key property :id, :integer, :key => true property :slug, :string, :key => true`	`# keys are now mandatory property :id, Serial # # Natural Key property :slug, String, :key => true # # Composite Key property :id, Integer, :key => true property :slug, String, :key => true`
Properties	`property :title, :string property :body, :text property :posted_on, :datetime property :active, :boolean`	`property :title, String property :body, Text property :posted_on, DateTime property :active, Boolean`
Associations	`has_many :comments belongs_to :blog has_and_belongs_to_many :categories has_one :author`	`has n, :comments belongs_to :blog has n, :categories => Resource has 1, :author`
Finders	`Post.first :order => 'created_at DESC' Post.all :conditions => [ 'active = ?', true ] database.query 'SELECT 1' database.execute 'UPDATE posts...'`	`Post.first :order => [ :created_at.desc ] Post.all :conditions => [ 'active = ?', true ] repository(:default).adapter.query 'SELECT 1' repository(:default).adapter.execute 'UPDATE posts...'`
Validations	`validates_presence_of :title validates_numericality_of :rating validates_format_of :email, :with => :email_address validates_length_of :summary, :within => 1..100 validates_uniqueness_of :slug`	`validates_present :title validates_is_number :rating validates_format :email, :as => :email_address validates_length :summary, :in => 1..100 validates_is_unique :slug`
Callbacks	`before_save :categorize before_create do \|post\| # do stuff with post end # return false to abort`	`before :save, :categorize before :create do # do stuff with self end # throw :halt to abort`

DataMapper Presented at MWRC 2008

2008-04-10T00:00:00-07:00

DataMapper Presented at MWRC 2008

At this year's Mountain West Ruby Conference 2008, DataMapper's own Yehuda Katz gave a presentation entitled "Faster, Better ORM With DataMapper."

The video of the talk is available for viewing and downloading at http://mwrc2008.confreaks.com/04katz.html and is brought to you by the good people at confreaks.com.

Spotlight on... Laziness

2008-04-03T00:00:00-07:00

Spotlight on... Laziness

Laziness. It means "an unwillingness to work or use energy" and typically indicates that the dishes don't get washed after lunch, the bath tub doesn't get cleaned, and the trash sits around an extra few days and stinks up the place.

But that very same definition in software takes on a whole new meaning: To avoid doing work you don't have to do for as long as you can avoid it; sometimes never doing it at all. It's a good thing. It means that expensive and slow tasks can be put off until the very last cycle possible and thus only incur their cost when it really is worth it. Maybe you never execute the code at all.

You could put off running a specific subroutine because it's slow, or because it locks a file that might be needed elsewhere, or because instantiating the resulting object eats up RAM. Either way, deferring execution of a block of code until the very last possible moment can be the difference between a snappy application that rarely slows down and a slow application that rarely speeds up.

But laziness isn't without its hidden costs. If you put off everything to the very last moment, you forfeit the opportunity to do more than one thing at a time, and likely create more work for yourself, rather than less.

So where's the balance?

Ultimately, it depends on your application. The tools you use should offer you the flexibility you need to design your application optimally. Every system, after all, is unique and breaks the mold of systems before it.

This brings us to DataMapper.

Lazy-loading attributes

You likely already know that DataMapper supports lazy properties.

class Post
  include DataMapper::Resource

  property :id,    Serial                  # auto_incrementing primary key
  property :title, String, :lazy => true   # intentionally lazy
  property :body,  Text                    # lazy by default
end

In this case, we're intentionally marking this Post's :title property as lazy, as well as letting the :body be lazy by default. If we go and inspect our query log for the retrieval of a post with the ID of 1, we see

SELECT `id` FROM `posts` WHERE `id` = 1

DataMapper didn't request the two lazy columns. But when we call .title off of our post, we suddenly see

SELECT `title` FROM `posts` WHERE `id` = 1

This is the very definition of a lazy-loaded property; The lazy column didn't get requested from our data store until we actually needed it, and no sooner.

But this is just for one individual instance of a post. How does this behave when we have a collection of posts and iteratively call the .title method?

SELECT `title` FROM `posts` WHERE `id` IN (1, 2, 3, 4, 5)

DataMapper loaded up the title for all of the posts in our collection in one query. It didn't issue the lazy-load retrieval from above over and over for each individual post, nor did it chicken out and issue the lazy-load retrieval for ALL of the posts in the data store.

When you retrieve a set of results using DataMapper's .all, each instance it returns knows about the others in the result set, which makes it brutally simple to issue just one lazy-load retrieval of :title, and thus solving the n+1 query problem without having to do anything special in the initial retrieval.

Contextual Lazy-loading

With a recent commit by Guy van den Berg, DataMapper just got a whole lot more flexible.

Most applications have only a few main views of a resource: a brief summary view used in listing results, a complete representation that might appear on a show page and a comprehensive view for when someone is editing something and needs access to metadata. Wouldn't it be nice to lump all of the lazy-load retrieval queries into one query which loads up multiple lazy properties, rather than query after query for each lazy property as you call them?

DataMapper now does this!

class Post
  include DataMapper::Resource

  property :id,    Serial
  property :title, String, :lazy => [ :summary, :brief ]
  property :body,  Text,   :lazy => [ :summary ]
end

So now, when you load an attribute with the :summary context, DataMapper will load up all of the other lazy-loaded properties marked :summary in one query to the data store.

In your query log, you'll see:

-- initial load
SELECT `id` FROM `posts`

-- lazy-loading of multiple properties in a given context in one query
SELECT `id`, `title`, `body` FROM `posts`

If you use this wisely, it would mean that DataMapper will never load more than it needs nor will it ever fire off more than the absolutely necessary amount of queries to get the job done.

It's lazy ;-)

Strategic Eager Loading

Well, not for everything.

Returning for a little bit to our "loaded set" discussion from above, every item you pull out of the data store is aware of any other item that got pulled along with it. This is a very powerful feature which lets DataMapper defeat n+1 query problems when dealing with associations as well as lazy-loading of properties.

For example, this is a severe "no no" in ActiveRecord:

  Zoo.find(:all).each do |zoo|
    zoo.animals
  end

This is a very bad idea because the ORM must query the "animals" table over and over again to load the association for each iteration. It's far better to use Zoo.find(:all, :include => [ :animals ]).each {} because a JOIN occurs and everything is retrieved in 1 query.

But the same issue doesn't exist in DataMapper. Each instance is aware of the other instances it was retrieved with. The same iterator example from above only fires off 2 queries as you're iterating and calling the association inside the each. If you forget to :include => [ :association ] in the initial query, DataMapper only ever fires off one more query to get what it needs.

Yehuda Katz has aptly named this 'Strategic Eager Loading'.

Getting Around to It

A conclusion for our talk about laziness will be written whenever I get around to it.

For now, just remember that DataMapper embraces lazy-loading, yet isn't overly zealous when the lazy properties are finally retrieved. It also fills associations strategically, and assumes you're going to iterate over the set of results. You don't have to catch yourself when you write an iterator because DataMapper loads associations for all of your items in the set, rather than on a one-by-one basis.

And, most importantly, you can avoid doing work you don't have to do for as long as you can avoid it.

Spotlight on... Composite Keys

2008-03-29T00:00:00-07:00

Spotlight on... Composite Keys

For those of us who have taken a course on database design in college or university, you may have run across a concept called 'Composite Primary Keys' (or sometimes 'Compound Keys' or 'Concatenated Keys', and abbreviated CPKs). It's usually right before you tackle JOINs and right after you fight with the "surrogate key" or "primary key" concept.

Boiling CPKs down, they're just a way of identifying a row by multiple keys rather than one. So instead of an auto_incrementing "serial" primary key (as in id), you'd have a combination of some_column and some_other_column that would uniquely identify a row.

CPKs aren't as prevalent in the Rails world as Serial Keys (such as the auto-incrementing :id column), but if you're going to support legacy, integration or reporting databases or just de-normalized schemas for performance reasons, they can be invaluable. So sure, Surrogate Keys are a great convenience, but sometimes they just aren't an option.

Let's briefly take a look at how a few ruby ORMs support Composite Primary Keys and then we'll talk about DataMapper's support for CPKs.

ActiveRecord

In short, ActiveRecord doesn't support CPKs without the help of an external library. Dr. Nic Williams Composite Keys is an effort to overcome this limitation.

Sequel

Unlike ActiveRecord, Sequel supports CPKs natively:

class Post < Sequel::Model
  set_primary_key [ :category, :title ]
end

post = Post.get('ruby', 'hello world')
post.key  # => [ 'ruby', 'hello world' ]

p(attribution). example compiled from http://github.com/jeremyevans/sequel.

DataMapper

The latest DataMapper was designed from the ground up to support CPKs:

class Pig
  include DataMapper::Resource

  property :id,   Integer, :key => true
  property :slug, String,  :key => true
  property :name, String
end

pig = Pig.get(1, 'Porky')

pig.key  # => [ 1, 'Wilbur' ]

We declared our keys by adding the :key => true to the appropriate properties. The order is important as it will determine the order keys are addressed throughout the system.

Next, we mixed and matched the keys' types. :id is a Integer, but :slug is a String. DataMapper didn't flinch when we defined a key column as a String because it supports Natural Keys as well.

Lastly, when retrieving rows via get and [] with a CPK, we supplied the keys in the order they were defined within our model. For example, we defined :id first, then :slug second; later, we retrieved Porky by specifying his :id and :slug in the same order. Additionally, when we asked Wilbur for his keys, he handed us an array in the order the keys were defined.

We didn't need to mix in an external library to get support for CPKs, nor did we need to call a set_primary_key method and then supply more than one key to it. DataMapper supports Composite Primary Keys intuitively and without compromise!

In later "Spotlight On..." articles, we'll examine and demonstrate other DataMapper features or persistence concepts as well as compare similar features with other ORMs or libraries.

*[CPK]: Composite Primary Keys

The Great Refactoring

2008-03-22T00:00:00-07:00

The Great Refactoring

"Tip" DataMapper (hosted on github) is going through a dramatic re-factor. Here's a quick summary of the anticipated NEW public API.

Not Just for Databases Anymore

DataMapper's class terminology will change and 'de-couple' itself from database-specific terminology. Gone are "database", "table", "column" and "join". Say hello to "Repository", "Resource", "Property", and "Link".

"Why would you want to do that?", you ask. Ultimately it's because DataMapper will soon support different types of persistence layers, not just databases. It'll talk to all sorts of things like web services (REST and such), XML files, YAML files, non-relational databases, even custom file-types or services of your own design. Just implement an Adapter that conforms to a certain API and DataMapper could support any type of data store. No need for a completely separate library or anything.

As an added benefit, DataMapper become more "RESTful". Ryan Tomayko has a very good explanation of REST that all should read entitled How I Explained REST to My Wife.

Model Definitions Are a Little Different

Since we're changing up the terminology, model definitions are going to change up a little bit. Here's what a Planet model would look like using the new API:

class Planet
  include DataMapper::Resource

  resource_names[:legacy] = 'dying_planets'

  property :name, String
  property :age,  Integer
  property :core, String,  :private => true
end

A couple of things are going on here. First, DataMapper::Base and DataMapper::Persistence are gone and replaced with DataMapper::Resource. Next set_table_name has been replaced with resource_names hash where you specify which arena play occurs in. After that we have a couple of Property definitions that look a little different.

First off, Properties will no longer take :symbols for their types and instead take real constants like String, Integer, DateTime. Also on the docket are the ability to define your own custom types.

Think about that for a minute. If developers are able to define their own custom types with their own materialization and serialization methods, DataMapper will be able to support all kinds of wild data-types like GIS information, network information, marshaled objects, JSON...pretty much anything a developer might need, or want.

A Command-Line Interface

Taking a lesson from web frameworks, DataMapper will sport an interactive command-line so that you can browse your resources without the need to load up the entire environment of your application. Here's an example session:

$ dm mysql://root@localhost/great_musicians  # connecting to a repository

An IRB session boots up...

>> the_king = Person.first(:name => 'elvis')
>> the_king.alive?  # => maybe

This is very similar to script/console in Rails or merb -i in Merb, only it won't load up the entire environment of your application, just your DataMapper resources and their associations, methods, and such. If you prefer "fat models", this will constitute the core of your application.

How This All Comes Together

This is the coolest new feature of DataMapper: we're skipping all the way from 0.3.0 to 0.9! Get excited, contact the press, fire up the blogosphere! Its a huge jump and we're honestly concerned that people may not be able to handle it.

Alright, so it's not that big of a deal, but we're confident that all of this will get DataMapper so close to going 1.0 that we'll be able to taste it. To get there, DataMapper's more advanced features like single table inheritance, paranoia, and chained associations will be re-implemented to use all this new stuff, and then we're sure 0.9 will need a touch up or two.

So close....so very very close...

Stay tuned in to the mailing list, check up on the wiki, chat it up in #datamapper and watch github commit messages for updates.

Datamapper.org News and Notes

DataMapper 1.2.0 released

DataMapper 1.2.0 released

Installation

Changes

valid? is always called even if a resource is not dirty

DataMapper 1.1.0 released

DataMapper 1.1.0 released

Installation

Changes

How to report issues

DataMapper 1.0.2 released

DataMapper 1.0.2 released

Installation

Changes

How to report issues

DataMapper 1.0 released

DataMapper 1.0 released

Before you install

Installation

Changes

How to report issues

DataMapper 1.0.0 rc3 released

DataMapper 1.0.0 rc3 released

How do I install rc3?

What's changed?

How to report issues

DataMapper 1.0.0 rc2 released

DataMapper 1.0.0 rc2 released

Installation Changes

How do I install the RC?

What are the changes?

Where was rc1?

How to report issues

DataMapper 0.10.2 is Released

DataMapper 0.10.2 is Released

DataMapper at RubyEnRails Amsterdam 2009

DataMapper at RubyEnRails Amsterdam 2009

DataMapper 0.10 is Released

DataMapper 0.10 is Released

DataMapper Presented at RailsConf 2008

DataMapper Presented at RailsConf 2008

DataMapper 0.9 is Released

DataMapper 0.9 is Released

DataMapper Presented at MWRC 2008

DataMapper Presented at MWRC 2008

Spotlight on... Laziness

Spotlight on... Laziness

Lazy-loading attributes

Contextual Lazy-loading

Strategic Eager Loading

Getting Around to It

Spotlight on... Composite Keys

Spotlight on... Composite Keys

ActiveRecord

Sequel

DataMapper

The Great Refactoring

The Great Refactoring

Not Just for Databases Anymore

Model Definitions Are a Little Different

A Command-Line Interface

How This All Comes Together