declare_schema 3.1.0.colin.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b65098860b02787bce136f3b694bcd294cdaaa6980716492bcf66b5ab9c4cc9
-  data.tar.gz: 9d8ff3e2e7c2cc06886f59b8052ab0f4b2d4bac88ea46ac4ada831000b6cb0a8
+  metadata.gz: 929f250672103aa42777cb918340e5281d100fdaf19cedb5f7aaa96504e66a8c
+  data.tar.gz: 377a3f2aaae4fa4b6294a4c4a9edd672a8626a505be6a07e06b953a28cb78ffc
 SHA512:
-  metadata.gz: 9e7456ba8c763846255997c5fb08a77cb094a199abea888f13c39a9a5dea8e099fe1e09f2a017931eb3b8f1c1e2e7c46b8752dda2510e7f2a892c3f0d2a29a43
-  data.tar.gz: 38909be09762f69b40d245385bccf004520142838a95cd27f2c75ef0f82c292a65f301dda444b05e6ce30d76406f712f59c6a9160f8fea9588c1791d3448a8d3
+  metadata.gz: 8d05a979184d7e93041a462b1269b7d71a6a675f37b8914e27728db0f2d28878d0436cc10eba4bd107f1cb57355c1321147659842367e9231ebb32eec5d14b79
+  data.tar.gz: 3c361cb45d57de4c4aac717155b354f34d0c654b4881c29742a9f611cf7ca8efd0c9297e70433dd7b2df4df70751bf3c1d0463824ccc8eb77f5f9a1d836e711d

data/.github/workflows/pipeline.yml

@@ -48,7 +48,7 @@ jobs:
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{matrix.ruby}}
-          bundler: latest
+          bundler: 2.5
           bundler-cache: true
       - name: Setup
         run: |

data/CHANGELOG.md

@@ -4,9 +4,11 @@ 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).
 
-## [3.1.0] - Unreleased
+## [4.0.0] - 2026-05-05
 ### Added
-- Add HABTM support for arbitrary primary key in the referenced table (rather than just :bigint). 
+- Generalized `belongs_to` foreign keys to always match the primary key they point at, including
+  in HABTM intersection tables. (Previously this was just a special case that matched up
+  :integer vs :bigint.)
 
 ### Removed
 - Drop support for Rails 6.x. Minimum supported Rails is now 7.0.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    declare_schema (3.1.0.colin.2)
+    declare_schema (4.0.0)
       rails (>= 7.0)
 
 GEM

data/lib/declare_schema/model/deferred_field_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module DeclareSchema
+  module Model
+    # A placeholder for a {FieldSpec} whose final shape can't be computed at field-
+    # declaration time. The only producer today is `belongs_to` between two
+    # declare_schema models: we cannot touch `reflection.klass` while declaring the
+    # FK without risking a model-load cycle, so we stash an eager default-typed
+    # FieldSpec along with a block that knows how to mirror the parent's PK once
+    # all models have been eager-loaded.
+    #
+    # The migrator calls {#resolve} on every value in `field_specs` at the start
+    # of migration generation (see `Migrator#generate`); for plain {FieldSpec}s
+    # `#resolve` is a no-op returning self, while for instances of this class it
+    # invokes the block (memoized) with the default spec and returns the produced
+    # {FieldSpec}.
+    class DeferredFieldSpec
+      # @param default_spec [FieldSpec] the eager placeholder spec
+      # @yieldparam default_spec [FieldSpec]
+      # @yieldreturn [FieldSpec] the resolved spec
+      def initialize(default_spec, &resolver)
+        resolver or raise ArgumentError, "DeferredFieldSpec requires a resolver block"
+        @default_spec = default_spec
+        @resolver = resolver
+      end
+
+      # Invoke the resolver block with the default spec and return its result.
+      # The migrator's `transform_values!(&:resolve)` swaps this DeferredFieldSpec
+      # out of `field_specs` for the produced FieldSpec, so resolve is called
+      # exactly once per instance in production -- no memoization needed.
+      #
+      # @return [FieldSpec]
+      def resolve
+        @resolver.call(@default_spec)
+      end
+    end
+  end
+end

data/lib/declare_schema/model/field_spec.rb

@@ -46,13 +46,12 @@ module DeclareSchema
         define_method(option) { @options[option] }
       end
 
