declare_schema 1.3.2 → 1.4.0.colin.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 474856e02a14224230a41cc4ef32234b8d20b69a647a30f810bce457c220261e
-  data.tar.gz: 13994a873d83d5bce533b71f36c3057a0a0caf8c7559f809091a7dc6627f5f7c
+  metadata.gz: 33160a248adef9ac404a1efa4f6446fedabc2ddc49b02f0434ff3e1a91bfa8b2
+  data.tar.gz: ff9b214dfb3d31904927c906f244312571967de575ffcdadd4f100558bc3ffe4
 SHA512:
-  metadata.gz: 7b298b54b826e8bb464c544ab2015ddca0a761cda03f03724598158617b89cef0b0f19521a103898e92157cad11d32e9feb71c1293a36bbc2c3a666c123d444f
-  data.tar.gz: 5e0c12a370ed83eeb31f398e124597a00dd7b5872d08b8c47e1eb2fb5842c6b295b251d2b58ff26619af8c92ca0342ac8bf585652c9822409dfab40798d0f086
+  metadata.gz: aae64d3b2dff696f0ac532831df033fd0433e41eca6018c74eb07088ea2d0384e30bdae0c6648087ed15e367094558ec040b05f2869d7d28009f3396c343147a
+  data.tar.gz: 776c0b887fcbb9566b9b3347e8359c5ddd7b40020816ce18494ad6897eee5bc9b0e827167ae9ba759b3dcec4cd3244ea62c9a79e1f351e266a319339ca2534d7

data/CHANGELOG.md

@@ -4,6 +4,12 @@ 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).
 
+## [1.4] - Unreleased
+### Added
+- Added support for partial indexes with `length:` option.
+### Changed
+- Deprecate index: 'name' and unique: true|false in favor of index: { name: 'name', unique: true|false }.
+
 ## [1.3.2] - 2024-01-12
 ### Fixed
 - Fix bug in migrator when table option definitions differ

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    declare_schema (1.3.2)
+    declare_schema (1.4.0.colin.2)
       rails (>= 5.0)
 
 GEM

data/README.md

@@ -9,7 +9,7 @@ Make a model and declare your schema within a `declare_schema do ... end` block:
 class Company < ActiveRecord::Base
   declare_schema do
     string  :company_name,  limit: 100
-    string  :ticker_symbol, limit: 4, null: true, index: true, unique: true
+    string  :ticker_symbol, limit: 4, null: true, index: { unique: true }
     integer :employee_count
     text    :comments
 
@@ -60,6 +60,61 @@ declare_schema id: :bigint do
 end
 ```
 
+## declare_schema DSL field (column) declaration
+The `declare_schema` DSL is yielded to the block as shown with block variable `t` (for table).
+Each field (column) is declared with the syntax `t.<type> :<column_name>, <options>` as shown here for the `string` column `company_name`:
+```ruby
+create_table :companies, id: :bigint do |t|
+  t.string   :company_name, null: false, limit: 100
+    ...
+end
+```
+### Field (Column) Types
+All of the ActiveRecord field types are supported, as returned by the database driver in use at the time.
+These typically include:
+- `binary` (blob)
+- `text`
+- `integer`
+- `bigint`
+- `float`
+- `decimal`
+- `date`
+- `time`
+- `datetime`
+- `timestamp`
+- `string` (varchar)
+- `boolean` (tinyint 0 or 1)
+- `json`
+- `array`
+- `enum` (if using the `activerecord-mysql-enum` gem) (MySQL enum)
+
+### Field (Column) Options
+The following field options are:
+- `limit` (integer) - The maximum length of the field. For `text` and `binary` fields, this is the maximum number of bytes.
+ For `string` fields, this is the maximum number of characters, and defaults to `DeclareSchema.default_string_limit`; for `text`, defaults to `DeclareSchema.default_text_limit`.
+ For `enum`
+- `null` (boolean) - Whether the field is nullable. Defaults to `DeclareSchema.default_null`.
+- `default` (any) - The default value for the field.
+- `ruby_default` (Proc) - A callable Ruby Proc that returns the default value for the field. This is useful for default values that require Ruby computation.
+  (Provided by the `attr_default` gem.)
+- `index` (boolean [deprecated] or hash) - Whether to create an index for the field. If `true`, defaults to `{ unique: false }` [deprecated]. See below for supported `index` options.
+- `unique` [deprecated] (boolean) - Whether to create a unique index for the field. Defaults to `false`. Deprecated in favor of `index: { unique: <boolean> }`.
+- `charset` (string) - The character set for the field. Defaults to `default_charset` (see below).
+- `collation` (string) - The collation for the field. Defaults to `default_collation` (see below).
+- `precision` (integer) - The precision for the numeric field.
+- `scale` (integer) - The scale for the numeric field.
+
+### Index Options
+The following `index` options are supported:
+- `name` (string) - The name of the index. Defaults the longest format that will fit within `DeclareSchema.max_index_and_constraint_name_length`. They are tried in this order:
+1. `index_<table>_on_<col1>[_and_<col2>...]>`.
+2. `__<col1>[_<col2>...]>`
+3. `<table_prefix><sha256_of_columns_prefix>`
+- `unique` (boolean) - Whether the index is unique. Defaults to `false`.
+- `order` (synbol or hash) - The index order. If `:asc` or `:desc` is provided, it is used as the order for all columns. If hash is provided, it is used to specify the order of individual columns, where the column names are given as `Symbol` hash keys with values of `:asc` or `:desc` indicating the sort order of that column.
+- `length` (integer or hash) - The partial index length(s). If an integer is provided, it is used as the length for all columns. If a hash is provided, it is used to specify the length for individual columns, where the column names are given as `Symbol` hash keys.
+- `where` (string) - The subset index predicate.
+
 ## Usage without Rails
 
 When using `DeclareSchema` without Rails, you can use the `declare_schema/rake` task to generate the migration file.
@@ -115,13 +170,13 @@ end
 ```
 
 ### clear_default_schema
-This method clears out any previously declared `default_schema`.
+This method clears out any previously declared `default_schema`. This can be useful for tests.
 ```ruby
 DeclareSchema.clear_default_schema
 ```
 
 ### Global Configuration
-Configurations can be set at the global level to customize default declaration for the following values:
+Configurations can be set at globally to customize default declaration for the following values:
 
 #### Text Limit
 The default text limit can be set using the `DeclareSchema.default_text_limit=` method.
@@ -134,8 +189,6 @@ set the default `text limit` value to `0xffff`:
 
 **declare_schema.rb**
 ```ruby
-# frozen_string_literal: true
-
 DeclareSchema.default_text_limit = 0xffff
 ```
 
@@ -150,8 +203,6 @@ set the default `string limit` value to `255`:
 
 **declare_schema.rb**
 ```ruby
-# frozen_string_literal: true
-
 DeclareSchema.default_string_limit = 255
 ```
 
@@ -166,40 +217,34 @@ 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.
+You can choose whether to generate foreign keys by using the `DeclareSchema.default_generate_foreign_keys=` method.
+This defaults to `true` and can only be set globally.
 
-For example, adding the following to your `config/initializers` directory will set
-the default `generate foreign keys` value to `false`:
+For example, adding the following to your `config/initializers` directory will cause
+foreign keys not to be generated:
 
 **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.
+You can choose whether to generate indexes automatically by using the `DeclareSchema.default_generate_indexing=` method.
+This defaults to `true` and can only be set globally.
 
-For example, adding the following to your `config/initializers` directory will
-set the default `generate indexing` value to `false`:
+For example, adding the following to your `config/initializers` directory will cause
+indexes not to be generated by `declare_schema`:
 
 **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
+The character set and collation for all tables and fields can be set at globally
 using the `Generators::DeclareSchema::Migrator.default_charset=` and
 `Generators::DeclareSchema::Migrator.default_collation=` configuration methods.
 
@@ -208,8 +253,6 @@ turn all tables into `utf8mb4` supporting tables:
 
 **declare_schema.rb**
 ```ruby
-# frozen_string_literal: true
-
 DeclareSchema.default_charset   = "utf8mb4"
 DeclareSchema.default_collation = "utf8mb4_bin"
 ```
@@ -221,7 +264,7 @@ bundle exec rails db:migrate
 ```
 If your repo has a different command to run for migrations, you can configure it like this:
 ```ruby
-`DeclareSchema.db_migrate_command = "bundle exec rails db:migrate_immediate"`
+DeclareSchema.db_migrate_command = "bundle exec rails db:migrate_immediate"
 ```
 
 ## The `belongs_to` Association
@@ -230,24 +273,16 @@ association is outside of the `declare_schema do` block, so `declare_schema` int
 infer the foreign key column.
 
 By default, `declare_schema` creates an index for `belongs_to` relations. If this default index is not desired,
-you can use `index: false` in the `belongs_to` expression. This may be the case if for example a different index
-already accounts for it.
+you can use `index: false` in the `belongs_to` expression. This may be the case if, for example, a different index
+already covers those columns at the front.
 
 ## The `has_and_belongs_to_many` Association
 Like the `belongs_to` association, `has_and_belongs_to_many` is outside of the `declare_schema ` block. `declare_schema` similarly
 infers foreign keys (and the intersection table).
 
 ## Ignored Tables
-If a table's schema or metadata are managed elsewhere, `declare_schema` probably should not alter it. Accordingly,
-`declare_schema` can be configured to ignore tables.
-
-`declare_schema` by default ignores these tables:
-- The ActiveRecord `schema_info` table
-- The ActiveRecord schema migrations table (generally named `schema_migrations`)
-- The ActiveRecord internal metadata table (generally named `ar_internal_metadata`)
-- If defined/configured, the CGI ActiveRecordStore session table
-
-Additional tables can be ignored by configuring `Generators::DeclareSchema::Migration::Migrator.ignore_tables`.
+If a table's schema or metadata are managed elsewhere, `declare_schema` can be instructed to ignore it
+by adding those table names to the array assigned to `Generators::DeclareSchema::Migration::Migrator.ignore_tables`.
 For example:
 
 ```ruby
