datamapper 0.2.5 → 0.3.0

data/CHANGELOG

@@ -138,4 +138,8 @@
 * Added private/protected properties
 * Remove HasOneAssociation, Make HasManyAssociation impersonate has_one relationships
 * Added #get method
-* Persistence module added, inheriting from DataMapper::Base no longer necessary
+* Persistence module added, inheriting from DataMapper::Base no longer necessary
+
+-- 0.3.0
+* HasManyAssociation::Set now has a nil? method, so we can do stuff like cage.animal.nil?
+

data/FAQ

@@ -0,0 +1,96 @@
+:include:QUICKLINKS
+
+= FAQ
+
+=== I don't want to use :id as a primary key, but I don't see <tt>set_primary_key</tt> anywhere. What do I do?
+
+If you're working with a table that doesn't have a <tt>:id</tt> column, you can declare your properties as you usually do, and declare one of them as a natural key.
+
+   property :name, :string, :key => true
+
+You should now be able to do <tt>Class['name_string']</tt> as well. Remember: this column should be unique, so treat it that way. This is the equivalent to using <tt>set_primary_key</tt> in ActiveRecord.
+
+
+=== How do I make a model paranoid?
+
+  property :deleted_at, :datetime
+
+If you've got deleted_at, your model is paranoid auto-magically. All of your calls to <tt>##all()</tt>, <tt>##first()</tt>, and <tt>##count()</tt> will be scoped with <tt>where deleted_at is null</tt>. Plus, you won't see deleted objects in your associations.
+
+=== Does DataMapper support Has Many Through?
+
+Write me!
+
+=== What about Self-Referential Has And Belongs to Many?
+
+Sure does.  Here's an example implementation: 
+
+  class Task < DataMapper::Base
+    has_and_belongs_to_many :tasks,
+      :join_table => "task_relationships",
+      :left_foreign_key => "parent_id",
+      :right_foreign_key => "child_id"
+  end
+
+You'll notice that instead of <tt>foreign_key</tt> and <tt>association_foreign_key</tt>, DataMapper uses the "database-y" terms <tt>left_foreign_key</tt>, and <tt>right_foreign_key</tt>.
+
+=== Does DataMapper do Single Table Inheritance?
+
+Oh yes, and particularly well too.
+
+  class Person < Datamapper::Base
+    property :type, :class
+    ## other shared properties here
+  end  
+
+  class Salesperson < Person; end
+
+You can claim a column to have the type <tt>:class</tt> and DataMapper will automatically drop the class name of the inherited classes into that column of the database.  
+
+=== What about Class Table Inheritance?
+
+Class Table Inheritance is on the drawing board and everyone's drooling over it. So no, not yet, but soon.
+
+=== How do I run my own commands?
+
+You're probably asking for <tt>find_by_sql</tt>, and DataMapper has that in it's ActiveRecordImpersonation, but if you want to go straight-up DataMapper, you'll want to use <tt>database.query</tt>
+
+  database.query("select * from users where clue > 0")
+
+This does not return any Users (har har), but rather Struct's that will quack like Users. They'll be read-only as well.
+
+<tt>database.query</tt> shouldn't be used if you aren't expecting a result set back.  If you want to just execute something against the database, use <tt>database.execute</tt> instead.
+
+=== Can I batch-process a ton of records at once?
+
+  User.each(:performance_rating => "low") do |u|
+    u.employment_status = "fired"
+    u.save
+  end
+
+With ActiveRecord, doing a <tt>User.find(:all).each{}</tt> would execute the find, instantiate an object for EVERY result, THEN apply your transformations to each object in turn. Doesn't sound too horrible unless you have a TON of records; you WILL grind your system to a screeching and bloody halt.
+
+Datamapper's <tt>#each</tt> works in sets of 500 so the amount of objects instantiated at a time won't make your computer think it's a victim in a Saw movie. Once it's done executing your block on the first set of 500, it moves on to the next.
+
+What's more is <tt>#each</tt> is secretly a finder too. You can pass it an options hash and it'll only iterate on 500-item sets matching your query. Don't send it <tt>:offset</tt> though, because that's how it pages. You can overload the page size by sending it <tt>:limit</tt>
+
+=== Can I get an SQL log of what queries DataMapper is issuing?
+
+Yup, when you issue <tt>Database.setup</tt>, tack on the <tt>log_stream</tt> and <tt>log_level</tt>:
+
+  DataMapper::Database.setup({
+   :adapter    => 'mysql',
+   :host       => 'localhost',
+   :username   => 'root',
+   :password   => 'R00tPaswooooord',
+   :database   => 'myspiffyblog_development',
+   :log_stream => 'log/sql.log',
+   :log_level  => 0
+  })
+
+By supplying the <tt>log_stream</tt> you're telling DataMapper what file you want to see your sql logs in. <tt>log_level</tt> is the Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/] level of output you want to see there. 0, in this case, says that you want to see all DEBUG level messages (and higher) sent to the logger. For more information on how to work with Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/], hit up http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/.
+
+Incidentally, if you'd like to send a message into the Datamapper logger, do:
+
+  database.adapter.logger.info "your message here"
+

