has_metadata 1.6.0 → 1.6.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e2f29c8739a41a97beed0ed3c6b331f8ba3cc2da4ee8bacbd7dc269a0113d23a
+  data.tar.gz: 9ceb1f806883a0a42a8734270801b88f715357fb8315f8dbf51566d84a4caaad
+SHA512:
+  metadata.gz: 91d5b70471591f8c37c8ae7d6849e370356b6f0fb42c324b7e5a451c0b3448564060f178be7c1ec853f53d4302f8eb2acd7ad1f0d13270fd69bd4ac0a19dfc57
+  data.tar.gz: a53e2493826bd95af4c129a6fa3b4a73acfee451f1b70797d48fa4803242662d54bda4324b7627204a90718fbc2db65edec46efb60f8fa13d7d38a1ef1ee4736

data/README.md

@@ -0,0 +1,117 @@
+> ⚠️ **DEPRECATED:** `has_metadata` is no longer maintained. Superseded by
+> [`has_metadata_column`](https://github.com/RISCfuture/has_metadata_column)
+> (also deprecated). No active maintenance. The final release is v1.6.2.
+
+has_metadata
+============
+
+**Keep your tables narrow**
+
+|             |                                 |
+|:------------|:--------------------------------|
+| **Author**  | Tim Morgan                      |
+| **Version** | 1.6.1 (Jan 24, 2012)            |
+| **License** | Released under the MIT License. |
+
+About
+-----
+
+Wide tables are a problem for big databases. If your `ActiveRecord` models have
+10, maybe 15 columns, some of which are `VARCHARs` or maybe even `TEXTs`, it's
+going to slow your queries down when you start to scale up.
+
+The easy solution to this problem is to limit your projections; in other words,
+to only `SELECT` the columns that you actually need. If you've got a `users`
+table with a giant `about_me` text column, and you're only trying to look up the
+user's login, then just select the `login` column.
+
+In the long run, though, a superior solution is to just move those
+`about_me`-type columns to a completely different table. This table has just one
+JSON-serialized field, making it schemaless, so it doesn't waste space. Each row
+in this table is associated with a record in another table (`Metadata` `has_one`
+of your models).
+
+This way, when your website gets huge, all of your giant, freeform data is in
+one table that you can shard, or move off to an alternate database, or even a
+NoSQL-type document store, or otherwise manage as you please. Your relational
+tables remain slim and efficient, containing only columns that a) are indexed,
+or b) you need frequent access to.
+
+This gem includes a generator that creates the `Metadata` model, and a module
+that you can include in your models to define which fields have been spun off to
+the metadata record.
+
+Installation
+------------
+
+**Important Note:** This gem is only compatible with Ruby 1.9+ and Rails 3.0+.
+
+Firstly, add the gem to your Rails project's `Gemfile`:
+
+```` ruby
+gem 'has_metadata'
+````
+
+Next, run the generator, which will add the `Metadata` model and its migration
+to your application.
+
+```` sh
+rails generate metadata
+````
+
+Usage
+-----
+
+The first thing to think about is what columns to keep in your model. You will
+need to keep any indexed columns, or any columns you perform lookups or other
+SQL queries with. You should also keep any frequently accessed columns,
+especially if they are small (integers or booleans). Good candidates for the
+metadata table are the `TEXT`- and `VARCHAR`-type columns that you only need to
+render a page or two in your app.
+
+You'll need to change your model's schema so that it has a `metadata_id` column
+that will associate the model with its `Metadata` instance:
+
+```` ruby
+t.belongs_to :metadata
+````
+
+Next, include the `HasMetadata` module in your model, and call the
+`has_metadata` method to define the schema of your metadata. You can get more
+information in the {HasMetadata::ClassMethods#has_metadata} documentation, but for starters, here's a
+basic example:
+
+```` ruby
+class User < ActiveRecord::Base
+  include HasMetadata
+  has_metadata({
+    about_me: { type: String, length: { maximum: 512 } },
+    birthdate: { type: Date, presence: true },
+    zipcode: { type: Number, numericality: { greater_than: 9999, less_than: 10_000} }
+  })
+end
+````
+
+As you can see, you pass field names mapped to a hash. The hash describes the
+validation that will be performed, and is in the same format as a call to
+`validates`. In addition to the `EachValidator` keys shown above, you can also
+pass a `type` key, to constrain the Ruby type that can be assigned to the field.
+
+Each of these fields (in this case, `about_me`, `birthdate`, and `zipcode`) can
+be accessed and set as first_level methods on an instance of your model:
+
+```` ruby
+user.about_me #=> "I was born in 1982 in Aberdeen. My father was a carpenter from..."
+````
+
+... and thus, used as part of `form_for` fields:
+
+```` ruby
+form_for user do |f|
+  f.text_area :about_me, rows: 5, cols: 80
+end
+````
+
+The only thing you _can't_ do is use these fields in a query, obviously. You
+can't do something like `User.where(zipcode: 90210)`, because that column
+doesn't exist on the `users` table.

data/has_metadata.gemspec

@@ -2,23 +2,24 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
+# stub: has_metadata 1.6.2 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "has_metadata"
-  s.version = "1.6.0"
+  s.version = "1.6.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tim Morgan"]
-  s.date = "2012-01-24"
+  s.date = "2013-12-08"
   s.description = "has_metadata lets you move non-indexed and weighty columns off of your big tables by creating a separate metadata table to store all this extra information. Works with Ruby 1.9. and Rails 3.0."
   s.email = "git@timothymorgan.info"
   s.extra_rdoc_files = [
     "LICENSE",
-    "README.textile"
+    "README.md"
   ]
   s.files = [
     "LICENSE",
-    "README.textile",
+    "README.md",
     "has_metadata.gemspec",
     "lib/has_metadata.rb",
     "lib/has_metadata/metadata_generator.rb",
@@ -29,11 +30,20 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/riscfuture/has_metadata"
   s.require_paths = ["lib"]
   s.required_ruby_version = Gem::Requirement.new(">= 1.9")
-  s.rubygems_version = "1.8.15"
-  s.summary = "Reduce your table width by moving non-indexed columns to a separate metadata table"
+  s.rubygems_version = "2.1.11"
+  s.summary = "[DEPRECATED] Reduce your table width by moving non-indexed columns to a separate metadata table"
+  s.post_install_message = <<~MSG
+
+    ⚠️  DEPRECATED: has_metadata is no longer maintained.
+
+    Superseded by `has_metadata_column` (also deprecated as of this notice). No active maintenance.
+
+    This is the final release. No further updates are planned.
+
+  MSG
 
   if s.respond_to? :specification_version then
-    s.specification_version = 3
+    s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<rails>, [">= 3.2"])

