partitioned 0.8.0

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

@@ -0,0 +1,628 @@
+module Partitioned
+  class PartitionedBase
+    module Configurator
+      #
+      # The Domain Specific Language manager for configuring partitioning.
+      #
+      # example:
+      #
+      # class Employee < Partitioned::ByCreatedAt
+      #   partitioned do |partition|
+      #     partition.index :id, :unique => true
+      #     partition.foreign_key :company_id
+      #   end
+      # end
+      #
+      # in the above example, block:
+      #
+      #   partitioned do |partition|
+      #      ...
+      #   end
+      #
+      # 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
+      # a lambda.
+      #
+      # The dynamic forms are expected to return some value(s), similar to the canonical form.
+      #
+      # DYNAMIC FORM: LAMBDA
+      # Lambdas have passed (sometimes) one and (sometimes) two parameters (depending on the directives requirements), as in:
+      #
+      # class Employee < Partitioned::Base
+      #   def self.partition_time_field
+      #     return :created_at
+      #   end
+      #
+      #   partitioned do |partition|
+      #     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}'"
+      #                                }
+      #   end
+      # end
+      #
+      # Single parameter lambdas are passed the most derived Partitioned::PartitionedBase class that defines the
+      # model of this partitioned table:
+      #    lambda {|model| return nil}
+      #
+      # Arguments:
+      #  model - the Partitioned::PartitionedBase class that is being partitioned.
+      #
+      # Multi parameter lambdas are passed the model being partitioned and the values to specify a single child table.
+      #    lambda {|model,*partition_key_values| return nil}
+      #
+      # Arguments:
+      #  model - the Partitioned::PartitionedBase class that is being partitioned.
+      #  *partition_key_values - the values used to partition a child table.
+      #
+      # Another example of a lambda that is passed partitioned values would be:
+      #    lambda {|model,created_at| return nil}
+      #
+      # This example, which names its parameter 'created_at', is more natural to deal with if
+      # you know the parameter passed in will always be a single field and the field's name
+      # is 'created_at'.
+      #
+      # DYNAMIC FORM: STRINGS
+      # Strings to be interpolated have access to two parameters:
+      #  model - the ActiveRecord class that is being partitioned.
+      #  partition_key_values - an array of values used to partition a child table.
+      #  field_value - the first element of partition_key_values (for convience)
+      #
+      # for instance:
+      # class Employee < Partitioned::PartitionBase
+      #   partitioned do |partition|
+      #     partition.on :foo
+      #     partition.index :bar
+      #     partition.index :baz
+      #     partition.constraint %q!foo = #{field_value}!
+      #   end
+      # end
+      #
+      # is the same as:
+      # class Employee < Partitioned::PartitionBase
+      #   def self.partitioned_field
+      #     return :foo
+      #   end
+      #   def self.index_field1
+      #     return :bar
+      #   end
+      #   def self.index_field2
+      #     return :baz
+      #   end
+      #   partitioned do |partition|
+      #     partition.on '#{model.partitioned_field}'
+      #     partition.index lambda { |model, *partition_key_values|
+      #       return Configurator::Data::Index.new(model.index_field1, {})
+      #     }
+      #     partition.index lambda { |model, *partition_key_values|
+      #       return Configurator::Data::Index.new(model.index_field2, {})
+      #     }
+      #     partition.constraint %q!#{model.partitioned_field} = #{field_value}!
+      #   end
+      # end
+      #
+      # IMPORTANT: note that lambdas receive, as their first parameter 'model', the most derived class that is being partition.
+      # This is not always the same as the class accessible through 'self' because 'self' is evaluated at lambda definition time.
+      # Use 'model' for general access to the Partitioned:PartitionedBase model.
+      # 
+      # The follow example shows incorrect access to the model:
+      #
+      #!bad! class Employee < Partitioned::PartitionBase
+      #!bad!   def self.index_field
+      #!bad!     return :bar
+      #!bad!   end
+      #!bad!   partitioned do |partition|
+      #!bad!     partition.on lambda { |model| return index_field }
+      #!bad!     partition.index lambda { |model, *partition_key_values|
+      #!bad!       return Configurator::Data::Index.new(self.index_field, {})
+      #!bad!     }
+      #!bad!   end
+      #!bad! end
+      #!bad!
+      #!bad! class FavoriteEmployee < Employee
+      #!bad!   def self.index_field
+      #!bad!     return :baz
+      #!bad!   end
+      #!bad! end
+      #
+      # In the above (bad code) the directive 'index' parameter is a lambda using "self.index_field" instead of "model.index_field"
+      # and the directive 'on' parameter is a lambda using "index_field" instead of "model.index_field".
+      # Since resolution of the self occurs at lambda definition time, self is Employee instead of
+      # FavoriteEmployee and index_field will be :bar instead of :baz.  model.index_field will
+      # resolve to FavoriteEmployee.index_field and be :baz as expected.
+      #
+      class Dsl
+        class InvalidConfiguratorDirectiveValue < StandardError
+          def initialize(model, table_name, directive, value, explanation)
+            super("#{model.name} [#{table_name}] invalid value '#{value}' for partitioned directive '#{directive}'.  #{explanation}")
+          end
+        end
+
+        attr_reader :data, :model
+
+        def initialize(most_derived_activerecord_class, data_class = Partitioned::PartitionedBase::Configurator::Data)
+          @model = most_derived_activerecord_class
+          @data = data_class.new
+        end
+
+        #
+        # The field used to partition child tables
+        #
+        # arguments:
+        #   field - the name of the field
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.on :company_id
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #   lambda(model) - proc returning the name of the field to partition child tables
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.on lambda {|model| model.partition_field}
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #   string - a string to be interpolated naming the field to partition child tables
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.on '#{model.partition_field}'
+        #   end
+        #
+        # one might use the latter forms to consolidate information about the field name when
+        # it might be used in several DSL directives.
+        #
+        def on(field)
+          data.on_field = field
+        end
+
+        #
+        # Define an index to be created on all (leaf-) child tables.
+        #
+        # arguments:
+        #  field - the name of the field (or an array of fields) to index
+        #  options - (not required) options passed to add_table_index()
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.index :id, :unique => true
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  lambda(model, *partition_key_values) - a procedure that will return a Partitioned::PartitionedBase::Configurator::Data::Index
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.index lambda { |model, *partition_key_values|
+        #       return Configurator::Data::Index.new(model.partition_field, {})
+        #     }
+        #   end
+        #
+        # note: this system only applies indexes to leaf child tables because indexes on parent tables,
+        # will not be used by the inherited tables (in postgres).
+        # 
+        def index(field, options = {})
+          if field.is_a? Proc
+            data.indexes << field
+          else
+            data.indexes << Partitioned::PartitionedBase::Configurator::Data::Index.new(field, options)
+          end
+        end
+
+        #
+        # Define a foreign key on a (leaf-) child table.
+        #
+        # arguments:
+        #  referencing_field - the local field that references a foreign key
+        #  referenced_table - (optional: derived from referencing_field) the foreign table that is referenced
+        #  referenced_field - (optional: default :id) the foreign tables key to reference
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.foreign_key :company_id
+        #     partition.foreign_key :home_town_id, :cities
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  proc(model, *partition_key_values) - a procedure that will return an instance of
+        #    Partitioned::PartitionedBase::Configurator::Data::ForeignKey
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.foreign_key lambda { |model, *partition_key_values|
+        #       return Configurator::Data::ForeignKey.new(model.foreign_key_field)
+        #     }
+        #   end
+        #
+        # note: as with indexes, foreign key constraints are not inherited by child tables (in postgres).
+        # this system only applies foreign keys to leaf tables.
+        #
+        def foreign_key(referencing_field, referenced_table = nil, referenced_field = :id)
+          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)
+          end
+        end
+
+        #
+        # Define the check constraint for a given child table.
+        #
+        # arguments:
+        #  constraint - a string defining the constraint for all child tables
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.constraint 'company_id = #{field_value}'
+        #   end
+        #
+        # note: the usage of single quotes to prevent string interpolation at definition time.  This string will be interpolated at
+        # run-time and "field_value" will be set to the value of the first element of partition_key_values.
+        #
+        # or:
+        #
+        # arguments:
+        #  lambda(model, *partitioned_key_values) - a procedure returning a string defining the child table's constraint.  The
+        #     child table is defined by the *partitioned key_values.
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.constraint lambda {|model, value|
+        #       return "#{model.field_to_partition} = #{value}"
+        #     }
+        #   end
+        #
+        def check_constraint(constraint)
+          data.check_constraint = constraint
+        end
+
+        #
+        # Define the order by clause used to list all child table names in order of "last to be used" to "oldest to have been used".
+        #
+        # the sql used for a table ORDERS whose child tables exist in ORDERS_PARTITIONS would look like:
+        #
+        #   select tablename from pg_tables where schemaname = 'orders_partitions' order by tablename
+        #
+        # for instance, if child tables of ORDERS are partitioned by id range (say every 5 values) and have the form orders_partition.pN,
+        # where N is the lowest value in the range of ids for that table, the order clause would probably be
+        # "substring(tablename, 2)::integer desc" which would result in:
+        #	p100
+        #	p95
+        #	p90
+        #	p85
+        #	p80
+        #	p75
+        #	p70
+        #	p65
+        #	p60
+        #	p55
+        #	p50
+        #	p45
+        #	p40
+        #	p35
+        #	p30
+        #	p25
+        #	p20
+        #	p15
+        #	p10
+        #	p5
+        #	p0
+        #
+        # this is used in PartitionedBase.last_n_partition_names(limit = 1) which should be used in code that wishes to determine
+        # if there are enough room in child tables for future use.  such processing code is not apart of
+        # partitioned code base, but this helper is here to assist in building such code.
+        #
+        # one might know that 1 partition is used per day and wish to have 10 partitions available for unforseeable spikes of data load.
+        # one might run a script once per day which calls Order.last_n_partition_names(10) and if any of the returned tables have any rows
+        # (or the sequence is set into any of the ranges in the child table) it is time to create new child tables
+        #
+        def order(clause)
+          data.last_partitions_order_by_clause = clause
+        end
+
+        #
+        # The name of the schema that will contain all child tables.
+        #
+        # arguments:
+        #  value - a string, the name of schema
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.schema_name "foos_partitions"
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  lambda(model, *partitioned_key_values) - a proc returning a string which is the name of the schema
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.schema_name lambda {|model, *value|
+        #       return "#{model.table_name}_partitions"
+        #     }
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  string - to be interpolated at run time
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.schema_name '#{model.table_name}_partitions'
+        #   end
+        # 
+        # the default is similar to the second usage: TABLENAME_partitions, for a table named 'foos' the schema name will be
+        # foos_partitions
+        #
+        def schema_name(value)
+          data.schema_name = value
+        end
+
+        #
+        # The prefix for the child table's name.
+        #
+        # by default this is the (second) 'p' in the fully qualified name 'foos_partitions.p42'
+        #
+        # arguments:
+        #  value - a string, the prefix name
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.name_prefix "p"
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  lambda(model, *partitioned_key_values) - a proc returning a string which is the prefix
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.name_prefix lambda {|model, *value|
+        #       return "#{model.table_name}_child_"
+        #     }
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  string - to be interpolated at run time
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.name_prefix '#{model.table_name}_child_'
+        #   end
+        # 
+        # the default is 'p'
+        #
+        def name_prefix(value)
+          data.name_prefix = value
+        end
+
+        #
+        # The name of the child table without the schema name or name prefix.
+        #
+        # in the example: 'foos_partitions.p42' the base_name would be 42
+        #
+        # arguments:
+        #  value - a string, the base name
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.base_name "42"
+        #   end
+        #
+        # arguments:
+        #  value - a string, the base name child table to be interpolated at runtime
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.base_name '#{model.partition_normalize_key_value(field_value)}'
+        #   end
+        #
+        # note: the string passed to partition.base_name is built using single quotes so that the
+        # the string will not be interpolated at definition time.  Rather, the string will be
+        # interpolated at run-time when it will scope the interpolation with the
+        # partition_key_values array (and field_value which the the first element of that array)
+        #
+        # or:
+        #
+        # arguments:
+        #  lambda(model, *partitioned_key_values) - a proc returning a string which is the base name of the child table
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.base_name lambda {|model, *partition_key_values|
+        #       return model.partition_normalize_key_value(*partition_key_values).to_s
+        #     }
+        #   end
+        #
+        # the default is similar to the second usage, that is: normalize the value and call to_s
+        #
+        def base_name(value)
+          data.base_name = value
+        end
+
+        #
+        # The child tables name without the schema name.
+        #
+        # in the example: 'foos_partitions.p42' the part_name would be p42
+        #
+        # arguments:
+        #  value - a string, the part name
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.part_name "p42"
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  value - a string, the part name child table to be interpolated at runtime
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.part_name '#{model.table_name}_child_#{model.partition_normalize_key_value(field_value)}'
+        #   end
+        #
+        # note: the string passed to partition.part_name is built using single quotes so that the
+        # the string will not be interpolated at definition time.  Rather, the string will be
+        # interpolated at run-time when it will scope the interpolation with the
+        # partition_key_values array (and field_value which the the first element of that array)
+        #
+        # or:
+        #
+        # arguments:
+        #  lambda(model, *partitioned_key_values) - a proc returning a string which is the part name of the child table
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.part_name lambda {|model, *partition_key_values|
+        #       return "#{model.table_name}_child_#{model.partition_normalize_key_value(field_value)}"
+        #     }
+        #   end
+        #
+        # the default is similar to the third usage
+        #
+        def part_name(value)
+          data.part_name = value
+        end
+
+        #
+        # The full name of a child table defined by the partition key values.
+        #
+        # in the example: 'foos_partitions.p42' the table name would be foos_partitions.p42
+        #
+        # arguments:
+        #  value - a string, the table name
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.table_name "foos_partitions.p42"
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  value - a string, the table name child table to be interpolated at runtime
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.table_name '#{model.table_name}_partitions.#{model.table_name}_child_#{model.partition_normalize_key_value(field_value)}'
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  lambda(model, *partitioned_key_values) - a proc returning a string which is the table name of the child table
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.table_name lambda {|model, *partition_key_values|
+        #       return "#{model.table_name}_partitions.#{model.table_name}_child_#{model.partition_normalize_key_value(partition_key_values.first)}"
+        #     }
+        #   end
+        #
+        # the default is similar to the third usage
+        #
+        def table_name(value)
+          data.table_name = value
+        end
+
+        #
+        # The table name of the table who is the direct ancestor of a child table.
+        #
+        # arguments:
+        #  value - a string, the parent table name
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.parent_table_name "foos"
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  value - a string, the parent table name child table to be interpolated at runtime
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.table_name '#{model.table_name}'
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  lambda(model, *partitioned_key_values) - a proc returning a string which is the parent table name of the child table
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.parent_table_name lambda {|model, *partition_key_values|
+        #       return "#{model.table_name}"
+        #     }
+        #   end
+        #
+        # By default this is just the active record's notion of the name of the class.
+        #
+        def parent_table_name(value)
+          data.parent_table_name = value
+        end
+
+        #
+        # The schema name of the table who is the direct ancestor of a child table.
+        #
+        # arguments:
+        #  value - a string, the schema name
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.parent_table_schema_name "public"
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  value - a string, the schema name to be interpolated at runtime
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.parent_table_schema_name '#{model.table_name}'
+        #   end
+        #
+        # or:
+        #
+        # arguments:
+        #  lambda(model, *partitioned_key_values) - a proc returning a string which is the schema name of the child table
+        #
+        # usage:
+        #   partitioned do |partition|
+        #     partition.parent_table_schema_name lambda {|model, *partition_key_values|
+        #       return "#{model.table_name}"
+        #     }
+        #   end
+        #
+        # By default this is just the "public".
+        #
+        def parent_table_schema_name(value)
+          data.parent_table_schema_name = value
+        end
+      end
+    end
+  end
+end