declare_schema 0.8.0.pre.6 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d3ceea8167afc532a38353f4bdac36fc805762dd2c8f2bf5fdb7895e7fc9886
-  data.tar.gz: 766a96c62aad5a6360c12a74a2630d52d6ee4c08b44ceeb3dd7309251886ce14
+  metadata.gz: 4a529991bad5ab16728f11b3f6c165b62853c3b68713e0ec69d6370d7d3c0e5b
+  data.tar.gz: 6a131f8af82b018b843f639e501371cf0db9a65b91a4acb99aea44d3eb1674d9
 SHA512:
-  metadata.gz: d9de9bb8b90e978d745b5832ce81553d1156e10810f30304a347dd5e591ccd55fa086982ea32f349634cc1a8ff34fad3798d94ccfcd1fe3351be1f9e5a1f9648
-  data.tar.gz: 7b569604b9dc7f0ca2b8a8c36ffaede21a85e5f0ca13e39291823cfdf41a7b2f3ee00dedb7dd93e4ddd589a266dee75909f9b33bcb084c1e8929086216dbdee9
+  metadata.gz: 655ab291337bf8f11fb249de1b97608e7ff73b14ff543f9248e3f92d9bf1770553b8bc2f962c72e8763d27ae559c35bdff1f12f4b6b460a1d46abfab00e931c0
+  data.tar.gz: b67d3340bb42b91bddd0940e0a9e5a895bd57f2017ef8d4712e1e4331ba46e78b17d9f7e9b0e60de9f921232897c0edeffe37621060632ecb18267db1ce15dc0

data/.github/workflows/declare_schema_build.yml

@@ -57,4 +57,4 @@ jobs:
           git config --global user.email "dummy@example.com"
           git config --global user.name "dummy"
           MYSQL_PORT=3306 bundle exec rake test:prepare_testapp[force]
-          bundle exec rake test:all < test_responses.txt
+          bundle exec rake test:all

data/CHANGELOG.md

@@ -4,8 +4,32 @@ Inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 Note: this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.8.0] - UNRELEASED
+## [0.10.1] - 2021-03-18
+### Fixed
+- Migration steps are now generated in a defined dependency order, so that--for example--indexes that depend
+ on columns are deleted first, before the columns themselves are deleted (since the latter implicitly does the former, which would break the migration when run).
+- Related to the above, down migration steps are now always generated in exactly the reverse order of the up migration steps.
+
+## [0.10.0] - 2021-03-17
+### Deprecated
+- Deprecated the `fields` DSL method in favor of `declare_schema`.
+
+### Added
+- Added the `declare_schema` method to replace `fields`. We now expect a column's type to come before the name
+i.e. `declare schema { string :title }`. Otherwise, there is no difference between `fields` and `declare_schema`.
+
+## [0.9.0] - 2021-03-01
+### Added
+- Added configurable default settings for `default_text_limit`, `default_string_limit`, `default_null`,
+`default_generate_foreign_keys` and `default_generate_indexing` to allow developers to adhere to project conventions.
+
+### Changed
+- Moved and deprecated default settings for `default_charset` and `default_collation` from
+`Generators::DeclareSchema::Migration::Migrator` to `::DeclareSchema`
+
+## [0.8.0] - 2021-02-22
 ### Removed