data/lib/has_metadata/metadata_generator.rb

@@ -5,19 +5,19 @@ require 'rails/generators/migration'
 # @private
 class MetadataGenerator < Rails::Generators::Base
   include Rails::Generators::Migration
-  
+
   source_root "#{File.dirname __FILE__}/../../templates"
-  
+
   def self.next_migration_number(dirname)
     if ActiveRecord::Base.timestamped_migrations then
-      Time.now.utc.strftime "%Y%m%d%H%M%S"
+      Time.now.utc.strftime '%Y%m%d%H%M%S'
     else
       "%.3d" % (current_migration_number(dirname) + 1)
     end
   end
-  
+
   def copy_files
-    copy_file "metadata.rb", "app/models/metadata.rb"
-    migration_template "create_metadata.rb", "db/migrate/create_metadata.rb"
+    copy_file 'metadata.rb', 'app/models/metadata.rb'
+    migration_template 'create_metadata.rb', 'db/migrate/create_metadata.rb'
   end
 end

data/lib/has_metadata/model.rb

@@ -1,9 +1,11 @@
+require 'active_record'
+
 module HasMetadata
-  
+
   # Base class of the {Metadata} model. Functionality is moved to this class to
-  # make changes to the model easier. See the @Metadata@ method for more
+  # make changes to the model easier. See the `Metadata` method for more
   # information.
-  
+
   class Model < ActiveRecord::Base
     self.table_name = 'metadata'
     serialize :data, Hash
@@ -20,10 +22,10 @@ module HasMetadata
         name = name.to_sym
         super(name) or fields.include?(name)
       end
-      
+
       # override attribute prefix/suffix methods to get full first-class
       # property functionality
-      
+
       singleton_class.send(:define_method, :attribute) do |name|
         name = name.to_sym
         super(name) unless fields.include?(name)
@@ -33,7 +35,7 @@ module HasMetadata
         data.include?(name) ? data[name] : default
       end
       singleton_class.send :alias_method, :attribute_before_type_cast, :attribute
-      
+
       singleton_class.send(:define_method, :query_attribute) do |name|
         name = name.to_sym
         super(name) unless fields.include?(name)
@@ -49,19 +51,26 @@ module HasMetadata
           not send(name).blank?
         end
       end
-      
+
       singleton_class.send(:define_method, :attribute=) do |name, value|
         name = name.to_sym
         super(name, value) unless fields.include?(name)
 
         options = fields[name] || {}
         data_will_change!
+        attribute_will_change! name.to_s
         data[name] = HasMetadata.metadata_typecast(value, options[:type])
       end
 
       self
     end
 
+    # @return [Hash<String, Object>] A hash of metadata fields that have been
+    #   altered.
+    def changed_metadata
+      changed_attributes.except(*attribute_names)
+    end
+
     private
 
     def initialize_data

data/lib/has_metadata.rb

@@ -16,15 +16,16 @@ class Object
 end
 
 
-# Provides the {ClassMethods#has_metadata} method to subclasses of @ActiveRecord::Base@.
+# Provides the {ClassMethods#has_metadata} method to subclasses of
+# `ActiveRecord::Base`.
 
 module HasMetadata
   extend ActiveSupport::Concern
-  
+
   # @private
   def self.metadata_typecast(value, type)
     if value.kind_of?(String) then
-      if type == Integer or type == Fixnum then
+      if type == Integer or type == Integer then
         begin
           return Integer(value.sub(/^0+/, '')) # so that it doesn't think it's in octal
         rescue ArgumentError
@@ -36,33 +37,37 @@ module HasMetadata
         rescue ArgumentError
           return value
         end
-      elsif type == Boolean then return value.parse_bool end
+      elsif type == Boolean then
+        return value.parse_bool
+      end
     end
     return value
   end
-  
+
   # Class methods that are added to your model.
-  
+
   module ClassMethods
 
     # Defines a set of fields whose values exist in the associated {Metadata}
-    # record. Each key in the @fields@ hash is the name of a metadata field, and
-    # the value is a set of options to pass to the @validates@ method. If you do
-    # not want to perform any validation on a field, simply pass @true@ as its
+    # record. Each key in the `fields` hash is the name of a metadata field, and
+    # the value is a set of options to pass to the `validates` method. If you do
+    # not want to perform any validation on a field, simply pass `true` as its
     # key value.
     #
-    # In addition to the normal @validates@ keys, you can also include a @:type@
-    # key to restrict values to certain classes, or a @:default@ key to specify
+    # In addition to the normal `validates` keys, you can also include a `:type`
+    # key to restrict values to certain classes, or a `:default` key to specify
     # a value to return for the getter should none be set (normal default is
-    # @nil@).
+    # `nil`).
     #
     # @param [Hash<Symbol, Hash>] fields A mapping of field names to their
-    #   validation options (and/or the @:type@ key).
+    #   validation options (and/or the `:type` key).
     #
     # @example Three metadata fields, one basic, one validated, and one type-checked.
-    #   has_metadata(optional: true, required: { presence: true }, number: { type: Fixnum })
+    #   has_metadata(optional: true, required: { presence: true }, number: { type: Integer })
 
     def has_metadata(fields)
+      raise "Can't define Rails-magic timestamped columns as metadata" if (fields.keys & [:created_at, :created_on, :updated_at, :updated_on]).any?
+
       if !respond_to?(:metadata_fields) then
         belongs_to :metadata, dependent: :destroy
         accepts_nested_attributes_for :metadata
@@ -73,7 +78,9 @@ module HasMetadata
 
         define_method(:save_metadata) { metadata.save! }
         define_method(:metadata_changed?) { metadata.try :changed? }
-      else
+
+        prepend WithMetadata
+      elsif metadata_fields.slice(*fields.keys) != fields
         raise "Cannot redefine existing metadata fields: #{(fields.keys & self.metadata_fields.keys).to_sentence}" unless (fields.keys & self.metadata_fields.keys).empty?
         self.metadata_fields = self.metadata_fields.merge(fields)
       end
@@ -81,33 +88,34 @@ module HasMetadata
       fields.each do |name, options|
         # delegate all attribute methods to the metadata
         attribute_method_matchers.each { |matcher| delegate matcher.method_name(name), to: :metadata! }
-        
+
         if options.kind_of?(Hash) then
-          type = options.delete(:type)
+          type          = options.delete(:type)
           type_validate = !options.delete(:skip_type_validation)
           options.delete :default
-          
+
           validate do |obj|
             value = obj.send(name)
-            errors.add(name, :incorrect_type) unless
-              HasMetadata.metadata_typecast(value, type).kind_of?(type) or
+            errors.add(name, :incorrect_type) unless HasMetadata.metadata_typecast(value, type).kind_of?(type) or
                 ((options[:allow_nil] and value.nil?) or (options[:allow_blank] and value.blank?))
           end if type && type_validate
-          validates(name, options) unless options.empty? or (options.keys - [ :allow_nil, :allow_blank ]).empty?
+          validates(name, options) unless options.empty? or (options.keys - [:allow_nil, :allow_blank]).empty?
         end
       end
     end
   end
 
+  # @private
   def as_json(options={})
-    options ||= Hash.new # the JSON encoder can sometimes give us nil options?
-    options[:except] = Array.wrap(options[:except]) + [ :metadata_id ]
+    options           ||= Hash.new # the JSON encoder can sometimes give us nil options?
+    options[:except]  = Array.wrap(options[:except]) + [:metadata_id]
     options[:methods] = Array.wrap(options[:methods]) + metadata_fields.keys - options[:except].map(&:to_sym)
     super options
   end
-  
+
+  # @private
   def to_xml(options={})
-    options[:except] = Array.wrap(options[:except]) + [ :metadata_id ]
+    options[:except]  = Array.wrap(options[:except]) + [:metadata_id]
     options[:methods] = Array.wrap(options[:methods]) + metadata_fields.keys - options[:except].map(&:to_sym)
     super options
   end
@@ -115,18 +123,20 @@ module HasMetadata
   # @private
   def assign_multiparameter_attributes(pairs)
     fake_attributes = pairs.select { |(field, _)| self.class.metadata_fields.include? field[0, field.index('(')].to_sym }
+    result = super(pairs.except(fake_attributes.keys))
 
     fake_attributes.group_by { |(field, _)| field[0, field.index('(')] }.each do |field_name, parts|
       options = self.class.metadata_fields[field_name.to_sym]
       if options[:type] then
         args = parts.each_with_object([]) do |(part_name, value), ary|
           part_ann = part_name[part_name.index('(') + 1, part_name.length]
-          index = part_ann.to_i - 1
+          index    = part_ann.to_i - 1
           raise "Out-of-bounds multiparameter argument index" unless index >= 0
           ary[index] = if value.blank? then nil
-            elsif part_ann.ends_with?('i)') then value.to_i
-            elsif part_ann.ends_with?('f)') then value.to_f
-            else value end
+                       elsif part_ann.ends_with?('i)') then value.to_i
+                       elsif part_ann.ends_with?('f)') then value.to_f
+                       else value
+                       end
         end
         args.compact!
         send :"#{field_name}=", options[:type].new(*args) unless args.empty?
@@ -135,22 +145,47 @@ module HasMetadata
       end
     end
 
-    super(pairs - fake_attributes)
+    return result
   end
 
   # @return [Metadata] An existing associated {Metadata} instance, or new,
   #   saved one if none was found.
 
   def metadata!
-    if instance_variables.include?(:@metadata) then
-      metadata.set_fields self.class.metadata_fields
+    if instance_variables.include?(:@metadata) && metadata then
+      metadata
     else
-      (metadata || Metadata.transaction { metadata || create_metadata }).set_fields self.class.metadata_fields
-    end
+      if new_record? then
+        metadata || build_metadata
+      else
+        metadata || Metadata.transaction { metadata || create_metadata }
+      end
+    end.set_fields self.class.metadata_fields
   end
 
   # @private
   def inspect
