datamapper 0.1.1 → 0.2.0

data/CHANGELOG

@@ -30,3 +30,68 @@
 * Added DataMapper::Support::Struct for increased Session#query performance
 * Added AdvancedHasManyAssociation (preview status)
 * Added benchmarks comparing ActiveRecord::Base::find_by_sql with Session#query
+
+-- 0.2.0
+* AdvancedHasManyAssociation now functional for fetches
+* AdvancedHasManyAssociation renamed to HasNAssociation
+* HasManyAssociation refactored to use HasNAssociation superclass
+* Slight spec tweaks to accomodate the updates
+* HasOneAssociation refactored to use HasNAssociation superclass
+* Added HasAndBelongsToManyAssociation, using HasNAssociation as a basis; Need to add corresponding SQL generation code in AdvancedLoadCommand
+* Added spec for habtm query generation
+* HasNAssociation#foreign_key returns a DataMapper::Adapters::Sql::Mappings::Column instance instead of a raw String now
+* Added table, association, association_table and to_sql methods to HasNAssociation
+* Added associations_spec.rb
+* Added a forced table-recreation to spec_helper.rb so the tests could run with a clean version of the database, including any new columns added to the models
+* Added HasAndBelongsToManyAssociation#to_sql (all current specs pass now!)
+* Minor tweaks to Callbacks
+* Added CallbacksHelper to declare class-method ::callbacks on DataMapper::Base
+* Implemented before_validate and after_validate hooks in ValidationHelper
+* Minor documentation additions in callbacks.rb
+* Added callbacks_spec
+* Moved class-method declarations for built-in callbacks to the callbacks helper instead of DataMapper::Base
+* Renamed :before/after_validate callback to :before/after_validation to match ActiveRecord
+* Callbacks#add now accepts a Symbol which maps a callback to a method call on the targetted instance, also added a spec to verify this behavior
+* Documented callbacks.rb
+* Added DataMapper::Associations::Reference class
+* Documented DataMapper::Associations::Reference class
+* Upgraded BelongsToAssociation to new style
+* Added AssociationsSet to handle simple "last-in" for association bindings
+* Fixed extra spec loading
+* Added *Association#columns
+* Some refactoring in AdvancedLoadCommand regarding :include options
+* Added support for class-less Mappings::Table instances, with just a string name
+* HasAndBelongsToManyAssociation#join_table #left_foreign_key and #right_foreign_key reference actual Table or Column objects now
+* Added :shallow_include option for HABTM joins in AdvancedLoadCommand and corresponding spec
+* Added Commands::AdvancedConditions
+* Added ORDER, LIMIT, OFFSET and WHERE support to AdvancedLoadCommand
+* Renamed spec/has_many.rb to spec/has_many_spec.rb
+* Tweaked the loading of has_many relationships; big performance boost; got rid of an extra query
+* Added EmbeddedValue support, and accompanying spec
+* Fleshed out AdvancedConditions a bit; added conditions_spec.rb
+* Added more AdvancedConditions specs
+* Added Loader to handle multi-instanced rows
+* AdvancedLoadCommand replaced LoadCommand; down to 3 failing specs
+* All specs pass
+* Added :intercept_load finder option and accompanying spec
+* Modified :intercept_load block signature to |instance,columns,row|
+* HasAndBelongsToMany works, all specs pass
+* Fixed a couple bugs with keys; Added DataMapper::Base#key= method
+* Made DataMapper::Base#lazy_load! a little more flexible
+* Removed LoadCommand overwrites from MysqlAdapter
+* Default Database#single_threaded mode is true now
+* Removed MysqlAdapter#initialize, which only served to setup the connections, moved to SqlAdapter
+* Added SqlAdapter#create_connection and SqlAdapter#close_connection abstract methods
+* Added MysqlAdapter#create_connection and MysqlAdapter#close_connection concrete methods
+* Made SqlAdapter#connection a concrete method (instead of abstract), with support for single_threaded operation
+* Database#setup now takes a Hash of options instead of a block-initializer
+* Validation chaining should work for all association types
+* Save chaining should work for has_many associations
+* Added benchmarks for in-session performance to performance.rb
+* Removed block conditions; They're slower and don't offer any real advantages
+* Removed DeleteCommand
+* Removed SaveCommand
+* Removed TableExistsCommand
+* Session renamed to Context
+* Most command implementations moved to methods in SqlAdapter
+* Removed UnitOfWork module, instead moving a slightly refactored implementation into Base

