activerecord 2.0.5 → 2.1.0

data/lib/active_record/locking/optimistic.rb

@@ -66,17 +66,20 @@ module ActiveRecord
           return result
         end
 
-        def update_with_lock #:nodoc:
-          return update_without_lock unless locking_enabled?
+        def update_with_lock(attribute_names = @attributes.keys) #:nodoc:
+          return update_without_lock(attribute_names) unless locking_enabled?
 
           lock_col = self.class.locking_column
           previous_value = send(lock_col).to_i
           send(lock_col + '=', previous_value + 1)
 
+          attribute_names += [lock_col]
+          attribute_names.uniq!
+
           begin
             affected_rows = connection.update(<<-end_sql, "#{self.class.name} Update with optimistic locking")
-              UPDATE #{self.class.table_name}
-              SET #{quoted_comma_pair_list(connection, attributes_with_quotes(false, false))}
+              UPDATE #{self.class.quoted_table_name}
+              SET #{quoted_comma_pair_list(connection, attributes_with_quotes(false, false, attribute_names))}
               WHERE #{self.class.primary_key} = #{quote_value(id)}
               AND #{self.class.quoted_locking_column} = #{quote_value(previous_value)}
             end_sql
@@ -104,20 +107,20 @@ module ActiveRecord
         end
 
         # Is optimistic locking enabled for this table? Returns true if the
-        # #lock_optimistically flag is set to true (which it is, by default)
-        # and the table includes the #locking_column column (defaults to
-        # lock_version).
+        # +lock_optimistically+ flag is set to true (which it is, by default)
+        # and the table includes the +locking_column+ column (defaults to
+        # +lock_version+).
         def locking_enabled?
           lock_optimistically && columns_hash[locking_column]
         end
 
-        # Set the column to use for optimistic locking. Defaults to lock_version.
+        # Set the column to use for optimistic locking. Defaults to +lock_version+.
         def set_locking_column(value = nil, &block)
           define_attr_method :locking_column, value, &block
           value
         end
 
-        # The version column used for optimistic locking. Defaults to lock_version.
+        # The version column used for optimistic locking. Defaults to +lock_version+.
         def locking_column
           reset_locking_column
         end
@@ -127,12 +130,12 @@ module ActiveRecord
           connection.quote_column_name(locking_column)
         end
 
-        # Reset the column used for optimistic locking back to the lock_version default.
+        # Reset the column used for optimistic locking back to the +lock_version+ default.
         def reset_locking_column
           set_locking_column DEFAULT_LOCKING_COLUMN
         end
 
-        # make sure the lock version column gets updated when counters are
+        # Make sure the lock version column gets updated when counters are
         # updated.
         def update_counters_with_lock(id, counters)
           counters = counters.merge(locking_column => 1) if locking_enabled?

data/lib/active_record/locking/pessimistic.rb

@@ -25,12 +25,12 @@ module ActiveRecord
     # Locking::Pessimistic provides support for row-level locking using
     # SELECT ... FOR UPDATE and other lock types.
     #
-    # Pass :lock => true to ActiveRecord::Base.find to obtain an exclusive
+    # Pass <tt>:lock => true</tt> to ActiveRecord::Base.find to obtain an exclusive
     # lock on the selected rows:
     #   # select * from accounts where id=1 for update
     #   Account.find(1, :lock => true)
     #
-    # Pass :lock => 'some locking clause' to give a database-specific locking clause
+    # Pass <tt>:lock => 'some locking clause'</tt> to give a database-specific locking clause
     # of your own such as 'LOCK IN SHARE MODE' or 'FOR UPDATE NOWAIT'.
     #
     # Example:

data/lib/active_record/migration.rb

@@ -8,6 +8,18 @@ module ActiveRecord
     end
   end
 
+  class DuplicateMigrationNameError < ActiveRecordError#:nodoc:
+    def initialize(name)
+      super("Multiple migrations have the name #{name}")
+    end
+  end
+
+  class UnknownMigrationVersionError < ActiveRecordError #:nodoc:
+    def initialize(version)
+      super("No migration with version number #{version}")
+    end
+  end
+
   class IllegalMigrationNameError < ActiveRecordError#:nodoc:
     def initialize(name)
       super("Illegal name for migration file: #{name}\n\t(only lower case letters, numbers, and '_' allowed)")
@@ -70,16 +82,16 @@ module ActiveRecord
   # * <tt>rename_table(old_name, new_name)</tt>: Renames the table called +old_name+ to +new_name+.
   # * <tt>add_column(table_name, column_name, type, options)</tt>: Adds a new column to the table called +table_name+
   #   named +column_name+ specified to be one of the following types:
-  #   :string, :text, :integer, :float, :decimal, :datetime, :timestamp, :time,
-  #   :date, :binary, :boolean. A default value can be specified by passing an
-  #   +options+ hash like { :default => 11 }. Other options include :limit and :null (e.g. { :limit => 50, :null => false })
+  #   <tt>:string</tt>, <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, <tt>:decimal</tt>, <tt>:datetime</tt>, <tt>:timestamp</tt>, <tt>:time</tt>,
+  #   <tt>:date</tt>, <tt>:binary</tt>, <tt>:boolean</tt>. A default value can be specified by passing an
+  #   +options+ hash like <tt>{ :default => 11 }</tt>. Other options include <tt>:limit</tt> and <tt>:null</tt> (e.g. <tt>{ :limit => 50, :null => false }</tt>)
   #   -- see ActiveRecord::ConnectionAdapters::TableDefinition#column for details.
   # * <tt>rename_column(table_name, column_name, new_column_name)</tt>: Renames a column but keeps the type and content.
   # * <tt>change_column(table_name, column_name, type, options)</tt>:  Changes the column to a different type using the same
   #   parameters as add_column.
   # * <tt>remove_column(table_name, column_name)</tt>: Removes the column named +column_name+ from the table called +table_name+.
   # * <tt>add_index(table_name, column_names, options)</tt>: Adds a new index with the name of the column. Other options include
-  #   :name and :unique (e.g. { :name => "users_name_index", :unique => true }).
+  #   <tt>:name</tt> and <tt>:unique</tt> (e.g. <tt>{ :name => "users_name_index", :unique => true }</tt>).
   # * <tt>remove_index(table_name, index_name)</tt>: Removes the index specified by +index_name+.
   #
   # == Irreversible transformations
@@ -91,16 +103,34 @@ module ActiveRecord
   #
   # The Rails package has several tools to help create and apply migrations.
   #
-  # To generate a new migration, use <tt>script/generate migration MyNewMigration</tt>
+  # To generate a new migration, you can use 
+  #   script/generate migration MyNewMigration
+  #
   # where MyNewMigration is the name of your migration. The generator will
-  # create a file <tt>nnn_my_new_migration.rb</tt> in the <tt>db/migrate/</tt>
+  # create an empty migration file <tt>nnn_my_new_migration.rb</tt> in the <tt>db/migrate/</tt>
   # directory where <tt>nnn</tt> is the next largest migration number.
+  #
   # You may then edit the <tt>self.up</tt> and <tt>self.down</tt> methods of
   # MyNewMigration.
   #
+  # There is a special syntactic shortcut to generate migrations that add fields to a table.
+  #   script/generate migration add_fieldname_to_tablename fieldname:string
+  #
+  # This will generate the file <tt>nnn_add_fieldname_to_tablename</tt>, which will look like this:
+  #   class AddFieldnameToTablename < ActiveRecord::Migration
+  #     def self.up
+  #       add_column :tablenames, :fieldname, :string
+  #     end
+  # 
+  #     def self.down
+  #       remove_column :tablenames, :fieldname
+  #     end
+  #   end
+  # 
   # To run migrations against the currently configured database, use
   # <tt>rake db:migrate</tt>. This will update the database by running all of the
-  # pending migrations, creating the <tt>schema_info</tt> table if missing.
+  # pending migrations, creating the <tt>schema_migrations</tt> table
+  # (see "About the schema_migrations table" section below) if missing.
   #
   # To roll the database back to a previous migration version, use
   # <tt>rake db:migrate VERSION=X</tt> where <tt>X</tt> is the version to which
@@ -178,7 +208,7 @@ module ActiveRecord
   #
   # You can quiet them down by setting ActiveRecord::Migration.verbose = false.
   #
-  # You can also insert your own messages and benchmarks by using the #say_with_time
+  # You can also insert your own messages and benchmarks by using the +say_with_time+
   # method:
   #
   #   def self.up
@@ -193,6 +223,21 @@ module ActiveRecord
   #
   # The phrase "Updating salaries..." would then be printed, along with the
   # benchmark for the block when the block completes.
+  #
+  # == About the schema_migrations table
+  #
+  # Rails versions 2.0 and prior used to create a table called
+  # <tt>schema_info</tt> when using migrations. This table contained the
+  # version of the schema as of the last applied migration.
+  #
+  # Starting with Rails 2.1, the <tt>schema_info</tt> table is
+  # (automatically) replaced by the <tt>schema_migrations</tt> table, which
+  # contains the version numbers of all the migrations applied.
+  #
+  # As a result, it is now possible to add migration files that are numbered
+  # lower than the current schema version: when migrating up, those
+  # never-applied "interleaved" migrations will be automatically applied, and
+  # when migrating down, never-applied "interleaved" migrations will be skipped.
   class Migration
     @@verbose = true
     cattr_accessor :verbose
@@ -291,18 +336,23 @@ module ActiveRecord
   class Migrator#:nodoc:
     class << self
       def migrate(migrations_path, target_version = nil)
-        Base.connection.initialize_schema_information
-
         case
-          when target_version.nil?, current_version < target_version
-            up(migrations_path, target_version)
-          when current_version > target_version
-            down(migrations_path, target_version)
-          when current_version == target_version
-            return # You're on the right version
+          when target_version.nil?              then up(migrations_path, target_version)
+          when current_version > target_version then down(migrations_path, target_version)
+          else                                       up(migrations_path, target_version)
         end
       end
 
+      def rollback(migrations_path, steps=1)
+        migrator = self.new(:down, migrations_path)
+        start_index = migrator.migrations.index(migrator.current_migration)
+        
+        return unless start_index
+        
+        finish = migrator.migrations[start_index + steps]
+        down(migrations_path, finish ? finish.version : 0)
+      end
+
       def up(migrations_path, target_version = nil)
         self.new(:up, migrations_path, target_version).migrate
       end
@@ -310,90 +360,129 @@ module ActiveRecord
       def down(migrations_path, target_version = nil)
         self.new(:down, migrations_path, target_version).migrate
       end
+      
+      def run(direction, migrations_path, target_version)
+        self.new(direction, migrations_path, target_version).run
+      end
 
-      def schema_info_table_name
-        Base.table_name_prefix + "schema_info" + Base.table_name_suffix
+      def schema_migrations_table_name
+        Base.table_name_prefix + 'schema_migrations' + Base.table_name_suffix
       end
 
       def current_version
-        Base.connection.select_value("SELECT version FROM #{schema_info_table_name}").to_i
+        version = Base.connection.select_values(
+          "SELECT version FROM #{schema_migrations_table_name}"
+        ).map(&:to_i).max rescue nil
+        version || 0
       end
 
       def proper_table_name(name)
-        # Use the ActiveRecord objects own table_name, or pre/suffix from ActiveRecord::Base if name is a symbol/string
+        # Use the Active Record objects own table_name, or pre/suffix from ActiveRecord::Base if name is a symbol/string
         name.table_name rescue "#{ActiveRecord::Base.table_name_prefix}#{name}#{ActiveRecord::Base.table_name_suffix}"
       end
     end
 
     def initialize(direction, migrations_path, target_version = nil)
       raise StandardError.new("This database does not yet support migrations") unless Base.connection.supports_migrations?