-      def initialize(model, name, type, position: 0, resolver: nil, **options)
+      def initialize(model, name, type, position: 0, **options)
         @model = model
         @name = name.to_sym
         type.is_a?(Symbol) or raise ArgumentError, "type must be a Symbol; got #{type.inspect}"
         @type = TYPE_SYNONYMS[type] || type
         @position = position
-        @resolver = resolver
         @options = options.dup
 
         @options.has_key?(:null) or @options[:null] = ::DeclareSchema.default_null
@@ -121,15 +120,29 @@ module DeclareSchema
         @sql_options = @options.slice(*SQL_OPTIONS)
       end
 
-      # Returns the final FieldSpec, invoking the deferred-resolution callback if one
-      # was supplied. Specs without a `resolver:` simply return `self`. Result is
-      # memoized so repeated calls (e.g. across migration generation passes) are cheap.
+      # Duck-type counterpart to {DeferredFieldSpec#resolve}. A concrete FieldSpec is
+      # already its own resolved form, so this just returns self. Lets the migrator's
+      # `transform_values!(&:resolve)` loop dispatch uniformly across both classes.
+      #
+      # @return [FieldSpec] self
       def resolve
-        @resolved ||= @resolver ? @resolver.call(self) : self
+        self
       end
 
-      def foreign_key_field_spec(model, name, position:, null:)
-        self.class.new(model, name, @type, position:, **@options.merge(null.nil? ? {} : { null: }))
+      # Build a FieldSpec for a foreign key that mirrors this PK's type/limit/charset/etc.
+      # Child column_options (e.g. `default:` from `belongs_to`) win over the parent's
+      # @options when they specify the same key.
+      #
+      # @param model [Class] the child ActiveRecord class
+      # @param name [Symbol] the FK column name (e.g. :user_id)
+      # @param position [Integer] FieldSpec position in the field_specs hash
+      # @param null [Boolean, nil] :null setting from `belongs_to`; nil leaves @options[:null] alone
+      # @param column_options [Hash] additional FK-side overrides (e.g. :default)
+      # @return [FieldSpec]
+      def foreign_key_field_spec(model, name, position:, null:, **column_options)
+        options = @options.merge(column_options)
+        options[:null] = null unless null.nil?
+        self.class.new(model, name, @type, position:, **options)
       end
 
       # returns the attributes for schema migrations as a Hash

data/lib/declare_schema/model.rb

@@ -226,81 +226,98 @@ module DeclareSchema
         end
       end
 
-      # Returns a FieldSpec for the foreign key column of a belongs_to association.
-      # - For a polymorphic association, the FK uses `DeclareSchema.default_generated_primary_key_type`
-      #   (mirroring `config.generators.primary_key_type`, default :bigint), or :integer with the
-      #   existing column's limit if the column already exists in the database.
-      # - For a non-polymorphic association, the FK should mirror the primary key it points
-      #   at (same data type, same options like limit:, charset:, etc.). However we cannot
-      #   load the parent model right now (at `belongs_to` time) without risking dependency
-      #   cycles between models, so we install a `resolver:` callback. The migration
-      #   generator calls that resolver at generation time -- after all models are
-      #   eager-loaded -- and the resolver returns a fully-mirrored FieldSpec that the
-      #   generator swaps in for this default_spec.
+      # Build the FK column FieldSpec for a `belongs_to`.
+      #
+      # Polymorphic associations have no parent class to mirror, so we grandfather to
+      # the live FK column when present (see {#_field_spec_options_from_pk_column}) and
+      # fall back to {DeclareSchema.default_generated_primary_key_type} otherwise.
+      #
+      # Non-polymorphic associations mirror the parent's PK at migration-generation time
+      # via a deferred resolver block (see {#_resolve_belongs_to_foreign_key_field_spec}).
+      # The deferral avoids loading `reflection.klass` here, which can trigger
+      # dependency cycles between models.
+      #
+      # @param foreign_key_column_name [Symbol] e.g. :user_id
+      # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+      # @param column_options [Hash] :null and (optionally) :default from `belongs_to`
+      # @return [FieldSpec]
       def _infer_foreign_key_field_spec(foreign_key_column_name, reflection, column_options)
         if reflection.options[:polymorphic]