data/README

@@ -1,5 +1,197 @@
-Start out with example.rb and go from there if you want to try it out live.
+= DataMapper
 
+DataMapper is an Object Relational Mapper written in Ruby. The goal is to create an ORM which is fast, thread-safe and feature rich.
+
+== Why you should use DataMapper
+
+=== Speed
+
+DataMapper combines tried and true principles from Martin Fowler's design patterns with a pure ruby implementation,
+creating not only beautiful syntax, but a huge speed up from other popular ORMs. 
+
+Where other ORMs have failed you before, DataMapper strives to make up for this gap.
+
+If this has piqued your interest, look below and learn how to get started. 
+
+If you're looking for cold hard numbers, take a gander at the PERFORMANCE file. 
+You'll find the latest performance stats under "Current Performance".
+
+
+    Most tests are run on a 2.16Ghz Core2Duo iMac.
+    Asterisk (*) indicates test run on 2.0Ghz Core2Duo MacBook.
+
+=== Open Development
+
+Found a bug or want a feature? Tired of dealing with the bureaucracy that other ORM maintainers force upon you? 
+
+The community surrounding DataMapper is open and friendly. Contributions of any kind are welcome, 
+and the founder and maintainer of the project can be easily reached by using the fairly active 
+mailing list (http://groups.google.com/group/datamapper) or by jumping in to the <tt>datamapper</tt>
+channel on irc.freenode.net.
+
+=== Thread-Safe
+
+Thread safety is a critical topic in any production software, and especially so with the DataMapper. 
+The maintainers have dedicated much of their time to ensuring that the DataMapper is thread safe thus far, 
+and will continue to do as much to ensure it stays that way.
+
+=== Hacker Friendly
+
+One of the most frustrating problems with other ORMs is the painstaking time it takes
+to understand and traverse the code-base. 
+
+DataMapper aims to be as lightweight as possible, keeping
+the code-base clean and uncluttered. Never be afraid to crack open the subversion trunk again!
+
+
+== Getting Started
+
+=== Install DataMapper
+There are two simple options for getting started with DataMapper.
+
+If you'd like to use SVN and check out the bleeding edge version of the project, 
+execute the following command in your terminal:
+
+
+  svn co http://datamapper.rubyforge.org/svn/trunk/ data_mapper
+
+After checking out the trunk, point your application to the trunk/lib folder and require it.
+
+If you'd like to just <i>use</i> datamapper and don't plan on looking at the source code or want bleeding edge features, 
+execute this instead:
+
+  gem install datamapper
+
+==== QuickStart
+If you want to find out how to use DataMapper in your existing application, jump to "Require it in your application".
+
+If you'd like to get started right away and play with the syntax of DataMapper, and you're using MySQL as your database,
+create a new database called:
+  data_mapper_1
+
+Then drop into the trunk directory, and execute:
+  rake
+  
+That will setup your database. From there, execute:
+  ruby example.rb
+  
+This will drop you into an IRB session, where you can further play with the syntax. Try out the intuitive finders:
+  Animal[0]
+  Animal.all
+  Zoo.first(:name => 'Galveston')
+  Zoo.find(:first, :conditions => ['name = ?', 'Galveston'])
+
+=== Require it in your application
+
+  require 'rubygems'
+  require 'data_mapper'
+  
+=== Specify a Database Connection
+
+Datamapper has Merb and Rails users in mind when setting up. If you've already setup a Merb or 
+Ruby on Rails project, and have a database.yml, DataMapper should pick it up automatically.
+
+If you'd like to set the database connection manually before using it, do something like this:
+  DataMapper::Database.setup({
+    :adapter  => 'mysql'
+    :host     => 'localhost'
+    :username => 'root'
+    :password => 'R00tPaswooooord'
+    :database => 'selecta_development'
+  })
+  
+The currently supported databases are:
+PostgreSQL:: (postgresql adaptor)
+MySQL:: (mysql adaptor)
+SQLite3:: (sqlite3 adaptor)
+  
+=== Define Your Models
+
+Defining your models requires a few steps.
+
+* Inherit your class from DataMapper::Base
+* Define your properties you wish to access from the database
+* Define any relationships (optional)
+
+Unlike many other ORMs, DataMapper requires that you define which fields in the database
+you'd like to make available to your models as properties. There are a few reasons for this, 
+which are too numerous to go into here.
+
+Your models might end up looking something like this:
+
+  class Animal < DataMapper::Base
+    property :name, :string
+    property :notes, :text, :lazy => true
+
+    has_one :favourite_fruit, :class => 'Fruit', :foreign_key => 'devourer_id'
+    has_and_belongs_to_many :exhibits
+  end
+  
+==== Lazy Attributes
+
+Lazy attributes are one of the many speed enhancing features in DataMapper.
+
+Properties that are given the lazy attribute will not be loaded until they are accessed by your code.
+
+So if you were to load a set of database records from your database, and only used the lazy property
+of those records occasionally, your memory signature will essentially stay much smaller, while still
+easily allowing you to gain access to those attributes when you need them.
+
+For example, if you were to load all of the Animals using the class above, and were to inspect the set 
+of returned data, you'd notice that all of the notes fields were <b>nil</b>. If you were to do something 
+like the following:
+  
+  animals = Animals.all
+  animals.inspect
+
+You'd notice the <b>nil</b> fields immediately.
+
+If you were to do something like the following:
+  animals.first.notes
+  animals.inspect
+
+You'd notice that ALL of the notes fields in your set were loaded into memory. 
+
+The astute rubyist will immediately wonder if this is possible on associations, and indeed it is!
+This inevitably avoids the 1+N query problems that have so plagued us in the past. It allows us to 
+develop in an intuitive manner, so that if we executed a loop:
+
+  animals.each do |animal|
+    #The next line crafts a query to fetch ALL of this
+    #set's favorite_fruit attributes
+    puts animal.favorite_fruit
+  end
+
+Only two queries hit our database. All with the automagical power of DataMapper!
+
+=== Associations
+
+DataMapper's associations are exactly like the other ORMs out there. Some association examples are found below:
+
+* belongs_to :model
+* has_one :model
+* has_many :model
+* has_and_belongs_to_many :model
+
+You can also set the class and foreign_keys for each association if you need to override the default naming scheme.
+
+== AutoMigrations
+
+With DataMapper, there's no need to constantly create migration after monotonous migration during your initial development.
+
+Once you've got your models to a point where you'd like a table associated with them, simply execute the following:
+
+  database.save(ModelName)
+  
+This will generate the table structure for your model automatically. 
+
+You can also execute the following to generate ALL of your models' tables:
+
+  DataMapper::Base.auto_migrate!
+
+=== NOTE
+Both of these methods are DESTRUCTIVE. If you are working in anything other than a pre-production environment, 
+stay far away from these methods!
 
 == Conventions
 

data/do_performance.rb

@@ -0,0 +1,153 @@
+require 'benchmark'
+require 'lib/data_mapper'
+
+DataMapper::Database.setup({
+  :adapter => 'do_mysql',
+  :database => 'data_mapper_1',
+  :username => 'root'
+})
+
+class DMAnimal < DataMapper::Base
+  set_table_name 'animals'
+  property :name, :string
+  property :notes, :string
+end
+
+class DMPerson < DataMapper::Base
+  set_table_name 'people'
+  property :name, :string
+  property :age, :integer
+  property :occupation, :string
+  property :notes, :text
+  property :street, :string
+  property :city, :string
+  property :state, :string, :size => 2
+  property :zip_code, :string, :size => 10
+end
+
+class Exhibit < DataMapper::Base
+  property :name, :string
+  belongs_to :zoo
+end
+
+class Zoo < DataMapper::Base
+  property :name, :string
+  has_many :exhibits
+end
+
+N = (ENV['N'] || 1000).to_i
+
+# 4.times do
+#   [DMAnimal, Zoo, Exhibit].each do |klass|
+#     klass.all.each do |instance|
+#       klass.create(instance.attributes.reject { |k,v| k == :id })
+#     end
+#   end
+# end
+
+Benchmark::send(ENV['BM'] || :bmbm, 40) do |x|
+  
+  x.report('DataMapper:id') do
+    N.times { DMAnimal[1] }
+  end
+  
+  x.report('DataMapper:id:in-session') do
+    database do
+      N.times { DMAnimal[1] }
+    end
+  end
+  
+  x.report('DataMapper:all') do
+    N.times { DMAnimal.all }
+  end
+  
+  x.report('DataMapper:all:in-session') do
+    database do
+      N.times { DMAnimal.all }
+    end
+  end
+  
+  x.report('DataMapper:conditions:short') do
+    N.times { Zoo[:name => 'Galveston'] }
+  end
+  
+  x.report('DataMapper:conditions:short:in-session') do
+    database do
+      N.times { Zoo[:name => 'Galveston'] }
+    end
+  end
+  
+  x.report('DataMapper:conditions:long') do
+    N.times { Zoo.find(:first, :conditions => ['name = ?', 'Galveston']) }
+  end
+  
+  x.report('DataMapper:conditions:long:in-session') do
+    database do
+      N.times { Zoo.find(:first, :conditions => ['name = ?', 'Galveston']) }
+    end
+  end
+  
+  people = [
+    ['Sam', 29, 'Programmer', 'A slow text field'],
+    ['Amy', 28, 'Business Analyst Manager', 'A slow text field'],
+    ['Scott', 25, 'Programmer', 'A slow text field'],
+    ['Josh', 23, 'Supervisor', 'A slow text field'],
+    ['Bob', 40, 'Peon', 'A slow text field']
+    ]
+  
+  DMPerson.truncate!
+  
+  x.report('DataMapper:insert') do
+    N.times do
+      people.each do |a|
+        DMPerson::create(:name => a[0], :age => a[1], :occupation => a[2], :notes => a[3])
+      end
+    end
+  end
+  
+  x.report('DataMapper:update') do
+    N.times do
+      bob = DMAnimal.first(:name => 'Elephant')
+      bob.notes = 'Updated by DataMapper'
+      bob.save
+    end
+  end
+  
+  x.report('DataMapper:associations') do
+    N.times do
+      Zoo.all.each { |zoo| zoo.exhibits.entries }
+    end
+  end
+  
+  x.report('DataMapper:associations:in-session') do
+    database do
+      N.times do
+        Zoo.all.each { |zoo| zoo.exhibits.entries }
+      end
+    end
+  end
+  
+  x.report('DataMapper:find_by_sql') do
+    N.times do
+      database.query("SELECT * FROM zoos")
+    end
+  end
+  
+  x.report('DataMapper:accessors') do
+    person = DMPerson.first
+      
+    N.times do
+      <<-VCARD
+        #{person.name} (#{person.age})
+        #{person.occupation}
+        
+        #{person.street}
+        #{person.city}, #{person.state} #{person.zip_code}
+        
+        #{person.notes}
+      VCARD
+    end
+  end
+    
+    
+end

data/environment.rb

@@ -0,0 +1,45 @@
+# Require the DataMapper, and a Mock Adapter.
+require File.dirname(__FILE__) + '/lib/data_mapper'
+require File.dirname(__FILE__) + '/spec/mock_adapter'
+
+adapter = ENV['ADAPTER'] || 'sqlite3'
+
+configuration_options = {
+  :adapter => adapter,
+  :database =>  (ENV['DATABASE'] || 'data_mapper_1').dup,
+  :single_threaded => true
+}
+
+# Prepare the log path, and remove the existing spec.log
+require 'fileutils'
+
+if ENV['LOG_NAME']
+  FileUtils::mkdir_p(File.dirname(__FILE__) + '/log')
+  log_path = File.dirname(__FILE__) + "/log/#{ENV['LOG_NAME']}.log"
+  FileUtils::rm log_path if File.exists?(log_path)
+
+  configuration_options.merge!(:log_stream => log_path, :log_level => Logger::DEBUG)
+end
+
+case adapter
+  when 'postgresql' then
+    configuration_options[:username] = ENV['USERNAME'] || 'postgres'
+  when 'mysql' then
+    configuration_options[:username] = 'root'
+  when 'sqlite3' then
+    unless configuration_options[:database] == ':memory:'
+      configuration_options[:database] << '.db'
+    end
+end
+
+load_models = lambda do
+  Dir[File.dirname(__FILE__) + '/spec/models/*.rb'].sort.each { |path| load path }
+end
+
+DataMapper::Database.setup(configuration_options)
+DataMapper::Database.setup(:mock, :adapter => MockAdapter)
+
+[:default, :mock].each { |name| database(name) { load_models.call } }
+
+# Reset the test database.
+DataMapper::Base.auto_migrate!