partitioned 0.8.0 → 1.0.1

data/lib/partitioned/partitioned_base/configurator/dsl.rb

@@ -4,22 +4,22 @@ module Partitioned
       #
       # The Domain Specific Language manager for configuring partitioning.
       #
-      # example:
+      # @example of use:
       #
-      # class Employee < Partitioned::ByCreatedAt
-      #   partitioned do |partition|
-      #     partition.index :id, :unique => true
-      #     partition.foreign_key :company_id
+      #   class Employee < Partitioned::ByCreatedAt
+      #     partitioned do |partition|
+      #       partition.index :id, :unique => true
+      #       partition.foreign_key :company_id
+      #     end
       #   end
-      # end
       #
-      # in the above example, block:
+      #   in the above example, block:
       #
-      #   partitioned do |partition|
-      #      ...
-      #   end
+      #     partitioned do |partition|
+      #        ...
+      #     end
       #
-      # Scopes a set of "partition directives".  The directives are accessed via the block parameter 'partition'
+      #   Scopes a set of "partition directives".  The directives are accessed via the block parameter 'partition'
       #
       # Directives parameters have two forms, a canonical form which takes a set of parameters
       # and a dynamic form which takes a single parameter which is either a string that should be interpolated or
@@ -36,10 +36,11 @@ module Partitioned
       #   end
       #
       #   partitioned do |partition|
-      #     partition.on lambda{|model| return model.partition_time_field}
+      #     partition.on lambda{ |model| return model.partition_time_field}
       #     partition.constraint lambda{|model,time_field_value|
-      #                                 return "#{model.partition_time_field} >= '#{time_field_value.strftime}' and #{model.partition_time_field} < '#{(time_field_value + 1.day).strftime}'"
-      #                                }
+      #       return "#{model.partition_time_field} >= '#{time_field_value.strftime}' and
+      #         #{model.partition_time_field} < '#{(time_field_value + 1.day).strftime}'"
+      #     }
       #   end
       # end
       #
@@ -134,6 +135,9 @@ module Partitioned
       # resolve to FavoriteEmployee.index_field and be :baz as expected.
       #
       class Dsl
+        #
+        # raised when a partitioned DSL directive's parameters are considered invalid
+        #
         class InvalidConfiguratorDirectiveValue < StandardError
           def initialize(model, table_name, directive, value, explanation)
             super("#{model.name} [#{table_name}] invalid value '#{value}' for partitioned directive '#{directive}'.  #{explanation}")
@@ -254,7 +258,8 @@ module Partitioned
           if referencing_field.is_a? Proc
             data.foreign_keys << referencing_field
           else
-            data.foreign_keys << Partitioned::PartitionedBase::Configurator::Data::ForeignKey.new(referencing_field, referenced_table, referenced_field)
+            data.foreign_keys << Partitioned::PartitionedBase::Configurator::Data::ForeignKey.
+                                    new(referencing_field, referenced_table, referenced_field)
           end
         end
 

data/lib/partitioned/partitioned_base/configurator/reader.rb

@@ -1,6 +1,9 @@
 module Partitioned
   class PartitionedBase
     module Configurator
+      # coalesces and parses all {Data} objects allowing the
+      # {PartitionManager} to request partitioning information froma
+      # centralized source.
       class Reader
         attr_reader :model
 

data/lib/partitioned/partitioned_base/configurator.rb

@@ -1,5 +1,9 @@
 module Partitioned
   class PartitionedBase < ActiveRecord::Base
+    # the configuration manager for partitioning.
+    # it supports, the front-end UI (a DSL) using {Dsl}
+    # state using {Data}
+    # and a parser using {Reader}
     module Configurator
     end
   end

data/lib/partitioned/partitioned_base/partition_manager.rb

@@ -1,3 +1,5 @@
+require 'forwardable'
+
 module Partitioned
   class PartitionedBase
     #
@@ -13,7 +15,7 @@ module Partitioned
       end
 
       #
-      # drop partitions that are no longer necessary.
+      # Drop partitions that are no longer necessary.
       # uses #old_partition_key_values_set as the list of
       # partitions to remove.
       #
@@ -24,7 +26,7 @@ module Partitioned
       end
 
       #
-      # create partitions that are needed (probably to handle data that
+      # Create partitions that are needed (probably to handle data that
       # will be inserted into the database within the next few weeks).
       # uses #new_partition_key_value_set to determine the key values
       # for the specific child tables to create.
@@ -36,7 +38,7 @@ module Partitioned
       end
 
       #
-      # create any partition tables from a list.  the partition tables must
+      # Create any partition tables from a list.  the partition tables must
       # not already exist and its schema must already exist.
       #
       def create_new_partition_tables(enumerable)
@@ -46,7 +48,7 @@ module Partitioned
       end
 
       #
-      # the once called function to prepare a parent table for partitioning as well
+      # The once called function to prepare a parent table for partitioning as well
       # as create the schema that the child tables will be placed in.
       #
       def create_infrastructure
@@ -56,41 +58,41 @@ module Partitioned
 
       protected
       #
-      # an array of key values (each key value is an array of keys) that represent
+      # An array of key values (each key value is an array of keys) that represent
       # the child partitions that should be created.
       #
-      # used by #create_new_partitions and generally called once a day to update
-      # the database with new soon-to-be needed child tables
+      # Used by #create_new_partitions and generally called once a day to update
+      # the database with new soon-to-be needed child tables.
       #
-      # typically overridden by the concrete class as this is pure business logic
+      # Typically overridden by the concrete class as this is pure business logic.
       #
       def new_partition_key_values_set
         []
       end
 
       #
-      # an array of key values (each key value is an array of keys) that represent
+      # An array of key values (each key value is an array of keys) that represent
       # the child partitions that should be dropped because they are no longer needed.
       #
-      # used by #drop_old_partitions and generally called once a day to clean up
-      # unneeded child tables
+      # Used by #drop_old_partitions and generally called once a day to clean up
+      # unneeded child tables.
       #
-      # typically overridden by the concrete class as this is pure business logic
+      # Typically overridden by the concrete class as this is pure business logic.
       #
       def old_partition_key_values_set
         []
       end
 
       #
-      # remove a specific partition from the database given
-      # the key value(s) of its check constraint columns
+      # Remove a specific partition from the database given
+      # the key value(s) of its check constraint columns.
       #
       def drop_old_partition(*partition_key_values)
         drop_partition_table(*partition_key_values)
       end
 
       #
-      # create a specific child table that does not currently
+      # Create a specific child table that does not currently
       # exist and whose schema (the schema that the table exists in)
       # also already exists (#create_infrastructure is designed to
       # create this).

data/lib/partitioned/partitioned_base/sql_adapter.rb

@@ -1,3 +1,5 @@
+require 'forwardable'
+
 module Partitioned
   class PartitionedBase
     #
@@ -12,7 +14,7 @@ module Partitioned
       end
 
       #
-      # ensure our function for warning about improper partition usage is in place
+      # Ensure our function for warning about improper partition usage is in place.
       #
       # Name: always_fail_on_insert(text); Type: FUNCTION; Schema: public
       #
@@ -43,7 +45,7 @@ module Partitioned
       end
 
       #