+- Removed assumption that primary key is named 'id'.
 - Removed `sql_type` that was confusing because it was actually the same as `type` (ex: :string) and not
   in fact the SQL type (ex: ``varchar(255)'`).
 
@@ -130,6 +154,9 @@ using the appropriate Rails configuration attributes.
 ### Added
 - Initial version from https://github.com/Invoca/hobo_fields v4.1.0.
 
+[0.10.1]: https://github.com/Invoca/declare_schema/compare/v0.10.0...v0.10.1
+[0.10.0]: https://github.com/Invoca/declare_schema/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/Invoca/declare_schema/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/Invoca/declare_schema/compare/v0.7.1...v0.8.0
 [0.7.1]: https://github.com/Invoca/declare_schema/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/Invoca/declare_schema/compare/v0.6.3...v0.7.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    declare_schema (0.8.0.pre.6)
+    declare_schema (0.10.1)
       rails (>= 4.2)
 
 GEM

data/README.md

@@ -70,18 +70,85 @@ DeclareSchema::Migration::Migrator.before_generating_migration do
 end
 ```
 
-## Declaring Character Set and Collation
-_Note: This feature currently only works for MySQL database configurations._
+### Global Configuration
+Configurations can be set at the global level to customize default declaration for the following values:
 
-MySQL originally supported UTF-8 in the range of 1-3 bytes (`mb3` or "multi-byte 3")
-which covered the full set of Unicode code points at the time: U+0000 - U+FFFF.
-But later, Unicode was extended beyond U+FFFF to make room for emojis, and with that
-UTF-8 require 1-4 bytes (`mb4` or "multi-byte 4"). With this addition, there has
-come a need to dynamically define the character set and collation for individual
-tables and columns in the database. With `declare_schema` this can be configured
-at three separate levels
+#### Text Limit
+The default text limit can be set using the `DeclareSchema.default_text_limit=` method.
+Note that a `nil` default means that there is no default-- so every declaration must be explicit.
+This will `raise` a `limit: must be provided for field :text...` error when the default value is `nil` and there is no explicit
+declaration.
 
-### Global Configuration
+For example, adding the following to your `config/initializers` directory will
+set the default `text limit` value to `0xffff`:
+ 
+**declare_schema.rb**
+```ruby
+# frozen_string_literal: true
+
+DeclareSchema.default_text_limit = 0xffff
+```
+
+#### String Limit
+The default string limit can be set using the `DeclareSchema.default_string_limit=` method.
+Note that a `nil` default means that there is no default-- so every declaration must be explicit.
+This will `raise` a `limit: must be provided for field :string...` error when the default value is `nil` and there is no explicit
+declaration.
+
+For example, adding the following to your `config/initializers` directory will
+set the default `string limit` value to `255`:
+ 
+**declare_schema.rb**
+```ruby
+# frozen_string_literal: true
+
+DeclareSchema.default_string_limit = 255
+```
+
+#### Null
+The default null value can be set using the `DeclareSchema.default_null=` method.
+Note that a `nil` default means that there is no default-- so every declaration must be explicit.
+This will `raise` a `null: must be provided for field...` error when the default value is `nil` and there is no explicit
+declaration.
+
+For example, adding the following to your `config/initializers` directory will
+set the default `null` value to `true`:
+ 
+**declare_schema.rb**
+```ruby
+# frozen_string_literal: true
+
+DeclareSchema.default_null = true
+```
+
+#### Generate Foreign Keys
+The default value for generate foreign keys can be set using the `DeclareSchema.default_generate_foreign_keys=` method.
+This value defaults to `true` and can only be set at the global level.
+
+For example, adding the following to your `config/initializers` directory will set
+the default `generate foreign keys` value to `false`:
+ 
+**declare_schema.rb**
+```ruby
+# frozen_string_literal: true
+
+DeclareSchema.default_generate_foreign_keys = false
+```
+
+#### Generate Indexing
+The default value for generate indexing can be set using the `DeclareSchema.default_generate_indexing=` method.
+This value defaults to `true` and can only be set at the global level.
+
+For example, adding the following to your `config/initializers` directory will
+set the default `generate indexing` value to `false`:
+ 
+**declare_schema.rb**
+```ruby
+# frozen_string_literal: true
+
+DeclareSchema.default_generate_indexing = false
+```
+#### Character Set and Collation
 The character set and collation for all tables and fields can be set at the global level
 using the `Generators::DeclareSchema::Migrator.default_charset=` and
 `Generators::DeclareSchema::Migrator.default_collation=` configuration methods.
@@ -93,10 +160,21 @@ turn all tables into `utf8mb4` supporting tables:
 ```ruby
 # frozen_string_literal: true
 
-Generators::DeclareSchema::Migration::Migrator.default_charset   = "utf8mb4"
-Generators::DeclareSchema::Migration::Migrator.default_collation = "utf8mb4_bin"
+DeclareSchema.default_charset   = "utf8mb4"
+DeclareSchema.default_collation = "utf8mb4_bin"
 ```
 
+## Declaring Character Set and Collation
+_Note: This feature currently only works for MySQL database configurations._
+
+MySQL originally supported UTF-8 in the range of 1-3 bytes (`mb3` or "multi-byte 3")
+which covered the full set of Unicode code points at the time: U+0000 - U+FFFF.
+But later, Unicode was extended beyond U+FFFF to make room for emojis, and with that
+UTF-8 require 1-4 bytes (`mb4` or "multi-byte 4"). With this addition, there has
+come a need to dynamically define the character set and collation for individual
+tables and columns in the database. With `declare_schema` this can be configured
+at three separate levels
+
 ### Table Configuration
 In order to configure a table's default character set and collation, the `charset` and
 `collation` arguments can be added to the `fields` block.
@@ -150,5 +228,5 @@ or add it to your `bundler` Gemfile:
 To run tests:
 ```
 rake test:prepare_testapp[force]
-rake test:all < test_responses.txt
+rake test:all
 ```

data/lib/declare_schema.rb

@@ -21,7 +21,18 @@ module DeclareSchema
     text:     String
   }.freeze
 
+  @default_charset               = "utf8mb4"
+  @default_collation             = "utf8mb4_bin"
+  @default_text_limit            = 0xffff_ffff
+  @default_string_limit          = nil
+  @default_null                  = false
+  @default_generate_foreign_keys = true
+  @default_generate_indexing     = true
+
   class << self
+    attr_reader :default_charset, :default_collation, :default_text_limit, :default_string_limit, :default_null,
+                :default_generate_foreign_keys, :default_generate_indexing
+
     def to_class(type)
       case type
       when Class
@@ -32,6 +43,41 @@ module DeclareSchema
         raise ArgumentError, "expected Class or Symbol or String: got #{type.inspect}"
       end
     end
+
+    def default_charset=(charset)
+      charset.is_a?(String) or raise ArgumentError, "charset must be a string (got #{charset.inspect})"
+      @default_charset = charset
+    end
+
+    def default_collation=(collation)
+      collation.is_a?(String) or raise ArgumentError, "collation must be a string (got #{collation.inspect})"
+      @default_collation = collation
+    end
+
+    def default_text_limit=(text_limit)
+      text_limit.nil? or text_limit.is_a?(Integer) or raise ArgumentError, "text limit must be an integer or nil (got #{text_limit.inspect})"
+      @default_text_limit = text_limit
+    end
+
+    def default_string_limit=(string_limit)
+      string_limit.nil? or string_limit.is_a?(Integer) or raise ArgumentError, "string limit must be an integer or nil (got #{string_limit.inspect})"
+      @default_string_limit = string_limit
+    end
+
+    def default_null=(null)
+      null.in?([true, false, nil]) or raise ArgumentError, "null must be either true, false, or nil (got #{null.inspect})"
+      @default_null = null
+    end
+
+    def default_generate_foreign_keys=(generate_foreign_keys)
+      generate_foreign_keys.in?([true, false]) or raise ArgumentError, "generate_foreign_keys must be either true or false (got #{generate_foreign_keys.inspect})"
+      @default_generate_foreign_keys = generate_foreign_keys
+    end
+
+    def default_generate_indexing=(generate_indexing)
+      generate_indexing.in?([true, false]) or raise ArgumentError, "generate_indexing must be either true or false (got #{generate_indexing.inspect})"
+      @default_generate_indexing = generate_indexing
+    end
   end
 end
 

data/lib/declare_schema/dsl.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'active_support/proxy_object'
+
+module DeclareSchema
+  class Dsl < BasicObject # avoid Object because that gets extended by lots of gems
+    include ::Kernel      # but we need the basic class methods
+
+    instance_methods.each do |m|
+      unless m.to_s.starts_with?('__') || m.in?([:object_id, :instance_eval])
+        undef_method(m)
+      end
+    end
+
+    def initialize(model, options = {})
+      @model = model
+      @options = options
+    end
+
+    attr_reader :model
+
+    def timestamps
+      field(:created_at, :datetime, null: true)
+      field(:updated_at, :datetime, null: true)
+    end
+
+    def optimistic_lock
+      field(:lock_version, :integer, default: 1, null: false)
+    end
+
+    def field(name, type, *args, **options)
+      @model.declare_field(name, type, *(args + [@options.merge(options)]))
+    end
+
+    def method_missing(type, name, *args)
+      field(name, type, *args)
+    end
+  end
+end

data/lib/declare_schema/extensions/active_record/fields_declaration.rb

@@ -1,21 +1,40 @@
 # frozen_string_literal: true
 
 require 'active_record'
+require 'declare_schema/dsl'
 require 'declare_schema/model'
 require 'declare_schema/field_declaration_dsl'
 
 module DeclareSchema
-  module FieldsDsl
+  module Macros
     def fields(table_options = {}, &block)
       # Any model that calls 'fields' gets DeclareSchema::Model behavior
       DeclareSchema::Model.mix_in(self)
 
-      # @include_in_migration = false #||= options.fetch(:include_in_migration, true); options.delete(:include_in_migration)
       @include_in_migration = true
       @table_options        = table_options
 
       if block
-        dsl = DeclareSchema::FieldDeclarationDsl.new(self, null: false)
+        dsl = DeclareSchema::FieldDeclarationDsl.new(self)
+        if block.arity == 1
+          yield dsl
+        else
+          dsl.instance_eval(&block)
+        end
+      end
+    end
+    deprecate :fields, deprecator: ActiveSupport::Deprecation.new('1.0', 'DeclareSchema')
+
+    def declare_schema(table_options = {}, &block)
+      # Any model that calls 'fields' gets DeclareSchema::Model behavior
+      DeclareSchema::Model.mix_in(self)
+
+      # @include_in_migration = false #||= options.fetch(:include_in_migration, true); options.delete(:include_in_migration)
+      @include_in_migration = true # TODO: Add back or delete the include_in_migration feature
+      @table_options        = table_options
+
+      if block
+        dsl = DeclareSchema::Dsl.new(self, null: false)
         if block.arity == 1
           yield dsl
         else
@@ -26,4 +45,4 @@ module DeclareSchema
   end
 end
 
-ActiveRecord::Base.singleton_class.prepend DeclareSchema::FieldsDsl
+ActiveRecord::Base.singleton_class.prepend DeclareSchema::Macros

data/lib/declare_schema/model.rb

@@ -38,24 +38,24 @@ module DeclareSchema
 
           # eval avoids the ruby 1.9.2 "super from singleton method ..." error
 
-          eval %(
+          eval <<~EOS
             def self.inherited(klass)
               unless klass.field_specs.has_key?(inheritance_column)
-                fields do |f|
+                declare_schema do |f|
                   f.field(inheritance_column, :string, limit: 255, null: true)
                 end
                 index(inheritance_column)
               end
               super
             end
-          )
+          EOS
         end
       end
     end
 
     module ClassMethods
       def index(fields, options = {})
-        # don't double-index fields
+        # make index idempotent
         index_fields_s = Array.wrap(fields).map(&:to_s)
         unless index_definitions.any? { |index_spec| index_spec.fields == index_fields_s }
           index_definitions << ::DeclareSchema::Model::IndexDefinition.new(self, fields, options)
@@ -74,7 +74,7 @@ module DeclareSchema
       end
 
       # tell the migration generator to ignore the named index. Useful for existing indexes, or for indexes
-      # that can't be automatically generated (for example: an prefix index in MySQL)
+      # that can't be automatically generated (for example: a prefix index in MySQL)
       def ignore_index(index_name)
         ignore_indexes << index_name.to_s
       end
@@ -85,10 +85,10 @@ module DeclareSchema
       # declarations.
       def declare_field(name, type, *args, **options)
         try(:field_added, name, type, args, options)
-        add_serialize_for_field(name, type, options)
-        add_formatting_for_field(name, type)
-        add_validations_for_field(name, type, args, options)
-        add_index_for_field(name, args, options)
+        _add_serialize_for_field(name, type, options)
+        _add_formatting_for_field(name, type)
+        _add_validations_for_field(name, type, args, options)
+        _add_index_for_field(name, args, options)
         field_specs[name] = ::DeclareSchema::Model::FieldSpec.new(self, name, type, position: field_specs.size, **options)
         attr_order << name unless attr_order.include?(name)
       end
@@ -97,41 +97,10 @@ module DeclareSchema
         if index_definitions.any?(&:primary_key?)
           index_definitions
         else
-          index_definitions + [rails_default_primary_key]
+          index_definitions + [_rails_default_primary_key]
         end
       end
 
-      if ::Rails::VERSION::MAJOR < 5
-        def primary_key
-          super || 'id'
-        end
-      end
-
-      # returns the primary key (String) as declared with primary_key =
-      # unlike the `primary_key` method, DOES NOT query the database to find the actual primary key in use right now
-      # if no explicit primary key set, returns the default_defined_primary_key
-      def defined_primary_key
-        if defined?(@primary_key)
-          @primary_key&.to_s
-        end || default_defined_primary_key
-      end
-
-      # if this is a derived class, returns the base class's defined_primary_key
-      # otherwise, returns 'id'
-      def default_defined_primary_key
-        if self == base_class
-          'id'
-        else
-          base_class.defined_primary_key
-        end
-      end
-
-      private
-
-      def rails_default_primary_key
-        ::DeclareSchema::Model::IndexDefinition.new(self, [primary_key.to_sym], unique: true, name: DeclareSchema::Model::IndexDefinition::PRIMARY_KEY_NAME)
-      end
-
       # Extend belongs_to so that it creates a FieldSpec for the foreign key
       def belongs_to(name, scope = nil, **options)
         column_options = {}
@@ -172,7 +141,7 @@ module DeclareSchema
         declare_field(fkey.to_sym, :integer, column_options)
         if refl.options[:polymorphic]
           foreign_type = options[:foreign_type] || "#{name}_type"
-          declare_polymorphic_type_field(foreign_type, column_options)
+          _declare_polymorphic_type_field(foreign_type, column_options)
           index([foreign_type, fkey], index_options) if index_options[:name] != false
         else
           index(fkey, index_options) if index_options[:name] != false
@@ -180,26 +149,49 @@ module DeclareSchema
         end
       end
 
+      if ::Rails::VERSION::MAJOR < 5
+        def primary_key
+          super || 'id'
+        end
+      end
+
+      # returns the primary key (String) as declared with primary_key =
+      # unlike the `primary_key` method, DOES NOT query the database to find the actual primary key in use right now
+      # if no explicit primary key set, returns the default_defined_primary_key
+      def _defined_primary_key
+        if defined?(@primary_key)
+          @primary_key&.to_s
+        end || _default_defined_primary_key
+      end
+
+      private
+
+      # if this is a derived class, returns the base class's _defined_primary_key
+      # otherwise, returns 'id'
+      def _default_defined_primary_key
+        if self == base_class
+          'id'
+        else
+          base_class._defined_primary_key
+        end
+      end
+
+      def _rails_default_primary_key
+        ::DeclareSchema::Model::IndexDefinition.new(self, [_defined_primary_key.to_sym], unique: true, name: DeclareSchema::Model::IndexDefinition::PRIMARY_KEY_NAME)
+      end
+
       # Declares the "foo_type" field that accompanies the "foo_id"
       # field for a polymorphic belongs_to
-      def declare_polymorphic_type_field(foreign_type, column_options)
+      def _declare_polymorphic_type_field(foreign_type, column_options)
         declare_field(foreign_type, :string, column_options.merge(limit: 255))
         # FIXME: Before declare_schema was extracted, this used to now do:
         # never_show(type_col)
         # That needs doing somewhere
       end
 
-      # Declare a rich-type for any attribute (i.e. getter method). This
-      # does not effect the attribute in any way - it just records the
-      # metadata.
-      def declare_attr_type(name, type, options = {})
-        attr_types[name] = klass = DeclareSchema.to_class(type)
-        klass.try(:declared, self, name, options)
-      end
-
       # Add field validations according to arguments in the
       # field declaration
-      def add_validations_for_field(name, type, args, options)
+      def _add_validations_for_field(name, type, args, options)
         validates_presence_of   name if :required.in?(args)
         validates_uniqueness_of name, allow_nil: !:required.in?(args) if :unique.in?(args)
 
@@ -218,18 +210,18 @@ module DeclareSchema
         end
       end
 
-      def add_serialize_for_field(name, type, options)
+      def _add_serialize_for_field(name, type, options)
         if (serialize_class = options.delete(:serialize))
           type == :string || type == :text or raise ArgumentError, "serialize field type must be :string or :text"
           serialize_args = Array((serialize_class unless serialize_class == true))
           serialize(name, *serialize_args)
           if options.has_key?(:default)
-            options[:default] = serialized_default(name, serialize_class == true ? Object : serialize_class, options[:default])
+            options[:default] = _serialized_default(name, serialize_class == true ? Object : serialize_class, options[:default])
           end
         end
       end
 
-      def serialized_default(attr_name, class_name_or_coder, default)
+      def _serialized_default(attr_name, class_name_or_coder, default)
         # copied from https://github.com/rails/rails/blob/7d6cb950e7c0e31c2faaed08c81743439156c9f5/activerecord/lib/active_record/attribute_methods/serialization.rb#L70-L76
         coder = if class_name_or_coder == ::JSON
                   ActiveRecord::Coders::JSON
@@ -248,7 +240,7 @@ module DeclareSchema
         end
       end
 
-      def add_formatting_for_field(name, type)
+      def _add_formatting_for_field(name, type)
         if (type_class = DeclareSchema.to_class(type))
           if "format".in?(type_class.instance_methods)
             before_validation do |record|
@@ -258,7 +250,7 @@ module DeclareSchema
         end
       end
 
-      def add_index_for_field(name, args, options)
+      def _add_index_for_field(name, args, options)
         if (to_name = options.delete(:index))
           index_opts =
             {
@@ -287,13 +279,13 @@ module DeclareSchema
               refl
             end
           end ||
-          if (col = column(name.to_s))
+          if (col = _column(name.to_s))
             DeclareSchema::PLAIN_TYPES[col.type] || col.klass
           end
       end
 
       # Return the entry from #columns for the named column
-      def column(name)
+      def _column(name)
         defined?(@table_exists) or @table_exists = table_exists?
         if @table_exists
           columns_hash[name.to_s]