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.
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.
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.
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.
migrations might not work perfectly
rspec-2 is not yet integrated
TODO (not necessarily in that order)
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
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)
Copyright © 2009-2010 The rails3_datamapper team. See LICENSE for details.