-          if (foreign_key_column = _column(foreign_key_column_name)) && foreign_key_column.type == :integer
-            # grandfather foreign key column to match what's in the database
-            column_options = column_options.merge(limit: foreign_key_column.limit)
-          end
-          FieldSpec.new(self, foreign_key_column_name, DeclareSchema.default_generated_primary_key_type, position: field_specs.size, **column_options)
+          # Mirror both type AND :limit from the live column -- mirroring only :limit
+          # doesn't help when the gem default is :bigint, since FieldSpec normalizes
+          # :bigint to (:integer, limit: 8) and discards the live :limit, generating a
+          # phantom int(4) -> bigint(8) change.
+          type, live_options = _field_spec_options_from_pk_column(_column(foreign_key_column_name))
+          type ||= DeclareSchema.default_generated_primary_key_type
+          FieldSpec.new(self, foreign_key_column_name, type,
+                        position: field_specs.size, **column_options.merge(live_options || {}))
         else
-          # Capture only what we need from `reflection` (no `reflection.klass` here -- that
-          # would force the parent model to load, which is exactly the cycle we are avoiding).
-          # `reflection.klass` is resolved lazily inside the block below.
-          resolver = ->(default_spec) do
-            _resolve_belongs_to_foreign_key_field_spec(reflection, default_spec)
+          default_spec = FieldSpec.new(self, foreign_key_column_name, DeclareSchema.default_generated_primary_key_type,
+                                       position: field_specs.size, **column_options)
+          DeferredFieldSpec.new(default_spec) do |spec|
+            _resolve_belongs_to_foreign_key_field_spec(reflection, spec)
           end
-          FieldSpec.new(self, foreign_key_column_name, DeclareSchema.default_generated_primary_key_type,
-                        position: field_specs.size, resolver:, **column_options)
         end
       end
 
-      # Called at migration generation time to mirror the parent model's primary key.
-      # Always returns a FieldSpec: the default_spec unchanged when the parent class is not
-      # a declare_schema model (we can't ask for its PK spec, so the configured default PK
-      # type is the best we can offer without inspecting the DB), otherwise a fully mirrored
-      # FieldSpec.
+      # Resolve the FK FieldSpec by mirroring the parent's PK at migration-generation time.
+      # Falls back to `default_spec` when there's nothing to mirror (greenfield
+      # non-declare_schema parent whose table can't be inspected yet).
       #
-      # Reconciliation with the live DB: if the parent's PK column already exists in the
-      # database with the same Rails type but a different :limit (e.g. a legacy table where
-      # `id` is INT(4) but the model now declares the default :bigint), prefer the live
-      # column's :limit so the FK matches what's actually on disk. This preserves the
-      # behavior of the old DB-column lookup (formerly `fk_field_options`) without
-      # overriding intentional type changes.
+      # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+      # @param default_spec [FieldSpec] the placeholder built at `belongs_to` time
+      # @return [FieldSpec]
       def _resolve_belongs_to_foreign_key_field_spec(reflection, default_spec)
         klass = reflection.klass or
           raise "Couldn't find belongs_to klass for #{reflection.name} on #{name} in #{reflection.inspect}"
 
-        if klass.respond_to?(:_primary_key_field_spec)
-          _mirror_parent_primary_key(klass, default_spec)
+        if (parent_pk_spec = _parent_pk_field_spec(klass))
+          # Forward child column options that should survive PK mirroring (currently just
+          # :default); otherwise they are silently dropped and a phantom change_column is
+          # emitted on every run.
+          child_options = default_spec.options.slice(:default)
+          fk_spec = parent_pk_spec.foreign_key_field_spec(
+                      default_spec.model, default_spec.name,
+                      position: default_spec.position, null: default_spec.null,
+                      **child_options
+                    )
+          _reconcile_fk_with_live_pk(klass, fk_spec)
         else
           default_spec
         end
       end
 
