Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Integrate DataMapper with Rails 3
Ruby
Branch: master

This branch is 2 commits ahead, 5 commits behind jhuckabee:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
tasks
.document
.gitignore
LICENSE
README.rdoc
Rakefile
VERSION
rails3_datamapper.gemspec

README.rdoc

rails3_datamapper

This gem provides the railtie that allows datamapper to hook into rails3 and thus behave like a rails framework component. Just like activercord does in rails, rails3_datamapper uses the railtie API to hook into rails. The two are actually hooked into rails almost identically.

Creating new datamapper apps on rails3 from scratch is actually really easy. The following will guide you through the process.

Sample Gemfile

Using bundler it's really easy to get an app going with datamapper and rails3. Just use a Gemfile like this, and bundler will pull in everything needed to run your app. Note that you also must add any additional datamapper plugin or any other gem that you'd like to use to the Gemfile. This makes sure that bundler is able to provide a complete environment containing all required dependencies for your app.

source 'http://gemcutter.org'

gem 'rails',        '3.0.0.beta'

gem 'data_objects', '0.10.1'
gem 'do_mysql',     '0.10.1'

git 'git://github.com/snusnu/dm-core.git', 'branch' => 'active_support'
git "git://github.com/snusnu/dm-more.git", 'branch' => 'active_support'
git 'git://github.com/dkubb/rails3_datamapper.git'

gem 'dm-core'
gem 'dm-types'
gem 'dm-validations'
gem 'dm-constraints'
gem 'dm-aggregates'
gem 'dm-timestamps'
gem 'dm-migrations'
gem 'dm-observer'
gem 'rails3_datamapper'

Generating a new application from scratch

It's really easy to go from zero gems to a working rails3 app using datamapper. Basically, all you need is bundler.

gem install bundler

Once you have bundler installed, you can bootstrap a rails3 application with the following commands. Note that you should choose either the Gemfile for the rails3 beta gem or the one for rails master, but not both. Furthermore, it's currently necessary to fetch a config/database.yml file manually. This will change once I find out more clever ways to do this.

mkdir rails3_app; cd rails3_app
curl -L http://is.gd/7Q6AB > Gemfile # rails-3.0.0.beta gem
curl -L http://is.gd/7QrBt > Gemfile # rails master from github
bundle install vendor
bundle exec vendor/bin/rails . -s --skip-activerecord --skip-prototype skip-testunit
# At this point you will have to get a config/database.yml still
# This will not be necessary once we can come up with proper rails application templates
# In the meantime, you can either write config/database.yml yourself or fetch one from the
# sample app (note that you would have to change the name of the database in that case)
curl -L http://is.gd/7R29l > config/database.yml

At that point, you should have a running rails3 application, but that's unfortunately not enough at that point. To really use rails3_datamapper you currently have to replace the corresponding lines in config/application.rb with the following. This tells rails that we don't want to use active_record, but datamapper instead.

# Pick the frameworks you want:
require "action_controller/railtie"
require "rails3_datamapper/railtie"
require "action_mailer/railtie"
# require "active_resource/railtie"
# require "rails/test_unit/railtie"

At this point you should have everything you need in order to start your datamapper on rails3 application. Type the following and you should be good to go.

vendor/bin/rails server

Minimal sample application

Have a look at datamapper_on_rails3 for a very minimal sample application that was built following the previous instructions on how to build a new application from scratch.

Available generators

Due to the awesomeness of rails3 generators we get some cool generators almost for free. Since the new generators provide hooks that allow the rails3_datamapper gem to provide generators that hook into parts like model, scaffolds or test generation, everything just works like it would with active_record.

The following generators are available to help you get started with the typical components of any rails application.

bundle exec rails generate controller
bundle exec rails generate generator
bundle exec rails generate helper
bundle exec rails generate integration_test
bundle exec rails generate mailer
bundle exec rails generate metal
bundle exec rails generate migration
bundle exec rails generate model
bundle exec rails generate model_subclass
bundle exec rails generate observer
bundle exec rails generate performance_test
bundle exec rails generate plugin
bundle exec rails generate resource
bundle exec rails generate scaffold
bundle exec rails generate scaffold_controller
bundle exec rails generate session_migration
bundle exec rails generate stylesheets

Available datamapper specific rake tasks

To get a list of all available rake tasks in your rails3 app, issue the usual

bundlex exec rake -T

The following is an excerpt of the datamapper specific rake tasks that the rails3_datamapper gem adds for us.

...
rake db:automigrate           # Perform destructive automigration
rake db:autoupgrade           # Perform non destructive automigration
rake db:create                # Create the database defined in config/database.yml for the current Rails.env - also creates the test database if Rails.env.development?
rake db:create:all            # Create all the local databases defined in config/database.yml
rake db:drop                  # Drops the database for the current Rails.env
rake db:drop:all              # Drop all the local databases defined in config/database.yml
rake db:migrate               # Migrate the database to the latest version
rake db:migrate:down[version] # Migrate down using migrations
rake db:migrate:up[version]   # Migrate up using migrations
rake db:seed                  # Load the seed data from db/seeds.rb
rake db:sessions:clear        # Clear the sessions table for DataMapperStore
rake db:sessions:create       # Creates the sessions table for DataMapperStore
rake db:setup                 # Create the database, load the schema, and initialize with the seed data
...

Identity Map support

By default, rails3_datamapper enables the use of the identity map. If for any reason you want to turn that off, just add the following line to your config/application.rb or config/environments/*.rb file.

config.data_mapper.use_identity_map = false

Using additional datamapper plugins

In order to use additional plugins add them to the Gemfile and require them from inside a file in config/initializers. Once you've done that, update your bundle and you should be ready to use the plugin(s)

cd /path/to/your/app
edit Gemfile and add requires to your config/initializers/data_mapper_plugins
bundle install vendor

Have a look at this application's Gemfile for an idea of how to use gems from git repositories.

Rails notification system

Currently rails3_datamapper publishes the same benchmarking information like active_record does. This means that you will get output like this in your log files.

Completed in 9ms (Views: 7.6ms | DataMapper: 0.6ms) with 200

While the SQL issued by DO adapters is already being logged properly, it is not yet published to possible rails subscribers. This is basically the only thing we're still missing in terms of datamapper rails3 notifications integration, compared with active_record. Of course we're not tied to only publishing these messages. If anyone can think of other useful information to publish, it's easy to hook into rails' notification system.

Current Issues

  • migrations might not work perfectly

  • rspec-2 is not yet integrated

TODO (not necessarily in that order)

  • SPECS !!!

  • Think about a release strategy supporting both beta releases and master branch

  • Further README updates

  • More work on migrations

  • Check if the session store support works

  • rspec-2.0.0 (generator) support

  • Provide a rails template for generating tailored apps for datamapper

  • Publish SQL issued by DO (and eventually every adapter) to rails subscribers

  • Think about integrating with dana

  • Think about integrating dm-serializer

Credits

Big thanks to everyone working on datamapper, rails, bundler and open source in general. This will be (and actually already is) an awesome platform for developing web applications.

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

The rails3_datamapper team

Thx to all contributors, every patch, big or small is very much appreciated!

  • Martin Gamsjaeger (snusnu)

  • Dan Kubb (dkubb)

  • Alex Coles (myabc)

  • Alex Mankuta

  • Foy Savas

  • Randall Brewer

  • Josh Huckabee

Copyright

Copyright © 2009-2010 The rails3_datamapper team. See LICENSE for details.

Something went wrong with that request. Please try again.