@@ -258,6 +293,12 @@ For example:
 ]
 ```
 
+Note: `declare_schema` always ignores these tables:
+- The ActiveRecord `schema_info` table
+- The ActiveRecord schema migrations table (generally named `schema_migrations`)
+- The ActiveRecord internal metadata table (generally named `ar_internal_metadata`)
+- If defined/configured, the CGI ActiveRecordStore session table
+
 ## Maximum Length of Index and Constraint Names
 
 MySQL limits the length of index and constraint names to 64 characters.
@@ -279,7 +320,10 @@ But later, Unicode was extended beyond U+FFFF to make room for emojis, and with
 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
+at three separate levels.
+
+### Global Configuration
+The global configuration option is explained above in the [Character Set and Collation](#Character-Set-and-Collation) section.
 
 ### Table Configuration
 In order to configure a table's default character set and collation, the `charset` and

data/lib/declare_schema/model/index_definition.rb

@@ -8,7 +8,8 @@ module DeclareSchema
       include Comparable
 
       # TODO: replace `fields` with `columns` and remove alias. -Colin
-      attr_reader :table, :fields, :explicit_name, :name, :unique, :where
+      OPTIONS = [:name, :unique, :where, :length].freeze
+      attr_reader :table, :fields, :explicit_name, *OPTIONS
       alias columns fields
 
       class IndexNameTooLongError < RuntimeError; end
@@ -22,14 +23,17 @@ module DeclareSchema
         @explicit_name = options[:name] unless options.delete(:allow_equivalent)
         @name = options.delete(:name) || self.class.default_index_name(@table, @fields)
         @unique = options.delete(:unique) || name == PRIMARY_KEY_NAME || false
+        @length = options.delete(:length)
 
         if DeclareSchema.max_index_and_constraint_name_length && @name.length > DeclareSchema.max_index_and_constraint_name_length
           raise IndexNameTooLongError, "Index '#{@name}' exceeds configured limit of #{DeclareSchema.max_index_and_constraint_name_length} characters. Give it a shorter name, or adjust DeclareSchema.max_index_and_constraint_name_length if you know your database can accept longer names."
         end
 
-        if (where = options[:where])
+        if (where = options.delete(:where))
           @where = where.start_with?('(') ? where : "(#{where})"
         end
+
+        options.any? and warn("ignoring unrecognized option(s): #{options.inspect} for model #{model}")
       end
 
       class << self
@@ -102,12 +106,21 @@ module DeclareSchema
         name == PRIMARY_KEY_NAME
       end
 
+      def options
+        @options ||=
+          OPTIONS.each_with_object({}) do |option, result|
+            result[option] = send(option)
+          end.freeze
+      end
+
+      # Unique key for this object. Used for equality checking.
       def to_key
-        @key ||= [table, fields, name, unique, where].map(&:to_s)
+        @key ||= [table, fields, options].freeze
       end
 
+      # The index settings for this object. Used for equivalence checking. Does not include the name.
       def settings
-        @settings ||= [table, fields, unique].map(&:to_s)
+        @settings ||= [table, fields, options.except(:name)].freeze
       end
 
       def hash
@@ -123,7 +136,7 @@ module DeclareSchema
       end
 
       def with_name(new_name)
-        self.class.new(@model, @fields, table_name: @table_name, index_name: @index_name, unique: @unique, name: new_name)
+        self.class.new(@model, @fields, **{ **options, name: new_name })
       end
 
       alias eql? ==

data/lib/declare_schema/model.rb

@@ -51,9 +51,9 @@ module DeclareSchema
     module ClassMethods
       def index(fields, **options)
         # 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)
+        index = ::DeclareSchema::Model::IndexDefinition.new(self, fields, **options)
+        unless index_definitions.any? { |index_spec| index_spec.equivalent?(index) }
+          index_definitions << index
         end
       end
 
@@ -114,14 +114,36 @@ module DeclareSchema
           ActiveSupport::Deprecation.warn("belongs_to limit: is deprecated since it is now inferred")
         end
 
-        index_options = {}
-        index_options[:name]   = options.delete(:index) if options.has_key?(:index)
-        index_options[:unique] = options.delete(:unique) if options.has_key?(:unique)
-        index_options[:allow_equivalent] = options.delete(:allow_equivalent) if options.has_key?(:allow_equivalent)
+        # index: true means create an index on the foreign key
+        # index: false means do not create an index on the foreign key
+        # index: { ... } means create an index on the foreign key with the given options
+        index_value = options.delete(:index)
+        if index_value != false || options.has_key?(:unique) || options.has_key?(:allow_equivalent)
+          index_options = {}
+          case index_value
+          when String
+            Kernel.warn("belongs_to index: 'name' is deprecated; use index: { name: 'name' } instead (in #{self.class.name})")
+            index_options[:name] = index_value
+          # when false -- impossible since we checked that above
+          when true
+          when nil
+          when Hash
+            index_options = index_value
+          else
+            raise ArgumentError, "belongs_to index: must be true or false or a Hash; got #{index_value.inspect}"
+          end
+
+          if options.has_key?(:unique)
+            Kernel.warn("belongs_to unique: true|false is deprecated; use index: { unique: true|false } instead (in #{self.class.name})")
+            index_options[:unique] = options.delete(:unique)
+          end
+
+          index_options[:allow_equivalent] = options.delete(:allow_equivalent) if options.has_key?(:allow_equivalent)
+        end
 
         fk_options = options.dup
         fk_options[:constraint_name] = options.delete(:constraint) if options.has_key?(:constraint)
-        fk_options[:index_name] = index_options[:name]
+        fk_options[:index_name] = index_options&.[](:name)
 
         fk = options[:foreign_key]&.to_s || "#{name}_id"
 
@@ -157,9 +179,9 @@ module DeclareSchema
         if refl.options[:polymorphic]
           foreign_type = options[:foreign_type] || "#{name}_type"
           _declare_polymorphic_type_field(foreign_type, column_options)
-          index([foreign_type, fkey], **index_options) if index_options[:name] != false
+          index([foreign_type, fkey], **index_options) if index_options
         else
-          index(fkey, **index_options) if index_options[:name] != false
+          index(fkey, **index_options) if index_options
           constraint(fkey, **fk_options) if fk_options[:constraint_name] != false
         end
       end
@@ -283,7 +305,7 @@ module DeclareSchema
         if (to_name = options.delete(:index))
           index_opts =
             {
-              unique: args.include?(:unique) || options.delete(:unique)
+              unique: args.include?(:unique) || !!options.delete(:unique)
             }
           # support index: true declaration
           index_opts[:name] = to_name unless to_name == true

data/lib/declare_schema/schema_change/index_add.rb

@@ -5,12 +5,13 @@ require_relative 'base'
 module DeclareSchema
   module SchemaChange
     class IndexAdd < Base
-      def initialize(table_name, column_names, name:, unique:, where: nil)
+      def initialize(table_name, column_names, name:, unique:, where: nil, length: nil)
         @table_name = table_name
         @column_names = column_names
         @name = name
         @unique = unique
         @where = where.presence
+        @length = length
       end
 
       def up_command
@@ -19,6 +20,7 @@ module DeclareSchema
         }
         options[:unique] = true if @unique
         options[:where] = @where if @where
+        options[:length] = @length if @length
 
         "add_index #{[@table_name.to_sym.inspect,
                       @column_names.map(&:to_sym).inspect,

data/lib/declare_schema/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeclareSchema
-  VERSION = "1.3.2"
+  VERSION = "1.4.0.colin.2"
 end

data/lib/generators/declare_schema/migration/migrator.rb

@@ -330,7 +330,7 @@ module Generators
         # TODO: TECH-5338: optimize that index doesn't need to be dropped on undo since entire table will be dropped
         def create_indexes(model)
           model.index_definitions.map do |i|
-            ::DeclareSchema::SchemaChange::IndexAdd.new(model.table_name, i.columns, unique: i.unique, where: i.where, name: i.name)
+            ::DeclareSchema::SchemaChange::IndexAdd.new(model.table_name, i.columns, **i.options)
           end
         end
 
@@ -457,11 +457,11 @@ module Generators
           renamed_indexes_to_drop, renamed_indexes_to_add = index_changes_due_to_column_renames(indexes_to_drop, indexes_to_add, to_rename)
 
           drop_indexes = (indexes_to_drop - renamed_indexes_to_drop).map do |i|
-            ::DeclareSchema::SchemaChange::IndexRemove.new(new_table_name, i.columns, unique: i.unique, where: i.where, name: i.name)
+            ::DeclareSchema::SchemaChange::IndexRemove.new(new_table_name, i.columns, **i.options)
           end
 
           add_indexes = (indexes_to_add - renamed_indexes_to_add).map do |i|
-            ::DeclareSchema::SchemaChange::IndexAdd.new(new_table_name, i.columns, unique: i.unique, where: i.where, name: i.name)
+            ::DeclareSchema::SchemaChange::IndexAdd.new(new_table_name, i.columns, **i.options)
           end
 
           # the order is important here - adding a :unique, for instance needs to remove then add

data/spec/lib/declare_schema/migration_generator_spec.rb

@@ -108,8 +108,8 @@ RSpec.describe 'DeclareSchema Migration Generator' do
           add_column :adverts, :published_at, :datetime, null: true
         EOS
         .and migrate_down(<<~EOS.strip)
-          remove_column :adverts, :published_at
-          remove_column :adverts, :body
+            remove_column :adverts, :published_at
+            remove_column :adverts, :body
         EOS
       )
 
@@ -141,8 +141,8 @@ RSpec.describe 'DeclareSchema Migration Generator' do
           remove_column :adverts, :name
         EOS
         .and migrate_down(<<~EOS.strip)
-          add_column :adverts, :name, :string, limit: 250, null: true#{charset_and_collation}
-          remove_column :adverts, :title
+            add_column :adverts, :name, :string, limit: 250, null: true#{charset_and_collation}
+            remove_column :adverts, :title
         EOS
       )
 
@@ -179,7 +179,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
           change_column :adverts, :title, :string, limit: 250, null: true, default: "Untitled"#{charset_and_collation}
           EOS
               .and migrate_down(<<~EOS.strip)
-          change_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
+              change_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
       EOS
       )
 
@@ -209,7 +209,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
           change_column :adverts, :price, :integer, limit: 3, null: true
           EOS
               .and migrate_down(<<~EOS.strip)
-          change_column :adverts, :price, :integer, limit: 2, null: true
+              change_column :adverts, :price, :integer, limit: 2, null: true
       EOS
       )
 
@@ -306,7 +306,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
             change_column :adverts, :description, :text, limit: 4294967295, null: false#{charset_and_collation}
             EOS
                 .and migrate_down(<<~EOS.strip)
-            change_column :adverts, :description, :text#{', limit: 255' if defined?(Mysql2)}, null: true#{charset_and_collation}
+                change_column :adverts, :description, :text#{', limit: 255' if defined?(Mysql2)}, null: true#{charset_and_collation}
         EOS
         )
 
@@ -323,7 +323,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
             change_column :adverts, :description, :text, limit: 4294967295, null: false#{charset_and_collation}
             EOS
                 .and migrate_down(<<~EOS.strip)
-            change_column :adverts, :description, :text#{', limit: 255' if defined?(Mysql2)}, null: true#{charset_and_collation}
+                change_column :adverts, :description, :text#{', limit: 255' if defined?(Mysql2)}, null: true#{charset_and_collation}
         EOS
         )
       end
@@ -363,14 +363,14 @@ RSpec.describe 'DeclareSchema Migration Generator' do
           #{"add_foreign_key :adverts, :categories, column: :category_id, name: :index_adverts_on_category_id\n" if defined?(Mysql2)}
         EOS
         .and migrate_down(<<~EOS.strip)
-          #{"remove_foreign_key :adverts, name: :index_adverts_on_category_id" if defined?(Mysql2)}
-          remove_index :adverts, name: :index_adverts_on_category_id
-          remove_column :adverts, :category_id
+            #{"remove_foreign_key :adverts, name: :index_adverts_on_category_id" if defined?(Mysql2)}
+            remove_index :adverts, name: :index_adverts_on_category_id
+            remove_column :adverts, :category_id
         EOS
       )
 
       Advert.field_specs.delete(:category_id)
-      Advert.index_definitions.delete_if { |spec| spec.fields==["category_id"] }
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["category_id"] }
 
       # If you specify a custom foreign key, the migration generator observes that:
 
@@ -411,7 +411,9 @@ RSpec.describe 'DeclareSchema Migration Generator' do
       Advert.field_specs.delete(:category_id)
       Advert.index_definitions.delete_if { |spec| spec.fields == ["category_id"] }
 
-      # You can specify the index name with :index
+      # You can specify the index name with index: 'name' [deprecated]
+
+      expect(Kernel).to receive(:warn).with(/belongs_to index: 'name' is deprecated; use index: \{ name: 'name' \} instead/i)
 
       class Category < ActiveRecord::Base; end
       class Advert < ActiveRecord::Base
@@ -431,6 +433,26 @@ RSpec.describe 'DeclareSchema Migration Generator' do
       Advert.field_specs.delete(:category_id)
       Advert.index_definitions.delete_if { |spec| spec.fields == ["category_id"] }
 
+      # You can specify the index name with index: { name: }'name', unique: true|false }
+
+      class Category < ActiveRecord::Base; end
+      class Advert < ActiveRecord::Base
+        declare_schema { }
+        belongs_to :category, index: { name: 'my_index', unique: false }
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+            add_column :adverts, :category_id, :integer, limit: 8, null: false
+            add_index :adverts, [:category_id], name: :my_index
+            #{"add_foreign_key :adverts, :categories, column: :category_id, name: :index_adverts_on_category_id\n" +
+          "add_foreign_key :adverts, :categories, column: :c_id, name: :index_adverts_on_c_id" if defined?(Mysql2)}
+      EOS
+      )
+
+      Advert.field_specs.delete(:category_id)
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["category_id"] }
+
       ### Timestamps and Optimimistic Locking
 
       # `updated_at` and `created_at` can be declared with the shorthand `timestamps`.
@@ -452,11 +474,11 @@ RSpec.describe 'DeclareSchema Migration Generator' do
             "add_foreign_key :adverts, :categories, column: :c_id, name: :index_adverts_on_c_id" if defined?(Mysql2)}
         EOS
         .and migrate_down(<<~EOS.strip)
-          #{"remove_foreign_key :adverts, name: :index_adverts_on_c_id\n" +
-            "remove_foreign_key :adverts, name: :index_adverts_on_category_id" if defined?(Mysql2)}
-          remove_column :adverts, :lock_version
-          remove_column :adverts, :updated_at
-          remove_column :adverts, :created_at
+            #{"remove_foreign_key :adverts, name: :index_adverts_on_c_id\n" +
+              "remove_foreign_key :adverts, name: :index_adverts_on_category_id" if defined?(Mysql2)}
+            remove_column :adverts, :lock_version
+            remove_column :adverts, :updated_at
+            remove_column :adverts, :created_at
         EOS
       )
 
@@ -468,22 +490,29 @@ RSpec.describe 'DeclareSchema Migration Generator' do
 
       # You can add an index to a field definition
 
+      expect(Kernel).to receive(:warn).with(/belongs_to index: 'name' is deprecated; use index: \{ name: 'name' \} instead/i)
+      expect(Kernel).to receive(:warn).with(/belongs_to unique: true\|false is deprecated; use index: \{ unique: true\|false \} instead/i)
+
       class Advert < ActiveRecord::Base
         declare_schema do
           string :title, index: true, limit: 250, null: true
         end
+        belongs_to :category, index: 'my_index', unique: false
       end
 
       expect(Generators::DeclareSchema::Migration::Migrator.run).to(
         migrate_up(<<~EOS.strip)
           add_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
+          add_column :adverts, :category_id, :integer, limit: 8, null: false
           add_index :adverts, [:title], name: :index_adverts_on_title
+          add_index :adverts, [:category_id], name: :my_index
           #{"add_foreign_key :adverts, :categories, column: :category_id, name: :index_adverts_on_category_id\n" +
             "add_foreign_key :adverts, :categories, column: :c_id, name: :index_adverts_on_c_id" if defined?(Mysql2)}
         EOS
       )
 
-      Advert.index_definitions.delete_if { |spec| spec.fields==["title"] }
+      Advert.field_specs.delete(:category_id)
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] || spec.fields == ["category_id"] }
 
       # You can ask for a unique index
 
@@ -521,7 +550,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
         EOS
       )
 
-      Advert.index_definitions.delete_if { |spec| spec.fields==["title"] }
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
 
       # You can ask for an index outside of the fields block
 
@@ -540,16 +569,16 @@ RSpec.describe 'DeclareSchema Migration Generator' do
 
       Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
 
-      # The available options for the index function are `:unique` and `:name`
+      # The available options for the index function are :unique, :name, :where, and :length.
 
       class Advert < ActiveRecord::Base
-        index :title, unique: true, name: 'my_index'
+        index :title, unique: false, name: 'my_index', length: 10
       end
 
       expect(Generators::DeclareSchema::Migration::Migrator.run).to(
         migrate_up(<<~EOS.strip)
           add_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
-          add_index :adverts, [:title], name: :my_index, unique: true
+          add_index :adverts, [:title], name: :my_index, length: 10
           #{"add_foreign_key :adverts, :categories, column: :category_id, name: :index_adverts_on_category_id\n" +
             "add_foreign_key :adverts, :categories, column: :c_id, name: :index_adverts_on_c_id" if defined?(Mysql2)}
         EOS
@@ -572,7 +601,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
         EOS
       )
 
-      Advert.index_definitions.delete_if { |spec| spec.fields==["title", "category_id"] }
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["title", "category_id"] }
 
       # Finally, you can specify that the migration generator should completely ignore an
       # index by passing its name to ignore_index in the model.
@@ -645,10 +674,10 @@ RSpec.describe 'DeclareSchema Migration Generator' do
           remove_column :advertisements, :name
         EOS
         .and migrate_down(<<~EOS.strip)
-          add_column :advertisements, :name, :string, limit: 250, null: true#{charset_and_collation}
-          remove_column :advertisements, :body
-          remove_column :advertisements, :title
-          rename_table :advertisements, :adverts
+            add_column :advertisements, :name, :string, limit: 250, null: true#{charset_and_collation}
+            remove_column :advertisements, :body
+            remove_column :advertisements, :title
+            rename_table :advertisements, :adverts
         EOS
       )
 
@@ -665,9 +694,9 @@ RSpec.describe 'DeclareSchema Migration Generator' do
           drop_table :adverts
         EOS
         .and migrate_down(<<~EOS.strip)
-          create_table "adverts"#{table_options}, force: :cascade do |t|
-            t.string "name", limit: 250#{charset_and_collation}
-          end
+            create_table "adverts"#{table_options}, force: :cascade do |t|
+              t.string "name", limit: 250#{charset_and_collation}
+            end
         EOS
       )
 
@@ -700,8 +729,8 @@ RSpec.describe 'DeclareSchema Migration Generator' do
             add_index :adverts, [:type], name: :on_type
           EOS
           .and migrate_down(<<~EOS.strip)
-            remove_index :adverts, name: :on_type
-            remove_column :adverts, :type
+              remove_index :adverts, name: :on_type
+              remove_column :adverts, :type
           EOS
         )
       end
@@ -709,7 +738,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
       Advert.field_specs.delete(:type)
       nuke_model_class(SuperFancyAdvert)
       nuke_model_class(FancyAdvert)
-      Advert.index_definitions.delete_if { |spec| spec.fields==["type"] }
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["type"] }
 
       ## Coping with multiple changes
 
@@ -744,8 +773,8 @@ RSpec.describe 'DeclareSchema Migration Generator' do
           change_column :adverts, :name, :string, limit: 250, null: true, default: "No Name"#{charset_and_collation}
         EOS
         .and migrate_down(<<~EOS.strip)
-          change_column :adverts, :name, :string, limit: 250, null: true, default: "Untitled"#{charset_and_collation}
-          rename_column :adverts, :name, :title
+            change_column :adverts, :name, :string, limit: 250, null: true, default: "Untitled"#{charset_and_collation}
+            rename_column :adverts, :name, :title
         EOS
       )
 
@@ -855,21 +884,21 @@ RSpec.describe 'DeclareSchema Migration Generator' do
       it 'will genereate unique constraint names' do
         expect(Generators::DeclareSchema::Migration::Migrator.run).to(
           migrate_up(<<~EOS.strip)
-          create_table :categories, id: :bigint, options: "CHARACTER SET utf8mb4 COLLATE utf8mb4_bin" do |t|
-            t.string :name, limit: 250, null: true, charset: "utf8mb4", collation: "utf8mb4_bin"
-          end
-          create_table :advertisers, id: :bigint, options: "CHARACTER SET utf8mb4 COLLATE utf8mb4_bin" do |t|
-            t.string  :name, limit: 250, null: true, charset: "utf8mb4", collation: "utf8mb4_bin"
-            t.integer :category_id, limit: 8, null: false
-          end
-          create_table :affiliates, id: :bigint, options: "CHARACTER SET utf8mb4 COLLATE utf8mb4_bin" do |t|
-            t.string  :name, limit: 250, null: true, charset: "utf8mb4", collation: "utf8mb4_bin"
-            t.integer :category_id, limit: 8, null: false
-          end
-          add_index :advertisers, [:category_id], name: :index_advertisers_on_category_id
-          add_index :affiliates, [:category_id], name: :index_affiliates_on_category_id
-          add_foreign_key :advertisers, :categories, column: :category_id, name: :index_advertisers_on_category_id
-          add_foreign_key :affiliates, :categories, column: :category_id, name: :index_affiliates_on_category_id
+            create_table :categories, id: :bigint, options: "CHARACTER SET utf8mb4 COLLATE utf8mb4_bin" do |t|
+              t.string :name, limit: 250, null: true, charset: "utf8mb4", collation: "utf8mb4_bin"
+            end
+            create_table :advertisers, id: :bigint, options: "CHARACTER SET utf8mb4 COLLATE utf8mb4_bin" do |t|
+              t.string  :name, limit: 250, null: true, charset: "utf8mb4", collation: "utf8mb4_bin"
+              t.integer :category_id, limit: 8, null: false
+            end
+            create_table :affiliates, id: :bigint, options: "CHARACTER SET utf8mb4 COLLATE utf8mb4_bin" do |t|
+              t.string  :name, limit: 250, null: true, charset: "utf8mb4", collation: "utf8mb4_bin"
+              t.integer :category_id, limit: 8, null: false
+            end
+            add_index :advertisers, [:category_id], name: :index_advertisers_on_category_id
+            add_index :affiliates, [:category_id], name: :index_affiliates_on_category_id
+            add_foreign_key :advertisers, :categories, column: :category_id, name: :index_advertisers_on_category_id
+            add_foreign_key :affiliates, :categories, column: :category_id, name: :index_affiliates_on_category_id
         EOS
         )
         migrate

data/spec/lib/declare_schema/model/index_definition_spec.rb

@@ -36,26 +36,102 @@ RSpec.describe DeclareSchema::Model::IndexDefinition do
 
     describe 'instance methods' do
       let(:model) { model_class.new }
-      subject { declared_class.new(model_class) }
-
-      it 'has index_definitions' do
-        expect(model_class.index_definitions).to be_kind_of(Array)
-        expect(model_class.index_definitions.map(&:name)).to eq(['index_index_definition_test_models_on_name'])
-        expect([:name, :fields, :unique].map { |attr| model_class.index_definitions[0].send(attr)}).to eq(
-          ['index_index_definition_test_models_on_name', ['name'], false]
-        )
+      let(:fields) { ['last_name', 'first_name'] }
+      let(:options) { {} }
+      subject(:instance) { described_class.new(model_class, fields, **options) }
+
+      describe 'attr_readers' do
+        describe '#table' do
+          subject { instance.table }
+
+          it { is_expected.to eq(model_class.table_name) }
+
+          context 'with table_name option' do
+            let(:options) { { table_name: 'auth_users' } }
+
+            it { is_expected.to eq('auth_users') }
+          end
+        end
+
+        describe '#fields' do
+          subject { instance.fields }
+
+          it { is_expected.to eq(fields) }
+        end
+
+        describe '#explicit_name' do
+          subject { instance.explicit_name }
+
+          it { is_expected.to eq(nil) }
+
+          context 'with name option' do
+            let(:options) { { name: 'index_auth_users_on_last_name_and_first_name' } }
+
+            it { is_expected.to eq('index_auth_users_on_last_name_and_first_name') }
+          end
+        end
+
+        describe '#length' do
+          subject { instance.length }
+          let(:options) { { length: length } }
+
+          context 'with integer length' do
+            let(:length) { 2 }
+
+            it { is_expected.to eq(length) }
+          end
+
+          context 'with Hash length' do
+            let(:length) { { name: 2 } }
+
+            it { is_expected.to eq(length) }
+          end
+        end
+
+        describe '#options' do
+          subject { instance.options }
+          let(:options) { { name: 'my_index', unique: false, where: "(name like 'a%')", length: 10 } }
+
+          it { is_expected.to eq(options) }
+        end
+
+        describe '#with_name' do
+          subject { instance.with_name('new_name') }
+
+          it { is_expected.to be_kind_of(described_class) }
+          it { expect(instance.name).to eq('index_index_definition_test_models_on_last_name_and_first_name') }
+          it { expect(subject.name).to eq('new_name') }
+        end
       end
+    end
 
-      it 'has index_definitions_with_primary_key' do
-        expect(model_class.index_definitions_with_primary_key).to be_kind_of(Array)
-        result = model_class.index_definitions_with_primary_key.sort_by(&:name)
-        expect(result.map(&:name)).to eq(['PRIMARY', 'index_index_definition_test_models_on_name'])
-        expect([:name, :fields, :unique].map { |attr| result[0].send(attr)}).to eq(
-          ['PRIMARY', ['id'], true]
-        )
-        expect([:name, :fields, :unique].map { |attr| result[1].send(attr)}).to eq(
-          ['index_index_definition_test_models_on_name', ['name'], false]
-        )
+    describe 'class methods' do
+      let(:model) { model_class.new }
+
+      describe 'index_definitions' do
+        it do
+          expect(model_class.index_definitions.size).to eq(1)
+
+          expect(model_class.index_definitions[0].name).to eq('index_index_definition_test_models_on_name')
+          expect(model_class.index_definitions[0].fields).to eq(['name'])
+          expect(model_class.index_definitions[0].unique).to eq(false)
+        end
+      end
+
+      describe 'has index_definitions_with_primary_key' do
+        it do
+          expect(model_class.index_definitions_with_primary_key).to be_kind_of(Array)
+          result = model_class.index_definitions_with_primary_key.sort_by(&:name)
+          expect(result.size).to eq(2)
+
+          expect(result[0].name).to eq('PRIMARY')
+          expect(result[0].fields).to eq(['id'])
+          expect(result[0].unique).to eq(true)
+
+          expect(result[1].name).to eq('index_index_definition_test_models_on_name')
+          expect(result[1].fields).to eq(['name'])
+          expect(result[1].unique).to eq(false)
+        end
       end
     end
 
@@ -86,12 +162,12 @@ RSpec.describe DeclareSchema::Model::IndexDefinition do
         context 'with single-column PK' do
           it 'returns the indexes for the model' do
             expect(subject.size).to eq(2), subject.inspect
-            expect([:name, :columns, :unique].map { |attr| subject[0].send(attr) }).to eq(
-              ['index_definition_test_models_on_name', ['name'], true]
-            )
-            expect([:name, :columns, :unique].map { |attr| subject[1].send(attr) }).to eq(
-              ['PRIMARY', ['id'], true]
-            )
+            expect(subject[0].name).to eq('index_definition_test_models_on_name')
+            expect(subject[0].columns).to eq(['name'])
+            expect(subject[0].unique).to eq(true)
+            expect(subject[1].name).to eq('PRIMARY')
+            expect(subject[1].columns).to eq(['id'])
+            expect(subject[1].unique).to eq(true)
           end
         end
 
@@ -100,9 +176,9 @@ RSpec.describe DeclareSchema::Model::IndexDefinition do
 
           it 'returns the indexes for the model' do
             expect(subject.size).to eq(1), subject.inspect
-            expect([:name, :columns, :unique].map { |attr| subject[0].send(attr) }).to eq(
-              ['PRIMARY', ['fk1_id', 'fk2_id'], true]
-            )
+            expect(subject[0].name).to eq('PRIMARY')
+            expect(subject[0].columns).to eq(['fk1_id', 'fk2_id'])
+            expect(subject[0].unique).to eq(true)
           end
         end
       end

data/spec/lib/declare_schema/schema_change/index_add_spec.rb

@@ -30,7 +30,7 @@ RSpec.describe DeclareSchema::SchemaChange::IndexAdd do
       end
 
       context 'with where:' do
-        let(:where) { "'last_name like 'A%'"}
+        let(:where) { "'last_name like 'A%'" }
         subject { described_class.new(table_name, column_names, name: name, unique: unique, where: where) }
 
         it 'responds with command' do
@@ -45,6 +45,33 @@ RSpec.describe DeclareSchema::SchemaChange::IndexAdd do
           expect(subject.up).to eq("add_index :#{table_name}, #{column_names.map(&:to_sym).inspect}, name: #{name.to_sym.inspect}, unique: true\n")
         end
       end
+
+      context 'with length: nil' do
+        let(:length) { nil }
+        subject { described_class.new(table_name, column_names, name: name, unique: unique, length: length) }
+
+        it 'responds with command' do
+          expect(subject.up).to eq("add_index :#{table_name}, #{column_names.map(&:to_sym).inspect}, name: #{name.to_sym.inspect}\n")
+        end
+      end
+
+      context 'with length: 2' do
+        let(:length) { 2 }
+        subject { described_class.new(table_name, column_names, name: name, unique: unique, length: length) }
+
+        it 'responds with command' do
+          expect(subject.up).to eq("add_index :#{table_name}, #{column_names.map(&:to_sym).inspect}, name: #{name.to_sym.inspect}, length: #{length}\n")
+        end
+      end
+
+      context 'with length: hash' do
+        let(:length) { { last_name: 10, first_name: 1 } }
+        subject { described_class.new(table_name, column_names, name: name, unique: unique, length: length) }
+
+        it 'responds with command' do
+          expect(subject.up).to eq("add_index :#{table_name}, #{column_names.map(&:to_sym).inspect}, name: #{name.to_sym.inspect}, length: { last_name: 10, first_name: 1 }\n")
+        end
+      end
     end
 
     describe '#down' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: declare_schema
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0.colin.2
 platform: ruby
 authors:
 - Invoca Development adapted from hobo_fields by Tom Locke
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-12 00:00:00.000000000 Z
+date: 2024-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails