database_transform 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5260295aa827b58fa3504b901e310810dfb36a4a
-  data.tar.gz: f15c12e08f7b6b736af4dc86e1d97ae0b33cd394
+  metadata.gz: f2ae47980a59f3120da84d3ed32be29f920f491f
+  data.tar.gz: 44077ed24f2f94f104acddcdb581b57db714665e
 SHA512:
-  metadata.gz: 8c1d1982ff7532f8a7d21ab1c5541aa1169830bdcf07acecf14e8f5976d0a5d40ad498e4d48d17a3f0c32781a0657802ca1f937ce1c0cf79aeb6b737d657a069
-  data.tar.gz: 51a77ad4b478b66270af5f4e974da544a431886d49b146f154e485e1564314d37cf3c65e7dcfbb13155eb64f4a420cbfbe00f20fcf135f5f8568cf7d3aa098b0
+  metadata.gz: a1d3934645c04b7213a10edab6f2aba18c655c87a971492f8ca5b73729974b71f1e1ba07b2039c2cd3bd0c6b2c458acb03afb23f629ede4501818c9dee71e6b1
+  data.tar.gz: 1aad272a4278423cf5b90819011c24b948e89a9d98b790c1da31064b84d802bcdd0bcee5e7d656dcdceb04078a4557ac7e2901e6ae3437e77ae6affc140835eb

data/README.md

@@ -32,7 +32,7 @@ Or install it yourself as:
 
 ## Usage
 