-      @direction, @migrations_path, @target_version = direction, migrations_path, target_version
-      Base.connection.initialize_schema_information
+      Base.connection.initialize_schema_migrations_table
+      @direction, @migrations_path, @target_version = direction, migrations_path, target_version      
     end
 
     def current_version
       self.class.current_version
     end
+    
+    def current_migration
+      migrations.detect { |m| m.version == current_version }
+    end
+    
+    def run
+      target = migrations.detect { |m| m.version == @target_version }
+      raise UnknownMigrationVersionError.new(@target_version) if target.nil?
+      target.migrate(@direction)
+    end
 
     def migrate
-      migration_classes.each do |migration_class|
-        if reached_target_version?(migration_class.version)
-          Base.logger.info("Reached target version: #{@target_version}")
-          break
+      current = migrations.detect { |m| m.version == current_version }
+      target = migrations.detect { |m| m.version == @target_version }
+
+      if target.nil? && !@target_version.nil? && @target_version > 0
+        raise UnknownMigrationVersionError.new(@target_version)
+      end
+      
+      start = up? ? 0 : (migrations.index(current) || 0)
+      finish = migrations.index(target) || migrations.size - 1
+      runnable = migrations[start..finish]
+      
+      # skip the last migration if we're headed down, but not ALL the way down
+      runnable.pop if down? && !target.nil?
+      
+      runnable.each do |migration|
+        Base.logger.info "Migrating to #{migration} (#{migration.version})"
+
+        # On our way up, we skip migrating the ones we've already migrated
+        # On our way down, we skip reverting the ones we've never migrated
+        next if up? && migrated.include?(migration.version.to_i)
+
+        if down? && !migrated.include?(migration.version.to_i)
+          migration.announce 'never migrated, skipping'; migration.write
+        else
+          migration.migrate(@direction)
+          record_version_state_after_migrating(migration.version)
         end
+      end
+    end
 
-        next if irrelevant_migration?(migration_class.version)
+    def migrations
+      @migrations ||= begin
+        files = Dir["#{@migrations_path}/[0-9]*_*.rb"]
+        
+        migrations = files.inject([]) do |klasses, file|
+          version, name = file.scan(/([0-9]+)_([_a-z0-9]*).rb/).first
+          
+          raise IllegalMigrationNameError.new(file) unless version
+          version = version.to_i
+          
+          if klasses.detect { |m| m.version == version }
+            raise DuplicateMigrationVersionError.new(version) 
+          end
 
-        Base.logger.info "Migrating to #{migration_class} (#{migration_class.version})"
-        migration_class.migrate(@direction)
-        set_schema_version(migration_class.version)
+          if klasses.detect { |m| m.name == name.camelize }
+            raise DuplicateMigrationNameError.new(name.camelize) 
+          end
+          
+          load(file)
+          
+          klasses << returning(name.camelize.constantize) do |klass|
+            class << klass; attr_accessor :version end
+            klass.version = version
+          end
+        end
+        
+        migrations = migrations.sort_by(&:version)
+        down? ? migrations.reverse : migrations
       end
     end
 
     def pending_migrations
-      migration_classes.select { |m| m.version > current_version }
+      already_migrated = migrated
+      migrations.reject { |m| already_migrated.include?(m.version.to_i) }
     end
 
-    private
-      def migration_classes
-        classes = migration_files.inject([]) do |migrations, migration_file|
-          load(migration_file)
-          version, name = migration_version_and_name(migration_file)
-          assert_unique_migration_version(migrations, version.to_i)
-          migrations << migration_class(name, version.to_i)
-        end.sort_by(&:version)
-
-        down? ? classes.reverse : classes
-      end
+    def migrated
+      sm_table = self.class.schema_migrations_table_name
+      Base.connection.select_values("SELECT version FROM #{sm_table}").map(&:to_i).sort
+    end
 
-      def assert_unique_migration_version(migrations, version)
-        if !migrations.empty? && migrations.find { |m| m.version == version }
-          raise DuplicateMigrationVersionError.new(version)
-        end
-      end
+    private
+      def record_version_state_after_migrating(version)
+        sm_table = self.class.schema_migrations_table_name
 
-      def migration_files
-        files = Dir["#{@migrations_path}/[0-9]*_*.rb"].sort_by do |f|
-          m = migration_version_and_name(f)
-          raise IllegalMigrationNameError.new(f) unless m
-          m.first.to_i
+        if down?
+          Base.connection.update("DELETE FROM #{sm_table} WHERE version = '#{version}'")
+        else
+          Base.connection.insert("INSERT INTO #{sm_table} (version) VALUES ('#{version}')")
         end
-        down? ? files.reverse : files
-      end
-
-      def migration_class(migration_name, version)
-        klass = migration_name.camelize.constantize
-        class << klass; attr_accessor :version end
-        klass.version = version
-        klass
-      end
-
-      def migration_version_and_name(migration_file)
-        return *migration_file.scan(/([0-9]+)_([_a-z0-9]*).rb/).first
-      end
-
-      def set_schema_version(version)
-        Base.connection.update("UPDATE #{self.class.schema_info_table_name} SET version = #{down? ? version.to_i - 1 : version.to_i}")
       end
 
       def up?
@@ -403,14 +492,5 @@ module ActiveRecord
       def down?
         @direction == :down
       end
-
-      def reached_target_version?(version)
-        return false if @target_version == nil
-        (up? && version.to_i - 1 >= @target_version) || (down? && version.to_i <= @target_version)
-      end
-
-      def irrelevant_migration?(version)
-        (up? && version.to_i <= current_version) || (down? && version.to_i > current_version)
-      end
   end
 end

data/lib/active_record/named_scope.rb