-      # Build a FieldSpec for the FK by mirroring the parent's declared primary key,
-      # then reconciling against the live DB column when it differs only in :limit
-      # (see _resolve_belongs_to_foreign_key_field_spec for the full rationale).
-      def _mirror_parent_primary_key(klass, default_spec)
-        spec = klass._primary_key_field_spec.foreign_key_field_spec(
-          default_spec.model, default_spec.name,
-          position: default_spec.position, null: default_spec.null
-        )
+      # The PK FieldSpec to mirror into a FK: the parent's declared spec when available
+      # (declare_schema parent), otherwise one synthesized from the parent's live PK
+      # column.
+      #
+      # @param klass [Class] the parent ActiveRecord class
+      # @return [FieldSpec, nil] nil when the parent is not a declare_schema model and
+      #   its table can't be inspected (e.g. greenfield)
+      def _parent_pk_field_spec(klass)
+        if klass.respond_to?(:_primary_key_field_spec)
+          klass._primary_key_field_spec
+        else
+          type, options = _field_spec_options_from_pk_column(_pk_column_for(klass))
+          FieldSpec.new(klass, klass.primary_key, type, **options) if type
+        end
+      end
 
-        # Look up the parent's live PK column directly (not via _column, whose
-        # @table_exists memoization can pin to a stale value when the parent table
-        # is created after the model class is first defined). The rescue covers
-        # the table-doesn't-exist-yet case (greenfield migration).
-        live_pk_column = klass.columns_hash[klass._declared_primary_key.to_s] rescue nil
-        if live_pk_column && live_pk_column.type == spec.type && live_pk_column.limit && live_pk_column.limit != spec.limit
-          FieldSpec.new(
-            spec.model, spec.name, spec.type,
-            position: spec.position,
-            **spec.options.merge(limit: live_pk_column.limit)
-          )
+      # Preserve a legacy live PK :limit when the model has drifted to a different :limit
+      # (e.g. parent declares :bigint while live `id` is still INT(4)) -- without this the
+      # migrator would emit a phantom widening on every run.
+      #
+      # @param klass [Class] the parent ActiveRecord class
+      # @param fk_spec [FieldSpec] the proposed FK spec built from the parent's PK
+      # @return [FieldSpec] fk_spec with :limit overridden when reconciliation applies,
+      #   otherwise fk_spec unchanged
+      def _reconcile_fk_with_live_pk(klass, fk_spec)
+        live_pk = _pk_column_for(klass)
+        if live_pk && live_pk.type == fk_spec.type && live_pk.limit && live_pk.limit != fk_spec.limit
+          FieldSpec.new(fk_spec.model, fk_spec.name, fk_spec.type,
+                        position: fk_spec.position, **fk_spec.options.merge(limit: live_pk.limit))
         else
-          spec
+          fk_spec
         end
       end
 
@@ -329,22 +346,72 @@ module DeclareSchema
           raise "Declared primary key #{declared_primary_key.inspect} not found in field_specs or _table_options #{_table_options.inspect} for #{name}"
       end
 
+      # Build the PK FieldSpec when no explicit `declare_schema id: ...` is given.
+      # Prefers the live PK column (so legacy `int(4)` PKs predating Rails's `:bigint`
+      # default aren't forced to bigint via FK mirroring) and falls back to the gem
+      # default for greenfield tables.
+      #
+      # _table_options is nil on STI subclasses that never call `declare_schema`
+      # themselves: they inherit `field_specs` via `inheriting_cattr_reader`, but
+      # `@_table_options` is a plain class-instance variable on each class, so the
+      # subclass's reader returns nil. We treat that the same as an empty options hash.
+      #
+      # @param declared_primary_key [String, Symbol] PK column name (typically 'id')
+      # @return [FieldSpec]
       def _primary_key_field_spec_from_table_options(declared_primary_key)
-        # _table_options is nil on STI subclasses that never call `declare_schema` themselves:
-        # they inherit `field_specs` etc. via `inheriting_cattr_reader`, but `@_table_options`
-        # is a plain class-instance variable on each class, so the subclass's reader returns
-        # nil. Treat that the same as an empty options hash and fall through to
-        # `default_generated_primary_key_type` below.
         type, options = _parse_pk_table_options(_table_options&.[](declared_primary_key.to_sym))
-        type ||= DeclareSchema.default_generated_primary_key_type
+        if type.nil?
+          type, options = _field_spec_options_from_pk_column(_pk_column_for(self)) ||
+                          [DeclareSchema.default_generated_primary_key_type, {}]
+        end
         FieldSpec.new(self, declared_primary_key, type, **options)
       end
 
       private
 
+      # @param klass [Class] any ActiveRecord class
+      # @return [ActiveRecord::ConnectionAdapters::Column, nil] the live PK column, or
+      #   nil when the table doesn't exist yet or can't otherwise be inspected, or
+      #   when the model has a compound primary key (Array PK name misses
+      #   `columns_hash`). Reads via `columns_hash` directly (not `_column`, whose
+      #   `@table_exists` memoization can pin a stale answer) so a parent table
+      #   being created in this same migration run is honored.
+      def _pk_column_for(klass)
+        if (pk_name = klass.try(:_declared_primary_key) || klass.primary_key)
+          klass.columns_hash[pk_name]
+        end
+      rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError
+        nil
+      end
+
+      # Translate a live PK column into FieldSpec arguments. AR returns :integer for both
+      # INT and BIGINT in MySQL; we distinguish by `limit` so callers can mirror the
+      # legacy width rather than the gem's :bigint default.
+      #
+      # @param column [ActiveRecord::ConnectionAdapters::Column, nil]
+      # @return [Array(Symbol, Hash), nil] [type, options] for FieldSpec.new, or nil if
+      #   the column type doesn't round-trip cleanly
+      def _field_spec_options_from_pk_column(column)
+        if column&.type == :integer
+          if column.limit == 8
+            [:bigint, {}]
+          else
+            [:integer, { limit: column.limit || 4 }]
+          end
+        end
+      end
+
       # `declare_schema id: ...` accepts either a Hash (`id: { type: :integer, limit: 4 }`)
-      # or a bare type Symbol (`id: :integer`). Returns [type, options_hash], with type == nil
-      # when value is neither (caller falls back to a default).
+      # or a bare type Symbol (`id: :integer`). Normalizes both shapes -- plus the
+      # absent / unrecognized case -- into a uniform `[type, options]` pair so the
+      # caller (`_primary_key_field_spec_from_table_options`) can dispatch on
+      # `type.nil?` to decide whether to fall back to live-PK inspection or the
+      # gem default.
+      #
+      # @param value [Hash, Symbol, nil] the per-PK entry from `_table_options`
+      # @return [Array(Symbol, Hash), Array(nil, Hash)] `[type, options]` where
+      #   `type` is nil when `value` is neither a Hash nor a Symbol (signal to
+      #   caller to fall back). `options` always excludes `:type`.
       def _parse_pk_table_options(value)
         case value
         when Hash   then [value[:type], value.except(:type)]

data/lib/declare_schema/version.rb

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

data/lib/declare_schema.rb

@@ -179,6 +179,7 @@ end
 require 'declare_schema/extensions/active_record/fields_declaration'
 require 'declare_schema/model'
 require 'declare_schema/model/field_spec'
+require 'declare_schema/model/deferred_field_spec'
 require 'declare_schema/model/index_definition'
 require 'declare_schema/model/foreign_key_definition'
 require 'declare_schema/model/table_options_definition'

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

@@ -80,7 +80,16 @@ module Generators
           self.class.native_types
         end
 
-        # return habtm reflections keyed by join table name (so that habtm from each side has just one entry)
+        # Collect every HABTM reflection across the application, keyed by its join
+        # table name. Each join table is shared by both sides of a HABTM
+        # association, so iterating all descendants would yield two reflections
+        # per join table (one from each parent model). Keying by `join_table` and
+        # using `||=` keeps the first occurrence and silently drops the duplicate
+        # from the other side, so the migrator emits exactly one shim per join
+        # table.
+        #
+        # @return [Hash{String => ActiveRecord::Reflection::HasAndBelongsToManyReflection}]
+        #   join table name -> the (first-seen) HABTM reflection that owns it
         def habtm_tables
           ActiveRecord::Base.send(:descendants).each_with_object({}) do |c, result|
             c.reflect_on_all_associations(:has_and_belongs_to_many).each do |a|

data/spec/lib/declare_schema/deferred_field_spec_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+RSpec.describe DeclareSchema::Model::DeferredFieldSpec do
+  include_context 'prepare test app'
+
+  let(:model)         { double('model', _table_options: {}, _declared_primary_key: 'id') }
+  let(:default_spec)  { DeclareSchema::Model::FieldSpec.new(model, :advertiser_id, :integer, limit: 8, null: false, position: 1) }
+  let(:mirrored_spec) { DeclareSchema::Model::FieldSpec.new(model, :advertiser_id, :string,  limit: 36, null: false, position: 1) }
+
+  describe '#initialize' do
+    it 'requires a resolver block' do
+      expect { described_class.new(default_spec) }.to raise_error(ArgumentError, /resolver block/)
+    end
+  end
+
+  describe '#resolve' do
+    it 'invokes the resolver with the default spec and returns its result' do
+      captured = nil
+      deferred = described_class.new(default_spec) do |spec|
+        captured = spec
+        mirrored_spec
+      end
+
+      expect(deferred.resolve).to equal(mirrored_spec)
+      expect(captured).to equal(default_spec)
+    end
+  end
+end

data/spec/lib/declare_schema/field_spec_spec.rb

@@ -25,38 +25,6 @@ RSpec.describe DeclareSchema::Model::FieldSpec do
     end
   end
 
-  describe '#resolve' do
-    let(:default_spec) { described_class.new(model, :advertiser_id, :integer, limit: 8, null: false, position: 1) }
-    let(:mirrored_spec) { described_class.new(model, :advertiser_id, :string, limit: 36, null: false, position: 1) }
-
-    context 'when no resolver was supplied' do
-      it 'returns self' do
-        expect(default_spec.resolve).to equal(default_spec)
-      end
-    end
-
-    context 'when a resolver was supplied' do
-      it 'invokes the resolver with self and returns its result' do
-        captured = nil
-        spec_under_test = described_class.new(model, :advertiser_id, :integer, limit: 8, null: false, position: 1,
-                                              resolver: ->(spec) { captured = spec; mirrored_spec })
-
-        expect(spec_under_test.resolve).to equal(mirrored_spec)
-        expect(captured).to equal(spec_under_test)
-      end
-
-      it 'memoizes the resolver result' do
-        call_count = 0
-        spec_under_test = described_class.new(model, :advertiser_id, :integer, limit: 8, null: false, position: 1,
-                                              resolver: ->(_spec) { call_count += 1; mirrored_spec })
-
-        3.times { spec_under_test.resolve }
-
-        expect(call_count).to eq(1)
-      end
-    end
-  end
-
   describe '#schema_attributes' do
     describe 'integer 4' do
       subject { described_class.new(model, :price, :integer, limit: 4, null: false, position: 0) }

data/spec/lib/declare_schema/migration_generator_spec.rb

@@ -996,6 +996,8 @@ RSpec.describe 'DeclareSchema Migration Generator' do
         nuke_model_class(Tag)                if defined?(Tag)
         nuke_model_class(Product)            if defined?(Product)
         nuke_model_class(ProductsTagsClass)  if defined?(ProductsTagsClass)
+        nuke_model_class(LegacyChild)        if defined?(LegacyChild)
+        nuke_model_class(LegacyParent)       if defined?(LegacyParent)
       end
 
       it 'belongs_to defers parent class lookup to migration time (no dependency cycle)' do
@@ -1100,6 +1102,124 @@ RSpec.describe 'DeclareSchema Migration Generator' do
         end
       end
 