-    "#<#{self.class.to_s} #{attributes.merge(metadata.try(:data).try(:stringify_keys) || {}).map { |k,v| "#{k}: #{v.inspect}" }.join(', ')}>"
+    "#<#{self.class.to_s} #{attributes.merge(metadata.try(:data).try(:stringify_keys) || {}).map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}>"
+  end
+
+  module WithMetadata
+    # @private
+    def changed_attributes
+      super.merge(metadata.try(:changed_metadata) || {})
+    end
+
+    # @private
+    def attributes_changed_by_setter
+      super.merge(metadata.try(:changed_metadata) || {})
+    end
+
+    # @private
+    def attribute_will_change!(attr)
+      if attribute_names.include?(attr) then
+        super attr
+      else
+        metadata!.send :attribute_will_change!, attr
+      end
+    end
   end
 end

data/templates/metadata.rb

@@ -1,11 +1,14 @@
 # Stores information about a model that doesn't need to be in that model's
-# table. Each row in the @metadata@ table stores a schemaless, serialized hash
+# table. Each row in the `metadata` table stores a schemaless, serialized hash
 # of data associated with a model instance. Any model can have an associated row
-# in the @metadata@ table by using the {HasMetadata} module.
+# in the `metadata` table by using the {HasMetadata} module.
 #
-# h2. Properties
+# Properties
+# ----------
 #
-# | @data@ | A hash of this metadata's contents (YAML serialized in the database). |
+# |        |                                                                       |
+# |:-------|:----------------------------------------------------------------------|
+# | `data` | A hash of this metadata's contents (YAML serialized in the database). |
 
 class Metadata < HasMetadata::Model
 end

metadata

@@ -1,93 +1,112 @@
 --- !ruby/object:Gem::Specification
 name: has_metadata
 version: !ruby/object:Gem::Version
-  version: 1.6.0
-  prerelease: 
+  version: 1.6.2
 platform: ruby
 authors:
 - Tim Morgan
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-24 00:00:00.000000000 Z
+date: 2013-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70170864527740 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.2'
   type: :runtime
   prerelease: false
-  version_requirements: *70170864527740
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: boolean
-  requirement: &70170864527260 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70170864527260
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70170864526780 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70170864526780
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70170864526300 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70170864526300
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: RedCloth
-  requirement: &70170864525820 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70170864525820
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70170864525340 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70170864525340
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70170864524860 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70170864524860
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: has_metadata lets you move non-indexed and weighty columns off of your
   big tables by creating a separate metadata table to store all this extra information.
   Works with Ruby 1.9. and Rails 3.0.
@@ -96,10 +115,10 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE
-- README.textile
+- README.md
 files:
 - LICENSE
-- README.textile
+- README.md
 - has_metadata.gemspec
 - lib/has_metadata.rb
 - lib/has_metadata/metadata_generator.rb
@@ -108,27 +127,32 @@ files:
 - templates/metadata.rb
 homepage: http://github.com/riscfuture/has_metadata
 licenses: []
-post_install_message: 
+metadata: {}
+post_install_message: |2+
+
+  ⚠️  DEPRECATED: has_metadata is no longer maintained.
+
+  Superseded by `has_metadata_column` (also deprecated as of this notice). No active maintenance.
+
+  This is the final release. No further updates are planned.
+
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '1.9'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.15
-signing_key: 
-specification_version: 3
-summary: Reduce your table width by moving non-indexed columns to a separate metadata
-  table
+rubygems_version: 4.0.11
+specification_version: 4
+summary: "[DEPRECATED] Reduce your table width by moving non-indexed columns to a
+  separate metadata table"
 test_files: []
+...

data/README.textile

@@ -1,126 +0,0 @@
-h1. has_metadata -- Keep your tables narrow
-
-| *Author* | Tim Morgan |
-| *Version* | 1.6 (Jan 23, 2012) |
-| *License* | Released under the MIT License. |
-
-h2. Important note for those upgrading from 1.0 to 1.1
-
-You must re-run the @rails generate metadata@ task to update your @Metadata@
-model. When finished, your @app/models/metadata.rb@ file should look like:
-
-<pre><code>
-# Stores information about a model that doesn't need to be in that model's
-# table. Each row in the @metadata@ table stores a schemaless, serialized hash
-# of data associated with a model instance. Any model can have an associated row
-# in the @metadata@ table by using the {HasMetadata} module.
-#
-# h2. Properties
-#
-# | @data@ | A hash of this metadata's contents (YAML serialized in the database). |
-
-class Metadata &lt; HasMetadata::Model
-end
-</code></pre>
-
-Note that this is significantly emptier than the previous model.
-
-h2. About
-
-Wide tables are a problem for big databases. If your @ActiveRecord@ models have
-10, maybe 15 columns, some of which are @VARCHARs@ or maybe even @TEXTs@, it's
-going to slow your queries down when you start to scale up.
-
-The easy solution to this problem is to limit your projections; in other words,
-to only @SELECT@ the columns that you actually need. If you've got a @users@
-table with a giant @about_me@ text column, and you're only trying to look up the
-user's login, then just select the @login@ column.
-
-In the long run, though, a superior solution is to just move those
-@about_me@-type columns to a completely different table. This table has just one
-JSON-serialized field, making it schemaless, so it doesn't waste space. Each row
-in this table is associated with a record in another table (@Metadata@ @has_one@
-of your models).
-
-This way, when your website gets huge, all of your giant, freeform data is in
-one table that you can shard, or move off to an alternate database, or even a
-NoSQL-type document store, or otherwise manage as you please. Your relational
-tables remain slim and efficient, containing only columns that a) are indexed,
-or b) you need frequent access to.
-
-This gem includes a generator that creates the @Metadata@ model, and a module
-that you can include in your models to define which fields have been spun off to
-the metadata record.
-
-h2. Installation
-
-*Important Note:* This gem is only compatible with Ruby 1.9 and Rails 3.0.
-
-Firstly, add the gem to your Rails project's @Gemfile@:
-
-<pre><code>
-gem 'has_metadata'
-</code></pre>
-
-Next, run the generator, which will add the @Metadata@ model and its migration
-to your application.
-
-<pre><code>
-rails generate metadata
-</code></pre>
-
-h2. Usage
-
-The first thing to think about is what columns to keep in your model. You will
-need to keep any indexed columns, or any columns you perform lookups or other
-SQL queries with. You should also keep any frequently accessed columns,
-especially if they are small (integers or booleans). Good candidates for the
-metadata table are the @TEXT@- and @VARCHAR@-type columns that you only need to
-render a page or two in your app.
-
-You'll need to change your model's schema so that it has a @metadata_id@ column
-that will associate the model with its @Metadata@ instance:
-
-<pre><code>
-t.belongs_to :metadata
-</code></pre>
-
-Next, include the @HasMetadata@ module in your model, and call the
-@has_metadata@ method to define the schema of your metadata. You can get more
-information in the {HasMetadata::ClassMethods#has_metadata} documentation, but for starters, here's a
-basic example:
-
-<pre><code>
-class User < ActiveRecord::Base
-  include HasMetadata
-  has_metadata({
-    about_me: { type: String, length: { maximum: 512 } },
-    birthdate: { type: Date, presence: true },
-    zipcode: { type: Number, numericality: { greater_than: 9999, less_than: 10_000_} }
-  })
-end
-</code></pre>
-
-As you can see, you pass field names mapped to a hash. The hash describes the
-validation that will be performed, and is in the same format as a call to
-@validates@. In addition to the @EachValidator@ keys shown above, you can also
-pass a @type@ key, to constrain the Ruby type that can be assigned to the field.
-
-Each of these fields (in this case, @about_me@, @birthdate@, and @zipcode@) can
-be accessed and set as first_level methods on an instance of your model:
-
-<pre><code>
-user.about_me #=> "I was born in 1982 in Aberdeen. My father was a carpenter from..."
-</code></pre>
-
-... and thus, used as part of @form_for@ fields:
-
-<pre><code>
-form_for user do |f|
-  f.text_area :about_me, rows: 5, cols: 80
-end
-</code></pre>
-
-The only thing you _can't_ do is use these fields in a query, obviously. You
-can't do something like @User.where(zipcode: 90210)@, because that column
-doesn't exist on the @users@ table.