-      # does a specific child partition exist
+      # Does a specific child partition exist.
       #
       def partition_exists?(*partition_key_values)
         return find(:first,
@@ -56,22 +58,22 @@ module Partitioned
       end
 
       #
-      # returns an array of partition table names from last to first limited to
+      # Returns an array of partition table names from last to first limited to
       # the number of entries requested by its first parameter.
       #
-      # the magic here is in the overridden method "last_n_partitions_order_by_clause"
+      # The magic here is in the overridden method "last_n_partitions_order_by_clause"
       # which is designed to order a list of partition table names (table names without
       # their schema name) from last to first.
       #
-      # if the child table names are the format "pYYYYMMDD" where YYYY is a four digit year, MM is
+      # If the child table names are the format "pYYYYMMDD" where YYYY is a four digit year, MM is
       # a month number and DD is a day number, you would use the following to order from last to
       # first:
       #   tablename desc
       #
-      # for child table names of the format "pXXXX" where XXXX is a number, you may want something like:
+      # For child table names of the format "pXXXX" where XXXX is a number, you may want something like:
       #   substring(tablename, 2)::integer desc
       #
-      # for clarity, the sql executed is:
+      # For clarity, the sql executed is:
       #    select tablename from pg_tables where schemaname = $1 order by $2 limit $3
       # where:
       #  $1 = the name of schema (foos_partitions)
@@ -88,18 +90,18 @@ module Partitioned
       end
 
       #
-      # override this or order the tables from last (greatest value? greatest date?) to first
+      # Override this or order the tables from last (greatest value? greatest date?) to first.
       #
       def last_n_partitions_order_by_clause
         return configurator.last_n_partitions_order_by_clause
       end
 
       #
-      # used to create the parent table rule to ensure
+      # Used to create the parent table rule to ensure.
       #
-      # this will cause an error on attempt to insert into the parent table
+      # This will cause an error on attempt to insert into the parent table.
       #
-      # we want all records to exist in one of the child tables so the
+      # We want all records to exist in one of the child tables so the
       # query planner can optimize access to the records.
       #
       def add_parent_table_rules(*partition_key_values)
@@ -118,14 +120,14 @@ module Partitioned
       end
 
       #
-      # the name of the table (schemaname.childtablename) given the check constraint values.
+      # The name of the table (schemaname.childtablename) given the check constraint values.
       #
       def partition_table_name(*partition_key_values)
         return configurator.table_name(*partition_key_values)
       end
 
       #
-      # create a single child table.
+      # Create a single child table.
       #
       def create_partition_table(*partition_key_values)
         create_table(configurator.table_name(*partition_key_values), {
@@ -137,14 +139,14 @@ module Partitioned
       end
 
       #
-      # remove a specific single child table
+      # Remove a specific single child table.
       #
       def drop_partition_table(*partition_key_values)
         drop_table(configurator.table_name(*partition_key_values))
       end
 
       #
-      # add indexes that must exist on child tables.  Only leaf child tables
+      # Add indexes that must exist on child tables. Only leaf child tables
       # need indexes as parent table indexes are not used in postgres.
       #
       def add_partition_table_index(*partition_key_values)
@@ -159,31 +161,31 @@ module Partitioned
       end
 
       #
-      # used when creating the name of a SQL rule
+      # Used when creating the name of a SQL rule.
       #
       def parent_table_rule_name(name, suffix = "rule", *partition_key_values)
         return "#{configurator.parent_table_name(*partition_key_values).gsub(/[.]/, '_')}_#{name}_#{suffix}"
       end
 
       #
-      # used to create index names
+      # Used to create index names.
       #
       def index_name(name, *partition_key_values)
         return "#{configurator.part_name(*partition_key_values)}_#{name}_idx"
       end
 
       #
-      # used to create index names
+      # Used to create index names.
       #
       def unique_index_name(name, *partition_key_values)
         return "#{configurator.part_name(*partition_key_values)}_#{name}_udx"
       end
 
       #
-      # this is here for derived classes to set up references to added columns
+      # This is here for derived classes to set up references to added columns
       # (or columns in the parent that need foreign key constraints).
       #
-      # foreign keys are not inherited in postgres.  So, a parent table
+      # Foreign keys are not inherited in postgres. So, a parent table
       # of the form:
       #
       #   -- this is the referenced table
@@ -211,12 +213,12 @@ module Partitioned
       #   create table employees_of_company_2 ( CHECK ( company_id = 2 ) ) INHERITS (employees);
       #   create table employees_of_company_3 ( CHECK ( company_id = 3 ) ) INHERITS (employees);
       #
-      # since postgres does not inherit referential integrity from parent tables, the following
+      # Since postgres does not inherit referential integrity from parent tables, the following
       # insert will work:
       #    insert into employees_of_company_1 (name, company_id, supervisor_id) values ('joe', 1, 10);
       # even if there is no record in companies with id = 1 and there is no record in employees with id = 10
       #
-      # for proper referential integrity handling you must do the following:
+      # For proper referential integrity handling you must do the following:
       #   ALTER TABLE employees_of_company_1 add foreign key (company_id) references companies(id)
       #   ALTER TABLE employees_of_company_2 add foreign key (company_id) references companies(id)
       #   ALTER TABLE employees_of_company_3 add foreign key (company_id) references companies(id)
@@ -225,7 +227,7 @@ module Partitioned
       #   ALTER TABLE employees_of_company_2 add foreign key (supervisor_id) references employees_of_company_2(id)
       #   ALTER TABLE employees_of_company_3 add foreign key (supervisor_id) references employees_of_company_3(id)
       #
-      # the second set of alter tables brings up a good another consideration about postgres references and partitions.
+      # The second set of alter tables brings up a good another consideration about postgres references and partitions.
       # postgres will not follow references to a child table.  So, a foreign key reference to "employees" in this
       # set of alter statements would not work because postgres would expect the table "employees" to have
       # the specific referenced record, but the record really exists in a child of employees.  So, the alter statement