@@ -0,0 +1,163 @@
+module ActiveRecord
+  module NamedScope
+    # All subclasses of ActiveRecord::Base have two named_scopes:
+    # * <tt>all</tt>, which is similar to a <tt>find(:all)</tt> query, and
+    # * <tt>scoped</tt>, which allows for the creation of anonymous scopes, on the fly: <tt>Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions)</tt>
+    #
+    # These anonymous scopes tend to be useful when procedurally generating complex queries, where passing
+    # intermediate values (scopes) around as first-class objects is convenient.
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        named_scope :scoped, lambda { |scope| scope }
+      end
+    end
+
+    module ClassMethods
+      def scopes
+        read_inheritable_attribute(:scopes) || write_inheritable_attribute(:scopes, {})
+      end
+
+      # Adds a class method for retrieving and querying objects. A scope represents a narrowing of a database query,
+      # such as <tt>:conditions => {:color => :red}, :select => 'shirts.*', :include => :washing_instructions</tt>.
+      #
+      #   class Shirt < ActiveRecord::Base
+      #     named_scope :red, :conditions => {:color => 'red'}
+      #     named_scope :dry_clean_only, :joins => :washing_instructions, :conditions => ['washing_instructions.dry_clean_only = ?', true]
+      #   end
+      # 
+      # The above calls to <tt>named_scope</tt> define class methods <tt>Shirt.red</tt> and <tt>Shirt.dry_clean_only</tt>. <tt>Shirt.red</tt>, 
+      # in effect, represents the query <tt>Shirt.find(:all, :conditions => {:color => 'red'})</tt>.
+      #
+      # Unlike Shirt.find(...), however, the object returned by <tt>Shirt.red</tt> is not an Array; it resembles the association object
+      # constructed by a <tt>has_many</tt> declaration. For instance, you can invoke <tt>Shirt.red.find(:first)</tt>, <tt>Shirt.red.count</tt>,
+      # <tt>Shirt.red.find(:all, :conditions => {:size => 'small'})</tt>. Also, just
+      # as with the association objects, name scopes acts like an Array, implementing Enumerable; <tt>Shirt.red.each(&block)</tt>,
+      # <tt>Shirt.red.first</tt>, and <tt>Shirt.red.inject(memo, &block)</tt> all behave as if Shirt.red really were an Array.
+      #
+      # These named scopes are composable. For instance, <tt>Shirt.red.dry_clean_only</tt> will produce all shirts that are both red and dry clean only.
+      # Nested finds and calculations also work with these compositions: <tt>Shirt.red.dry_clean_only.count</tt> returns the number of garments
+      # for which these criteria obtain. Similarly with <tt>Shirt.red.dry_clean_only.average(:thread_count)</tt>.
+      #
+      # All scopes are available as class methods on the ActiveRecord::Base descendent upon which the scopes were defined. But they are also available to
+      # <tt>has_many</tt> associations. If,
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :shirts
+      #   end
+      #
+      # then <tt>elton.shirts.red.dry_clean_only</tt> will return all of Elton's red, dry clean
+      # only shirts.
+      #
+      # Named scopes can also be procedural.
+      #
+      #   class Shirt < ActiveRecord::Base
+      #     named_scope :colored, lambda { |color|
+      #       { :conditions => { :color => color } }
+      #     }
+      #   end
+      #
+      # In this example, <tt>Shirt.colored('puce')</tt> finds all puce shirts.
+      #
+      # Named scopes can also have extensions, just as with <tt>has_many</tt> declarations:
+      #
+      #   class Shirt < ActiveRecord::Base
+      #     named_scope :red, :conditions => {:color => 'red'} do
+      #       def dom_id
+      #         'red_shirts'
+      #       end
+      #     end
+      #   end
+      #
+      #
+      # For testing complex named scopes, you can examine the scoping options using the
+      # <tt>proxy_options</tt> method on the proxy itself.
+      #
+      #   class Shirt < ActiveRecord::Base
+      #     named_scope :colored, lambda { |color|
+      #       { :conditions => { :color => color } }
+      #     }
+      #   end
+      #
+      #   expected_options = { :conditions => { :colored => 'red' } }
+      #   assert_equal expected_options, Shirt.colored('red').proxy_options
+      def named_scope(name, options = {}, &block)
+        scopes[name] = lambda do |parent_scope, *args|
+          Scope.new(parent_scope, case options
+            when Hash
+              options
+            when Proc
+              options.call(*args)
+          end, &block)
+        end
+        (class << self; self end).instance_eval do
+          define_method name do |*args|
+            scopes[name].call(self, *args)
+          end
+        end
+      end
+    end
+    
+    class Scope
+      attr_reader :proxy_scope, :proxy_options
+
+      [].methods.each do |m|
+        unless m =~ /(^__|^nil\?|^send|^object_id$|class|extend|find|count|sum|average|maximum|minimum|paginate|first|last|empty?)/
+          delegate m, :to => :proxy_found
+        end
+      end
+
+      delegate :scopes, :with_scope, :to => :proxy_scope
+
+      def initialize(proxy_scope, options, &block)
+        [options[:extend]].flatten.each { |extension| extend extension } if options[:extend]
+        extend Module.new(&block) if block_given?
+        @proxy_scope, @proxy_options = proxy_scope, options.except(:extend)
+      end
+
+      def reload
+        load_found; self
+      end
+
+      def first(*args)
+        if args.first.kind_of?(Integer) || (@found && !args.first.kind_of?(Hash))
+          proxy_found.first(*args)
+        else
+          find(:first, *args)
+        end
+      end
+
+      def last(*args)
+        if args.first.kind_of?(Integer) || (@found && !args.first.kind_of?(Hash))
+          proxy_found.last(*args)
+        else
+          find(:last, *args)
+        end
+      end
+
+      def empty?
+        @found ? @found.empty? : count.zero?
+      end
+
+      protected
+      def proxy_found
+        @found || load_found
+      end
+
+      private
+      def method_missing(method, *args, &block)
+        if scopes.include?(method)
+          scopes[method].call(self, *args)
+        else
+          with_scope :find => proxy_options do
+            proxy_scope.send(method, *args, &block)
+          end
+        end
+      end
+
+      def load_found
+        @found = find(:all)
+      end
+    end
+  end
+end