+      context 'when a parent has no explicit PK declaration but the live PK column is int(4)' do
+        # Legacy schemas where every PK predates the gem's `:bigint` default. Without
+        # this behavior, declare_schema would force every belongs_to FK to bigint(8)
+        # while the parent PK stays int(4) -- which MySQL refuses with
+        # `Referencing column ... and referenced column ... in foreign key
+        # constraint ... are incompatible`.
+        before do
+          conn = ActiveRecord::Base.connection
+          conn.create_table(:legacy_parents, id: { type: :integer, limit: 4 }) do |t|
+            t.string :name, limit: 100, null: false
+          end
+          conn.schema_cache.clear!
+
+          class LegacyParent < ActiveRecord::Base # rubocop:disable Lint/ConstantDefinitionInBlock
+            declare_schema do
+              string :name, limit: 100, null: false
+            end
+          end
+
+          class LegacyChild < ActiveRecord::Base # rubocop:disable Lint/ConstantDefinitionInBlock
+            declare_schema do
+              integer :amount, null: false
+            end
+            belongs_to :legacy_parent
+          end
+        end
+
+        let(:up) { Generators::DeclareSchema::Migration::Migrator.run.first }
+
+        it 'mirrors the live int(4) PK in the FK rather than the gem default :bigint' do
+          expect(up).to match(/t\.integer\s+:legacy_parent_id, limit: 4, null: false/)
+          expect(up).not_to match(/:legacy_parent_id[^\n]*limit: 8/)
+        end
+      end
+
+      context 'when belongs_to declares a column option such as default:' do
+        # Regression: the resolver-built FK spec must preserve column options the child
+        # passed to belongs_to (default:, etc.). Forgetting to merge them silently drops
+        # them and generates a phantom change_column on every run.
+        before do
+          class DimParent < ActiveRecord::Base # rubocop:disable Lint/ConstantDefinitionInBlock
+            declare_schema do
+              string :name, limit: 100, null: false
+            end
+          end
+
+          class DimChild < ActiveRecord::Base # rubocop:disable Lint/ConstantDefinitionInBlock
+            declare_schema do
+              integer :amount, null: false
+            end
+            belongs_to :dim_parent, default: 1
+          end
+        end
+
+        let(:up) { Generators::DeclareSchema::Migration::Migrator.run.first }
+
+        it 'preserves the default: on the FK FieldSpec' do
+          expect(up).to match(/:dim_parent_id[^\n]*default: 1/)
+        end
+      end
+
+      context 'when a polymorphic FK column already exists as int(4)' do
+        # Polymorphic belongs_to has no parent klass to mirror; the gem grandfathers the
+        # live FK column. Without the type-too fix, FieldSpec forces :bigint -> limit: 8
+        # and a phantom int(4) -> bigint(8) change_column gets generated.
+        before do
+          conn = ActiveRecord::Base.connection
+          conn.create_table(:legacy_owners, id: { type: :integer, limit: 4 }) do |t|
+            t.integer :owner_id, limit: 4, null: false
+            t.string  :owner_type, limit: 100, null: false
+          end
+          conn.schema_cache.clear!
+
+          class LegacyOwner < ActiveRecord::Base # rubocop:disable Lint/ConstantDefinitionInBlock
+            declare_schema do
+              # owner_id/owner_type already exist in the DB at int(4); declare_schema should mirror them
+            end
+            belongs_to :owner, polymorphic: true
+          end
+        end
+
+        let(:up) { Generators::DeclareSchema::Migration::Migrator.run.first }
+
+        it 'mirrors the live int(4) FK rather than forcing bigint(8)' do
+          expect(up).not_to match(/:owner_id[^\n]*limit: 8/)
+        end
+      end
+
+      context 'when the parent class is not a declare_schema model' do
+        # Mirrors the prior `int(4)` case but with a plain ActiveRecord parent that has
+        # never opted into declare_schema. We still need to mirror its live PK column so
+        # the FK doesn't drift to :bigint while the parent stays int(4).
+        before do
+          conn = ActiveRecord::Base.connection
+          conn.create_table(:plain_parents, id: { type: :integer, limit: 4 }) do |t|
+            t.string :name, limit: 100, null: false
+          end
+          conn.schema_cache.clear!
+
+          class PlainParent < ActiveRecord::Base # rubocop:disable Lint/ConstantDefinitionInBlock
+          end
+
+          class PlainChild < ActiveRecord::Base # rubocop:disable Lint/ConstantDefinitionInBlock
+            declare_schema do
+              integer :amount, null: false
+            end
+            belongs_to :plain_parent
+          end
+        end
+
+        let(:up) { Generators::DeclareSchema::Migration::Migrator.run.first }
+
+        it 'mirrors the parent live int(4) PK in the FK rather than the gem default :bigint' do
+          expect(up).to match(/t\.integer\s+:plain_parent_id, limit: 4, null: false/)
+          expect(up).not_to match(/:plain_parent_id[^\n]*limit: 8/)
+        end
+      end
+
       it 'HABTM mirrors both parents primary key types (different non-default types)' do
         class Product < ActiveRecord::Base # rubocop:disable Lint/ConstantDefinitionInBlock
           declare_schema id: { type: :string, limit: 36 } do
@@ -1395,7 +1515,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
                 belongs_to :ad_category, optional: true, null: false
               end
               expect(AdvertBelongsTo.reflections['ad_category'].options).to eq(optional_true)
-              expect(AdvertBelongsTo.field_specs['ad_category_id'].options&.[](:null)).to eq(false)
+              expect(AdvertBelongsTo.field_specs['ad_category_id'].resolve.options[:null]).to eq(false)
             end
 
             it 'passes through optional: false, null: true' do
@@ -1406,7 +1526,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
                 belongs_to :ad_category, optional: false, null: true
               end
               expect(AdvertBelongsTo.reflections['ad_category'].options).to eq(optional_false)
-              expect(AdvertBelongsTo.field_specs['ad_category_id'].options&.[](:null)).to eq(true)
+              expect(AdvertBelongsTo.field_specs['ad_category_id'].resolve.options[:null]).to eq(true)
             end
           end
 
@@ -1420,7 +1540,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
                   end
                 EOS
                 expect(AdvertBelongsTo.reflections['ad_category'].options).to eq(optional_flag[nullable])
-                expect(AdvertBelongsTo.field_specs['ad_category_id'].options&.[](:null)).to eq(nullable)
+                expect(AdvertBelongsTo.field_specs['ad_category_id'].resolve.options[:null]).to eq(nullable)
               end
 
               it 'infers null: from optional:' do
@@ -1431,7 +1551,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
                   end
                 EOS
                 expect(AdvertBelongsTo.reflections['ad_category'].options).to eq(optional_flag[nullable])
-                expect(AdvertBelongsTo.field_specs['ad_category_id'].options&.[](:null)).to eq(nullable)
+                expect(AdvertBelongsTo.field_specs['ad_category_id'].resolve.options[:null]).to eq(nullable)
               end
             end
           end

data/spec/lib/generators/declare_schema/migration/migrator_default_pk_type_spec.rb

@@ -12,11 +12,11 @@ RSpec.describe 'DeclareSchema.default_generated_primary_key_type integration wit
   include_context 'prepare test app'
 
   before do
-    if current_adapter == 'mysql2'
-      ActiveRecord::Base.connection.execute("CREATE TABLE foos (id int PRIMARY KEY, name varchar(250))")
-    else
-      ActiveRecord::Base.connection.execute("CREATE TABLE foos (id integer PRIMARY KEY AUTOINCREMENT NOT NULL, name varchar(250))")
-    end
+    # Cross-adapter DDL: `integer PRIMARY KEY NOT NULL` works on sqlite, mysql, and
+    # postgres. AUTOINCREMENT (sqlite) / AUTO_INCREMENT (mysql) / SERIAL (postgres)
+    # would all be valid, but the migrator inspects type/null, not auto-increment
+    # metadata, so we can skip the auto-increment dance entirely.
+    ActiveRecord::Base.connection.execute("CREATE TABLE foos (id integer PRIMARY KEY NOT NULL, name varchar(250))")
     ActiveRecord::Base.connection.schema_cache.clear!
 
     allow_any_instance_of(DeclareSchema::Support::ThorShell)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: declare_schema
 version: !ruby/object:Gem::Version
-  version: 3.1.0.colin.2
+  version: 4.0.0
 platform: ruby
 authors:
 - Invoca Development adapted from hobo_fields by Tom Locke
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-03 00:00:00.000000000 Z
+date: 2026-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -68,6 +68,7 @@ files:
 - lib/declare_schema/extensions/module.rb
 - lib/declare_schema/model.rb
 - lib/declare_schema/model/column.rb
+- lib/declare_schema/model/deferred_field_spec.rb
 - lib/declare_schema/model/field_spec.rb
 - lib/declare_schema/model/foreign_key_definition.rb
 - lib/declare_schema/model/habtm_model_shim.rb
@@ -107,6 +108,7 @@ files:
 - spec/fixtures/migrations/sqlite3/will_generate_unique_constraint_names_rails_6.txt
 - spec/fixtures/migrations/sqlite3/will_generate_unique_constraint_names_rails_7.txt
 - spec/lib/declare_schema/api_spec.rb
+- spec/lib/declare_schema/deferred_field_spec_spec.rb
 - spec/lib/declare_schema/field_spec_spec.rb
 - spec/lib/declare_schema/generator_spec.rb
 - spec/lib/declare_schema/interactive_primary_key_spec.rb