data/QUICKLINKS

@@ -0,0 +1,12 @@
+= Quick Links
+
+* Finders and CRUD - DataMapper::Persistence::ConvenienceMethods::ClassMethods
+* Properties - DataMapper::Property
+* Validations - Validatable
+* Migrations
+* FAQ[link:/files/FAQ.html]
+* Contact Us
+  * Website - http://www.datamapper.org
+  * Bug Reports - http://wm.lighthouseapp.com/projects/4819-datamapper/overview
+  * IRC Channel - <tt>##datamapper</tt> on irc.freenode.net
+  * Mailing List - http://groups.google.com/group/datamapper/

data/README

@@ -1,203 +1,105 @@
-= 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.
+:include:QUICKLINKS
 
-== Why you should use DataMapper
+= Why DataMapper?
 
-=== Speed
+== Open Development
 
-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. 
+Datamapper sports a very accessible code-base and a welcoming community. Outside contributions and feedback are welcome and encouraged, especially constructive criticism. Make your voice heard! Submit a ticket[http://wm.lighthouseapp.com/projects/4819-datamapper/overview] or patch[http://wm.lighthouseapp.com/projects/4819-datamapper/overview], speak up on our mailing-list[http://groups.google.com/group/datamapper/], chat with us on irc[irc://irc.freenode.net/#datamapper], write a spec, get it reviewed, ask for commit rights. It's as easy as that to become a contributor.
 
-Where other ORMs have failed you before, DataMapper strives to make up for this gap.
+== Identity Map
 
-If this has piqued your interest, look below and learn how to get started. 
+One row in the database should equal one object reference. Pretty simple idea. Pretty profound impact. If you run the following code in ActiveRecord you'll see all <tt>false</tt> results. Do the same in DataMapper and it's <tt>true</tt> all the way down.
 
-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".
 
+  @parent = Tree.find(:first, :conditions => ['name = ?', 'bob'])
 
-    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
+  @parent.children.each do |child|
+    puts @parent.object_id == child.parent.object_id
+  end
 
-==== QuickStart
-If you want to find out how to use DataMapper in your existing application, jump to "Require it in your application".
+This makes DataMapper faster and allocate less resources to get things done.
 
-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
+== Don't Do What You Don't Have To
 
-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'])
+ActiveRecord updates every column in a row during a save whether that column changed or not. So it performs work it doesn't really need to making it much slower, and more likely to eat data during concurrent access if you don't go around adding locking support to everything. 
 
-=== Require it in your application
+DataMapper only does what it needs to. So it plays well with others. You can use it in an Integration Database without worrying that your application will be a bad actor causing trouble for all of your other processes.
 
-  require 'rubygems'
-  require 'data_mapper'
-  
-=== Specify a Database Connection
+== Eager Loading
 
-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.
+Ready for something amazing? The following example executes only two queries.
 
-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
+  zoos = Zoo.all
+  first = zoos.first
+  first.exhibits # Loads the exhibits for all the Zoo objects in the zoos variable.
 
-Defining your models requires a few steps.
+Pretty impressive huh? The idea is that you aren't going to load a set of objects and use only an association in just one of them. This should hold up pretty well against a 99% rule. When you don't want it to work like this, just load the item you want in it's own set. So the DataMapper thinks ahead. We like to call it "performant by default". This feature single-handedly wipes out the "N+1 Query Problem". No need to specify an <tt>include</tt> option in your finders.
 
-* Include the module DataMapper::Persistence in your class
-* Define your properties you wish to access from the database
-* Define any relationships (optional)
+== Laziness Can Be A Virtue
 
-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.
+Text columns are expensive in databases. They're generally stored in a different place than the rest of your data. So instead of a fast sequential read from your hard-drive, your database server has to hop around all over the place to get what it needs. Since ActiveRecord returns everything by default, adding a text column to a table slows everything down drastically, across the board.
 
-Your models might end up looking something like this:
+Not so with the DataMapper. Text fields are treated like in-row associations by default, meaning they only load when you need them. If you want more control you can enable or disable this feature for any column (not just text-fields) by passing a @lazy@ option to your column mapping with a value of <tt>true</tt> or <tt>false</tt>.
 
-  class Animal
-    include DataMapper::Persistence
 
+  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
+    property :notes, :text, :lazy => false
   end
-  
-==== Lazy Attributes
 
-Lazy attributes are one of the many speed enhancing features in DataMapper.
+ 
+Plus, lazy-loading of text fields happens automatically and intelligently when working with associations.  The following only issues 2 queries to load up all of the notes fields on each animal:
 
-Properties that are given the lazy attribute will not be loaded until they are accessed by your code.
+  animals = Animal.all
+  animals.each do |pet|
+    pet.notes
+  end
 
-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.
+== Plays Well With Others
 
-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
+In ActiveRecord, all your columns are mapped, whether you want them or not. This slows things down. In the DataMapper you define your mappings in your model. So instead of an _ALTER TABLE ADD COLUMN_ in your Database, you simply add a <tt>property :name, :string</tt> to your model. DRY. No schema.rb. No migration files to conflict or die without reverting changes. Your model drives the database, not the other way around. 
 
-You'd notice the <b>nil</b> fields immediately.
+Unless of course you want to map to a legacy database. Raise your hand if you like seeing a method called <tt>col2Name</tt> on your model just because that's what it's called in an old database you can't afford to change right now? In DataMapper you control the mappings:
 
-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. 
+  class Fruit < DataMapper::Base
+    set_table_name 'frt'
+    property :name, :string, :column => 'col2'
+  end
 
-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
+== All Ruby, All The Time
 
-Only two queries hit our database. All with the automagical power of DataMapper!
+It's great that ActiveRecord allows you to write SQL when you need to, but should we have to so often? 
 
-=== Associations
+DataMapper supports issuing your own SQL, but it also provides more helpers and a unique hash-based condition syntax to cover more of the use-cases where issuing your own SQL would have been the only way to go. For example, any finder option that's non-standard is considered a condition. So you can write <tt>Zoo.all(:name => 'Dallas')</tt> and DataMapper will look for zoos with the name of 'Dallas'. 
 
-DataMapper's associations are exactly like the other ORMs out there. Some association examples are found below:
+It's just a little thing, but it's so much nicer than writing <tt>Zoo.find(:all, :conditions => ['name = ?', 'Dallas'])</tt>. What if you need other comparisons though? Try these:
 
-* 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.
+  Zoo.first(:name => 'Galveston')
 
-== AutoMigrations
+  # 'gt' means greater-than. We also do 'lt'.
+  Person.all(:age.gt => 30)
 
-With DataMapper, there's no need to constantly create migration after monotonous migration during your initial development.
+  # 'gte' means greather-than-or-equal-to. We also do 'lte'.
+  Person.all(:age.gte => 30)
 
-Once you've got your models to a point where you'd like a table associated with them, simply execute the following:
+  Person.all(:name.not => 'bob')
 
-  database.save(ModelName)
-  
-This will generate the table structure for your model automatically. 
+  # If the value of a pair is an Array, we do an IN-clause for you.
+  Person.all(:name.like => 'S%', :id => [1, 2, 3, 4, 5])
 
-You can also execute the following to generate ALL of your models' tables:
+  # An alias for Zoo.find(11)
+  Zoo[11]
 
-  DataMapper::Persistence.auto_migrate!
+  # Does a NOT IN () clause for you.
+  Person.all(:name.not => ['bob','rick','steve'])
 
-=== 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
+See? Fewer SQL fragments dirtying your Ruby code. And that's just a few of the nice syntax tweaks DataMapper delivers out of the box...
 
-Merb's coding conventions are a fantastic start: (http://merb.devjavu.com/#ContributingtoMerb)
+== Better Is Great, But Familiar Is Nice
 
-DataMapper could use some documentation help. If you'd like to contribute, the example you'll
-find on the above link is top-notch.
+The DataMapper also supports a lot of old-fashioned ActiveRecord syntax. We want to make it easy for you to get started, so aside from mapping your columns and changing the base-class your models inherit from, much of AR syntax for finders are supported as well, making your transition easy.

data/environment.rb

@@ -1,44 +1,62 @@
-# 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
-}
-
-# 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'
+unless defined?(INITIAL_CLASSES)
+  # 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
+  }
+
+  # Prepare the log path, and remove the existing spec.log
+  require 'fileutils'
+
+  if ENV['LOG_NAME']
+    log_path = nil
+    
+    if ENV['LOG_NAME'] != 'STDOUT'
+      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)
+    else
+      log_path = 'STDOUT'
     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::Persistence.auto_migrate! unless ENV['AUTO_MIGRATE'] == 'false'
+    
+    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
+
+  secondary_configuration_options = configuration_options.dup
+  secondary_configuration_options.merge!(:database => (adapter == 'sqlite3' ? 'data_mapper_2.db' : 'data_mapper_2'))
+  
+  DataMapper::Database.setup(configuration_options)
+  DataMapper::Database.setup(:secondary, secondary_configuration_options)
+  DataMapper::Database.setup(:mock, :adapter => MockAdapter)
+
+  [:default, :secondary, :mock].each { |name| database(name) { load_models.call } }
+
+  # Reset the test database.
+  unless ENV['AUTO_MIGRATE'] == 'false'
+    [:default, :secondary].each { |name| database(name) { DataMapper::Persistence.auto_migrate! } }
+  end
+
+  # Save the initial database layout so we can put everything back together
+  # after auto migrations testing
+  INITIAL_CLASSES = Array.new(DataMapper::Persistence.subclasses.to_a)
+end