-Database Transform is built with ActiveRecord in mind. First, define a new database conndtion to the old database in
+Database Transform is built with ActiveRecord in mind. First, define a new database connection to the old database in
 database.yml:
 
 ```yaml
@@ -67,46 +67,62 @@ end
 
 A summary of methods:
 
- - `transform_table` tells Database Transform to perform the given transform over records in the given source table.
-   - The first argument is the table to transform. This can be a symbol, string, or an ActiveRecord model.
-   - `to` specifies the new table to transform to. This can be a symbol, string, or an ActiveRecord model.
-     - If either argument is a symbol or string, an ActiveRecord model is generated which allows access to the record's
-       data.
-       - Source models are found in the Source namespace, and can be used as the `posts.uid` column above.
-       - Destination models are found in the Destination namespace.
-     - In all cases, the model will have extra accessory methods:
-       - `transform(old_primary_key)`: This takes a primary key in the source table, and returns the transformed object.
-         This only returns a valid result after the object has been transformed.
-       - `transformed?(old_primary_key)`: This checks if the object has been transformed.
-   - `default_scope` allows the programmer to specify the records to transform
- - `primary_key` declares the name of column with the primary key. This allows later access when relations need to be
-    mapped.
- - `column` declares how to transform the contents of that column from the old database to the new one.
-   - If `to:` is omitted, then it is assumed that the transfer function is the identity function, and the column would
-     map across as the same name.
-   - If `null: false` is specified, the value assigned to the column (in `to`) will be checked for nullity.
-   - A block can be provided.
-     - If so, then the data from the old record is passed to the block as the first argument
-     - In the context of the block, `self` refers to the new record.
-     - `self` has an additional attribute `source_record` which refers to the old record. (TODO)
-     - `self` has an additional attribute `schema` which refers to the transformation schema. (TODO)
- - `save` declares whether the new record should be saved.
-   - `if` and `unless` accepts a block which will be evaluated to determine if the record should be saved.
-   - `validate` will allow the record to be saved bypassing validations. This defaults to `true`.
+- `transform_table` tells Database Transform to perform the given transform over records in the given source table.
+    - The first argument is the table to transform. This can be a symbol, string, or an ActiveRecord model.
+    - `to` specifies the new table to transform to. This can be a symbol, string, or an ActiveRecord model.
+        - If either argument is a symbol or string, an ActiveRecord model is generated which allows access to the
+          record's data.
+            - Source models are found in the Source namespace, and can be used as the `posts.uid` column above.
+            - Destination models are found in the Destination namespace.
+        - In all cases, the model will have extra accessory methods:
+            - `transform(old_primary_key)`: This takes a primary key in the source table, and returns the transformed
+              object. This only returns a valid result after the object has been transformed.
+            - `transformed?(old_primary_key)`: This checks if the object has been transformed.
+    - `default_scope` allows the programmer to specify the records to transform
+- `primary_key` declares the name of column with the primary key. This allows later access when relations need to be
+  mapped.
+    - Use the `transform` and `transformed?` methods on the model to obtain the transformed object.
+- `column` declares how to transform the contents of that column from the old database to the new one.
+    - If `to:` is omitted, then it is assumed that the transfer function is the identity function, and the column would
+      map across as the same name.
+    - If `null: false` is specified, the value assigned to the column (in `to`) will be checked for nullity.
+    - A block can be provided.
+        - If so, then the data from the old record is passed to the block as the first argument
+        - In the context of the block, `self` refers to the new record.
+        - `self` has an additional attribute `source_record` which refers to the old record.
+        - `self` has an additional attribute `schema` which refers to the transformation schema.
+- `save` declares whether the new record should be saved.
+    - `if` and `unless` accepts a block which will be evaluated to determine if the record should be saved.
+    - `validate` will allow the record to be saved bypassing validations. This defaults to `true`.
 
 Finally, execute the Rake task:
 
-    $ rake db:transform my_old_app
+    $ rake db:transform[my_old_app]
 
 And the schema (`MyOldAppSchema`) and database connection (via `my_old_app_production`) will be established for you. A
 few variants of the schema name will be checked:
 
- - my_old_app
- - my_old_app_production
+- my_old_app
+- my_old_app_production
 
 Only the *source* schema will be annotated to use the other connection. The *destination* schema will be used through
 the application's normal configuration (i.e. depends on the value of `ENV['RAILS_ENV']`.)
 
+Additional arguments can be passed to the schema. All arguments specified in the Rake command following the schema name
+will be passed to the initialiser of the schema.
+
+```ruby
+class MyOldAppWithArgumentsSchema < DatabaseTransform::Schema
+  def initialize(uploads_path)
+    @uploads_path = uploads_path
+  end
+end
+```
+
+    $ rake db:transform[my_old_app_with_arguments,/home/joel/server/dumps/path]
+
+These arguments then can be used from within any transform blocks by accessing the `schema` property.
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/database_transform/fork )

data/lib/database_transform/schema.rb

@@ -114,7 +114,7 @@ class DatabaseTransform::Schema
       end
       next unless unmet_dependencies.empty?
 
-      table_config[:transform].run_transform
+      table_config[:transform].run_transform(self)
       transformed_this_pass << table
     end
 

data/lib/database_transform/schema_table.rb

@@ -66,6 +66,8 @@ class DatabaseTransform::SchemaTable
   #   together with if.
   # @option options [Proc] if A proc to call. The record will be saved if the proc returns a true value. This cannot be
   #   used together with unless.
+  # @option options [Boolean] validate Whether to run the model validations when saving the transformed record. Defaults
+  #   to true.
   def save(options = {})
     raise ArgumentError.new('unless and if cannot be both specified') if options[:unless] && options[:if]
     raise ArgumentError.new('Cannot specify a save clause twice for the same table') if @save
@@ -74,21 +76,24 @@ class DatabaseTransform::SchemaTable
       clause = options.delete(:unless)
       options[:if] = ->(*callback_args) { !self.instance_exec(*callback_args, &clause) }
     end
+    options[:validate] = true unless options.has_key?(:validate)
 
     @save = options
   end
 
   # @api private
   #   To be called only by Schema#run_transform
-  def run_transform
+  def run_transform(schema = nil)
     before_message =
       if @destination
-        format("-- transforming '%s' to '%s'\n", @source.table_name, @destination.table_name)
+        format("-- transforming '%s' to '%s'", @source.table_name, @destination.table_name)
       else
-        format("-- transforming '%s'\n", @source.table_name)
+        format("-- transforming '%s'", @source.table_name)
       end
 
-    time_block(before_message, "   -> %fs\n", &method(:transform!))
+    time_block(before_message, "   -> %fs") do
+      transform!(schema)
+    end
   end
 
   private
@@ -109,37 +114,39 @@ class DatabaseTransform::SchemaTable
   # @yield The block to time.
   def time_block(before, after, &proc)
     start = Time.now
-    $stderr.puts(before)
-
-    result = proc.call
-
-    complete = Time.now - start
-    $stderr.printf(after, complete)
-
-    result
+    $stderr.printf("%s\n", before)
+
+    proc.call
+  rescue Exception
+    $stderr.printf("%s (error)\n", format(after, Time.now - start))
+    raise
+  else
+    $stderr.printf("%s\n", format(after, Time.now - start))
   end
 
   # Performs the transform with the given parameters.
   #
+  # @param [DatabaseTransform::Schema] schema The schema being transformed.
   # @return [Void]
-  def transform!
+  def transform!(schema)
     # For each item in the old model
     default_scope = @default_scope || @source.method(:all)
     @source.instance_exec(&default_scope).each do |record|
-      transform_record!(record)
+      transform_record!(schema, record)
     end
   end
 
   # Transforms one record from the source model to the destination.
   #
+  # @param [DatabaseTransform::Schema] schema The schema being transformed.
   # @param [ActiveRecord::Base] old The record to map.
   # @return [Void]
-  def transform_record!(old)
+  def transform_record!(schema, old)
     # Instantiate a new model record
     new = @destination.new if @destination
 
     # Map the columns over
-    transform_record_columns!(old, new)
+    transform_record_columns!(schema, old, new)
     return if new.nil? || new.frozen?
 
     save_transformed_record(old, new)
@@ -147,14 +154,15 @@ class DatabaseTransform::SchemaTable
 
   # Applies the column transforms over the old record to the new record.
   #
+  # @param [DatabaseTransform::Schema] schema The schema being transformed.
   # @param [ActiveRecord::Base] old The record to map.
   # @param [ActiveRecord::Base] new The record to map to.
   # @return [Void]
-  def transform_record_columns!(old, new)
+  def transform_record_columns!(schema, old, new)
     @columns.each do |column|
       fail ArgumentError.new unless column.is_a?(Hash)
 
-      new_value = transform_record_field!(old, new, column[:from], column[:block])
+      new_value = transform_record_field!(schema, old, new, column[:from], column[:block])
 
       unless new.nil?
         break if new.frozen?
@@ -167,12 +175,13 @@ class DatabaseTransform::SchemaTable
 
   # Transforms one record's field.
   #
+  # @param [DatabaseTransform::Schema] schema The schema being transformed.
   # @param [ActiveRecord::Base] source The source row to map the values for.
   # @param [ActiveRecord::Base] destination The destination row to map the values to.
   # @param [Array<Symbol>] from The source columns to be used to map to the destination column.
   # @param [Proc, nil] block The block to transform the source values to the destination value.
   # @return The result of applying the transform over the input values.
-  def transform_record_field!(source, destination, from = nil, block = nil)
+  def transform_record_field!(schema, source, destination, from = nil, block = nil)
     # Get the old record column values (can be a block taking multiple arguments)
     new_values = from.map { |k| source.send(k) }
 
@@ -181,15 +190,29 @@ class DatabaseTransform::SchemaTable
       new_values.first
     elsif destination
       # Map the value if necessary.
-      # TODO: Provide the schema instance to the callback.
-      #       We should ensure that the block has a way to access the schema.
-      destination.instance_exec(*new_values, &block)
+      execute_transform_block!(schema, source, destination, block, new_values)
     else
       # Call the proc
-      block.call(*new_values)
+      execute_transform_block!(schema, source, Object.new, block, new_values)
     end
   end
 
+  # Executes the given transform block.
+  #
+  # This allows the transform to be given an appropriate value of self such that it can access the old record and the schema being used.
+  #
+  # @param [DatabaseTransform::Schema] schema The schema being transformed.
+  # @param [ActiveRecord::Base] source_record The old record being transformed.
+  # @param self_ The object to use as self in the context of the block.
+  # @param [Proc] block The block to execute.
+  # @param [Array] args The arguments to give to the block.
+  # @return The result of applying the block.
+  def execute_transform_block!(schema, source_record, self_, block, args)
+    self_.define_singleton_method(:source_record) { source_record } unless self_.respond_to?(:source_record)
+    self_.define_singleton_method(:schema) { schema } unless self_.respond_to?(:schema)
+    self_.instance_exec(*args, &block)
+  end
+
   # Assigns the transformed value to the new record, raising an argument error if the field was declared to not be
   # nullable and the value is null.
   #
@@ -216,9 +239,9 @@ class DatabaseTransform::SchemaTable
   def save_transformed_record(old, new)
     # Save. Skip if the conditional callback is given
     return if @save && @save[:if] && !new.instance_exec(&@save[:if])
+    validate = @save ? @save[:validate] : nil
 
-    # TODO: Make validation optional using the save clause.
-    new.save!(validate: false) unless new.destroyed?
+    new.save!(validate: validate != false) unless new.destroyed?
     @source.memoize_transform(old.send(@primary_key), new) if @primary_key
   end
 end

data/lib/database_transform/tasks/transform.rake

@@ -1,35 +1,34 @@
-# This class just loads the file containing the schema definition and hands off control to the schema.
-class DatabaseTransform::Transform
-  def initialize(args)
-    @schema = args.schema_name
-    @extra_args = args.extras
-    run
-  end
-
-  def run
-    import_schema
-    schema = @schema.constantize.new
-
-    ActiveRecord::Base.logger = Logger.new('log/import.log')
-    schema.transform!
-  end
-
-  private
-
-  def import_schema
-    schema_file = @schema.underscore
-    begin
-      return require(File.join(Rails.root, 'db', 'transforms', schema_file))
-    rescue LoadError
-    end
-
-    require (File.join(Rails.root, 'db', 'transforms', schema_file, schema_file))
-  end
-end
-
-namespace :db do
-  desc 'Transform old database schemas'
-  task :transform, [:schema_name] => :environment do |_, args|
-    DatabaseTransform::Transform.new(args)
-  end
-end
+# This class just loads the file containing the schema definition and hands off control to the schema.
+class DatabaseTransform::Transform
+  def initialize(args)
+    @schema = args.schema_name
+    @argv = args.extras
+  end
+
+  def run
+    require_schema
+    schema = @schema.camelize.constantize.new(*@argv)
+
+    ActiveRecord::Base.logger = Logger.new('log/import.log')
+    schema.transform!
+  end
+
+  private
+
+  def require_schema
+    schema_file = @schema.underscore
+    begin
+      return require(File.join(Rails.root, 'db', 'transforms', schema_file))
+    rescue LoadError
+    end
+
+    require (File.join(Rails.root, 'db', 'transforms', schema_file, schema_file))
+  end
+end
+
+namespace :db do
+  desc 'Transform old database schemas'
+  task :transform, [:schema_name] => :environment do |_, args|
+    DatabaseTransform::Transform.new(args).run
+  end
+end

data/lib/database_transform/version.rb

@@ -1,3 +1,3 @@
 module DatabaseTransform
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: database_transform
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Joel Low
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-28 00:00:00.000000000 Z
+date: 2015-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport