declare_schema 0.8.0.pre.6 → 0.10.1

data/lib/generators/declare_schema/support/model.rb

@@ -69,11 +69,11 @@ module DeclareSchema
             def declare_model_fields_and_associations
               buffer = ::DeclareSchema::Support::IndentedBuffer.new(indent: 2)
               buffer.newline!
-              buffer << 'fields do'
+              buffer << 'declare_schema do'
               buffer.indent! do
                 field_attributes.each do |attribute|
-                  decl = "%-#{max_attribute_length}s" % attribute.name + ' ' +
-                    attribute.type.to_sym.inspect +
+                  decl = "%-#{max_attribute_length}s" % attribute.type + ' ' +
+                    attribute.name.to_sym.inspect +
                     case attribute.type.to_s
                     when 'string'
                       ', limit: 255'
@@ -113,7 +113,7 @@ module DeclareSchema
             end
 
             def max_attribute_length
-              attributes.map { |attribute| attribute.name.length }.max
+              attributes.map { |attribute| attribute.type.length }.max
             end
 
             def field_attributes

data/spec/lib/declare_schema/api_spec.rb

@@ -20,9 +20,9 @@ RSpec.describe 'DeclareSchema API' do
       expect_model_definition_to_eq('advert', <<~EOS)
         class Advert < #{active_record_base_class}
 
-          fields do
-            title :string, limit: 255
-            body  :text
+          declare_schema do
+            string :title, limit: 255
+            text   :body
           end
 
         end
@@ -91,8 +91,8 @@ RSpec.describe 'DeclareSchema API' do
       class AdvertWithRequiredTitle < ActiveRecord::Base
         self.table_name = 'adverts'
 
-        fields do
-          title :string, :required, limit: 255
+        declare_schema do
+          string :title, :required, limit: 255
         end
       end
 
@@ -110,8 +110,8 @@ RSpec.describe 'DeclareSchema API' do
       class AdvertWithUniqueTitle < ActiveRecord::Base
         self.table_name = 'adverts'
 
-        fields do
-          title :string, :unique, limit: 255
+        declare_schema do
+          string :title, :unique, limit: 255
         end
       end
 

data/spec/lib/declare_schema/field_declaration_dsl_spec.rb

@@ -3,29 +3,55 @@
 require_relative '../../../lib/declare_schema/field_declaration_dsl'
 
 RSpec.describe DeclareSchema::FieldDeclarationDsl do
-  before do
-    load File.expand_path('prepare_testapp.rb', __dir__)
+  let(:model) { TestModel.new }
+  subject { declared_class.new(model) }
 
-    class TestModel < ActiveRecord::Base
-      fields do
-        name :string, limit: 127
+  context 'Using fields' do
+    before do
+      load File.expand_path('prepare_testapp.rb', __dir__)
 
-        timestamps
+      class TestModel < ActiveRecord::Base
+        fields do
+          name :string, limit: 127
+
+          timestamps
+        end
       end
     end
-  end
 
-  let(:model) { TestModel.new }
-  subject { declared_class.new(model) }
+    it 'has fields' do
+      expect(TestModel.field_specs).to be_kind_of(Hash)
+      expect(TestModel.field_specs.keys).to eq(['name', 'created_at', 'updated_at'])
+      expect(TestModel.field_specs.values.map(&:type)).to eq([:string, :datetime, :datetime])
+    end
 
-  it 'has fields' do
-    expect(TestModel.field_specs).to be_kind_of(Hash)
-    expect(TestModel.field_specs.keys).to eq(['name', 'created_at', 'updated_at'])
-    expect(TestModel.field_specs.values.map(&:type)).to eq([:string, :datetime, :datetime])
+    it 'stores limits' do
+      expect(TestModel.field_specs['name'].limit).to eq(127), TestModel.field_specs['name'].inspect
+    end
   end
 
-  it 'stores limits' do
-    expect(TestModel.field_specs['name'].limit).to eq(127), TestModel.field_specs['name'].inspect
+  context 'Using declare_schema' do
+    before do
+      load File.expand_path('prepare_testapp.rb', __dir__)
+
+      class TestModel < ActiveRecord::Base
+        declare_schema do
+          string :name, limit: 127
+
+          timestamps
+        end
+      end
+    end
+
+    it 'has fields' do
+      expect(TestModel.field_specs).to be_kind_of(Hash)
+      expect(TestModel.field_specs.keys).to eq(['name', 'created_at', 'updated_at'])
+      expect(TestModel.field_specs.values.map(&:type)).to eq([:string, :datetime, :datetime])
+    end
+
+    it 'stores limits' do
+      expect(TestModel.field_specs['name'].limit).to eq(127), TestModel.field_specs['name'].inspect
+    end
   end
 
   # TODO: fill out remaining tests

data/spec/lib/declare_schema/field_spec_spec.rb

@@ -6,7 +6,7 @@ rescue LoadError
 end
 
 RSpec.describe DeclareSchema::Model::FieldSpec do
-  let(:model) { double('model', table_options: {}, defined_primary_key: 'id') }
+  let(:model) { double('model', table_options: {}, _defined_primary_key: 'id') }
   let(:col_spec) { double('col_spec', type: :string) }
 
   before do
@@ -61,6 +61,15 @@ RSpec.describe DeclareSchema::Model::FieldSpec do
           expect(subject.schema_attributes(col_spec)).to eq(type: :string, limit: 100, null: true)
         end
       end
+
+      it 'raises error when default_string_limit option is nil when not explicitly set in field spec' do
+        if defined?(Mysql2)
+          expect(::DeclareSchema).to receive(:default_string_limit) { nil }
+          expect do
+            described_class.new(model, :title, :string, null: true, charset: 'utf8mb4', position: 0)
+          end.to raise_error(/limit: must be provided for :string field/)
+        end
+      end
     end
 
     describe 'text' do
@@ -83,12 +92,35 @@ RSpec.describe DeclareSchema::Model::FieldSpec do
           expect(subject.schema_attributes(col_spec)).to eq(type: :text, null: true, default: 'none')
         end
       end
+
+      describe 'limit' do
+        it 'uses default_text_limit option when not explicitly set in field spec' do
+          allow(::DeclareSchema).to receive(:default_text_limit) { 100 }
+          subject = described_class.new(model, :title, :text, null: true, charset: 'utf8mb4', position: 2)
+          if defined?(Mysql2)
+            expect(subject.schema_attributes(col_spec)).to eq(type: :text, limit: 255, null: true, charset: 'utf8mb4', collation: 'utf8mb4_bin')
+          else
+            expect(subject.schema_attributes(col_spec)).to eq(type: :text, null: true)
+          end
+        end
+
+        it 'raises error when default_text_limit option is nil when not explicitly set in field spec' do
+          if defined?(Mysql2)
+            expect(::DeclareSchema).to receive(:default_text_limit) { nil }
+            expect do
+              described_class.new(model, :title, :text, null: true, charset: 'utf8mb4', position: 2)
+            end.to raise_error(/limit: must be provided for :text field/)
+          end
+        end
+      end
     end
 
-    describe 'varbinary' do # TODO: :varbinary is an Invoca addition to Rails; make it a configurable option
-      it 'is supported' do
-        subject = described_class.new(model, :binary_dump, :varbinary, limit: 200, null: false, position: 2)
-        expect(subject.schema_attributes(col_spec)).to eq(type: :varbinary, limit: 200, null: false)
+    if defined?(Mysql2)
+      describe 'varbinary' do # TODO: :varbinary is an Invoca addition to Rails; make it a configurable option
+        it 'is supported' do
+          subject = described_class.new(model, :binary_dump, :varbinary, limit: 200, null: false, position: 2)
+          expect(subject.schema_attributes(col_spec)).to eq(type: :varbinary, limit: 200, null: false)
+        end
       end
     end
 
@@ -109,7 +141,7 @@ RSpec.describe DeclareSchema::Model::FieldSpec do
       end
     end
 
-    [:integer, :bigint, :string, :text, :binary, :varbinary, :datetime, :date, :time].each do |t|
+    [:integer, :bigint, :string, :text, :binary, :datetime, :date, :time, (:varbinary if defined?(Mysql2))].compact.each do |t|
       describe t.to_s do
         let(:extra) { t == :string ? { limit: 100 } : {} }
 
@@ -182,5 +214,17 @@ RSpec.describe DeclareSchema::Model::FieldSpec do
     it 'excludes non-sql options' do
       expect(subject.sql_options).to eq(limit: 4, null: true, default: 0)
     end
+
+    describe 'null' do
+      subject { described_class.new(model, :price, :integer, limit: 4, default: 0, position: 2, encrypt_using: ->(field) { field }) }
+      it 'uses default_null option when not explicitly set in field spec' do
+        expect(subject.sql_options).to eq(limit: 4, null: false, default: 0)
+      end
+
+      it 'raises error if default_null is set to nil when not explicitly set in field spec' do
+        expect(::DeclareSchema).to receive(:default_null) { nil }
+        expect { subject.sql_options }.to raise_error(/null: must be provided for field/)
+      end
+    end
   end
 end

data/spec/lib/declare_schema/generator_spec.rb

@@ -11,9 +11,9 @@ RSpec.describe 'DeclareSchema Migration Generator' do
     expect_model_definition_to_eq('alpha/beta', <<~EOS)
       class Alpha::Beta < #{active_record_base_class}
 
-        fields do
-          one :string, limit: 255
-          two :integer
+        declare_schema do
+          string  :one, limit: 255
+          integer :two
         end
 
       end

data/spec/lib/declare_schema/interactive_primary_key_spec.rb

@@ -11,49 +11,139 @@ RSpec.describe 'DeclareSchema Migration Generator interactive primary key' do
     load File.expand_path('prepare_testapp.rb', __dir__)
   end
 
-  it "allows alternate primary keys" do
-    class Foo < ActiveRecord::Base
-      fields do
+  context 'Using fields' do
+    it "allows alternate primary keys" do
+      class Foo < ActiveRecord::Base
+        fields do
+        end
+        self.primary_key = "foo_id"
       end
-      self.primary_key = "foo_id"
-    end
 
-    generate_migrations '-n', '-m'
-    expect(Foo.primary_key).to eq('foo_id')
+      generate_migrations '-n', '-m'
+      expect(Foo._defined_primary_key).to eq('foo_id')
 
-    ### migrate from
-    # rename from custom primary_key
-    class Foo < ActiveRecord::Base
-      fields do
+      ### migrate from
+      # rename from custom primary_key
+      class Foo < ActiveRecord::Base
+        fields do
+        end
+        self.primary_key = "id"
       end
-      self.primary_key = "id"
-    end
 
-    puts "\n\e[45m Please enter 'id' (no quotes) at the next prompt \e[0m"
-    generate_migrations '-n', '-m'
-    expect(Foo.primary_key).to eq('id')
+      allow_any_instance_of(DeclareSchema::Support::ThorShell).to receive(:ask).with(/one of the rename choices or press enter to keep/) { 'id' }
+      generate_migrations '-n', '-m'
+      expect(Foo._defined_primary_key).to eq('id')
+
+      nuke_model_class(Foo)
 
-    nuke_model_class(Foo)
+      # The ActiveRecord sqlite3 driver has a bug where rename_column recreates the entire table, but forgets to set the primary key:
+      #
+      # [7] pry(#<RSpec::ExampleGroups::DeclareSchemaMigrationGeneratorInteractivePrimaryKey>)> u = 'rename_column :foos, :foo_id, :id'
+      # => "rename_column :foos, :foo_id, :id"
+      # [8] pry(#<RSpec::ExampleGroups::DeclareSchemaMigrationGeneratorInteractivePrimaryKey>)> ActiveRecord::Migration.class_eval(u)
+      # (0.0ms)  begin transaction
+      #  (pry):17
+      # (0.2ms)  CREATE TEMPORARY TABLE "afoos" ("id" integer NOT NULL)
+      #  (pry):17
+      # (0.1ms)  INSERT INTO "afoos" ("id")
+      #
+      #  (pry):17
+      # (0.4ms)  DROP TABLE "foos"
+      #  (pry):17
+      # (0.1ms)  CREATE TABLE "foos" ("id" integer NOT NULL)
+      #  (pry):17
+      # (0.1ms)  INSERT INTO "foos" ("id")
+      #
+      #  (pry):17
+      # (0.1ms)  DROP TABLE "afoos"
+      #  (pry):17
+      # (0.9ms)  commit transaction
+      if defined?(SQLite3)
+        ActiveRecord::Base.connection.execute("drop table foos")
+        ActiveRecord::Base.connection.execute("CREATE TABLE foos (id integer PRIMARY KEY AUTOINCREMENT NOT NULL)")
+      end
+
+      if Rails::VERSION::MAJOR >= 5 && !defined?(Mysql2) # TODO TECH-4814 Put this test back for Mysql2
+        # replace custom primary_key
+        class Foo < ActiveRecord::Base
+          fields do
+          end
+          self.primary_key = "foo_id"
+        end
 
-    ### migrate to
+        allow_any_instance_of(DeclareSchema::Support::ThorShell).to receive(:ask).with(/one of the rename choices or press enter to keep/) { 'drop id' }
+        generate_migrations '-n', '-m'
+        expect(Foo._defined_primary_key).to eq('foo_id')
+      end
+    end
+  end
 
-    if Rails::VERSION::MAJOR >= 5 && !defined?(Mysql2) # TODO TECH-4814 Put this test back for Mysql2
-      # replace custom primary_key
+  context 'Using declare_schema' do
+    it "allows alternate primary keys" do
       class Foo < ActiveRecord::Base
-        fields do
+        declare_schema do
         end
         self.primary_key = "foo_id"
       end
 
-      puts "\n\e[45m Please enter 'drop id' (no quotes) at the next prompt \e[0m"
       generate_migrations '-n', '-m'
       expect(Foo.primary_key).to eq('foo_id')
 
-      ### ensure it doesn't cause further migrations
+      ### migrate from
+      # rename from custom primary_key
+      class Foo < ActiveRecord::Base
+        declare_schema do
+        end
+        self.primary_key = "id"
+      end
 
-      # check no further migrations
-      up = Generators::DeclareSchema::Migration::Migrator.run.first
-      expect(up).to eq("")
+      puts "\n\e[45m Please enter 'id' (no quotes) at the next prompt \e[0m"
+      allow_any_instance_of(DeclareSchema::Support::ThorShell).to receive(:ask).with(/one of the rename choices or press enter to keep/) { 'id' }
+      generate_migrations '-n', '-m'
+      expect(Foo.primary_key).to eq('id')
+
+      nuke_model_class(Foo)
+
+      # The ActiveRecord sqlite3 driver has a bug where rename_column recreates the entire table, but forgets to set the primary key:
+      #
+      # [7] pry(#<RSpec::ExampleGroups::DeclareSchemaMigrationGeneratorInteractivePrimaryKey>)> u = 'rename_column :foos, :foo_id, :id'
+      # => "rename_column :foos, :foo_id, :id"
+      # [8] pry(#<RSpec::ExampleGroups::DeclareSchemaMigrationGeneratorInteractivePrimaryKey>)> ActiveRecord::Migration.class_eval(u)
+      # (0.0ms)  begin transaction
+      #  (pry):17
+      # (0.2ms)  CREATE TEMPORARY TABLE "afoos" ("id" integer NOT NULL)
+      #  (pry):17
+      # (0.1ms)  INSERT INTO "afoos" ("id")
+      #
+      #  (pry):17
+      # (0.4ms)  DROP TABLE "foos"
+      #  (pry):17
+      # (0.1ms)  CREATE TABLE "foos" ("id" integer NOT NULL)
+      #  (pry):17
+      # (0.1ms)  INSERT INTO "foos" ("id")
+      #
+      #  (pry):17
+      # (0.1ms)  DROP TABLE "afoos"
+      #  (pry):17
+      # (0.9ms)  commit transaction
+      if defined?(SQLite3)
+        ActiveRecord::Base.connection.execute("drop table foos")
+        ActiveRecord::Base.connection.execute("CREATE TABLE foos (id integer PRIMARY KEY AUTOINCREMENT NOT NULL)")
+      end
+
+      if Rails::VERSION::MAJOR >= 5 && !defined?(Mysql2) # TODO TECH-4814 Put this test back for Mysql2
+        # replace custom primary_key
+        class Foo < ActiveRecord::Base
+          declare_schema do
+          end
+          self.primary_key = "foo_id"
+        end
+
+        puts "\n\e[45m Please enter 'drop id' (no quotes) at the next prompt \e[0m"
+        allow_any_instance_of(DeclareSchema::Support::ThorShell).to receive(:ask).with(/one of the rename choices or press enter to keep/) { 'drop id' }
+        generate_migrations '-n', '-m'
+        expect(Foo.primary_key).to eq('foo_id')
+      end
     end
   end
 end

data/spec/lib/declare_schema/migration_generator_spec.rb

@@ -10,16 +10,6 @@ RSpec.describe 'DeclareSchema Migration Generator' do
   before do
     load File.expand_path('prepare_testapp.rb', __dir__)
   end
-
-  let(:charset_alter_table) do
-    if defined?(Mysql2)
-      <<~EOS
-
-
-        execute "ALTER TABLE `adverts` CHARACTER SET utf8mb4 COLLATE utf8mb4_bin"
-      EOS
-    end
-  end
   let(:text_limit) do
     if defined?(Mysql2)
       ", limit: 4294967295"
@@ -30,6 +20,11 @@ RSpec.describe 'DeclareSchema Migration Generator' do
       ', charset: "utf8mb4", collation: "utf8mb4_bin"'
     end
   end
+  let(:create_table_charset_and_collation) do
+    if defined?(Mysql2)
+      ", options: \"CHARACTER SET utf8mb4 COLLATE utf8mb4_bin\""
+    end
+  end
   let(:datetime_precision) do
     if defined?(Mysql2) && Rails::VERSION::MAJOR >= 5
       ', precision: 0'
@@ -55,1153 +50,2182 @@ RSpec.describe 'DeclareSchema Migration Generator' do
     end
   end
 
-  # DeclareSchema - Migration Generator
-  it 'generates migrations' do
-    ## The migration generator -- introduction
+  context 'Using fields' do
+    # DeclareSchema - Migration Generator
+    it 'generates migrations' do
+      ## The migration generator -- introduction
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to migrate_up("").and migrate_down("")
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to migrate_up("").and migrate_down("")
 
-    class Advert < ActiveRecord::Base
-    end
+      class Advert < ActiveRecord::Base
+      end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to migrate_up("").and migrate_down("")
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to migrate_up("").and migrate_down("")
 
-    Generators::DeclareSchema::Migration::Migrator.ignore_tables = ["green_fishes"]
+      Generators::DeclareSchema::Migration::Migrator.ignore_tables = ["green_fishes"]
 
-    Advert.connection.schema_cache.clear!
-    Advert.reset_column_information
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
 
-    class Advert < ActiveRecord::Base
-      fields do
-        name :string, limit: 250, null: true
+      class Advert < ActiveRecord::Base
+        fields do
+          name :string, limit: 250, null: true
+        end
       end
-    end
 
-    up, _ = Generators::DeclareSchema::Migration::Migrator.run.tap do |migrations|
-      expect(migrations).to(
-        migrate_up(<<~EOS.strip)
-          create_table :adverts, id: :bigint do |t|
-            t.string :name, limit: 250, null: true#{charset_and_collation}
-          end#{charset_alter_table}
-        EOS
-        .and migrate_down("drop_table :adverts")
-      )
-    end
+      up, _ = Generators::DeclareSchema::Migration::Migrator.run.tap do |migrations|
+        expect(migrations).to(
+          migrate_up(<<~EOS.strip)
+            create_table :adverts, id: :bigint#{create_table_charset_and_collation} do |t|
+              t.string :name, limit: 250, null: true#{charset_and_collation}
+            end
+          EOS
+          .and migrate_down("drop_table :adverts")
+        )
+      end
 
-    ActiveRecord::Migration.class_eval(up)
-    expect(Advert.columns.map(&:name)).to eq(["id", "name"])
+      ActiveRecord::Migration.class_eval(up)
+      expect(Advert.columns.map(&:name)).to eq(["id", "name"])
 
-    if Rails::VERSION::MAJOR < 5
-      # Rails 4 drivers don't always create PK properly. Fix that by dropping and recreating.
-      ActiveRecord::Base.connection.execute("drop table adverts")
-      if defined?(Mysql2)
-        ActiveRecord::Base.connection.execute("CREATE TABLE adverts (id integer PRIMARY KEY AUTO_INCREMENT NOT NULL, name varchar(250)) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin")
-      else
-        ActiveRecord::Base.connection.execute("CREATE TABLE adverts (id integer PRIMARY KEY AUTOINCREMENT  NOT NULL, name varchar(250))")
+      if Rails::VERSION::MAJOR < 5
+        # Rails 4 drivers don't always create PK properly. Fix that by dropping and recreating.
+        ActiveRecord::Base.connection.execute("drop table adverts")
+        if defined?(Mysql2)
+          ActiveRecord::Base.connection.execute("CREATE TABLE adverts (id integer PRIMARY KEY AUTO_INCREMENT NOT NULL, name varchar(250)) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin")
+        else
+          ActiveRecord::Base.connection.execute("CREATE TABLE adverts (id integer PRIMARY KEY AUTOINCREMENT  NOT NULL, name varchar(250))")
+        end
       end
-    end
 
-    class Advert < ActiveRecord::Base
-      fields do
-        name :string, limit: 250, null: true
-        body :text, null: true
-        published_at :datetime, null: true
+      class Advert < ActiveRecord::Base
+        fields do
+          name :string, limit: 250, null: true
+          body :text, null: true
+          published_at :datetime, null: true
+        end
       end
-    end
 
-    Advert.connection.schema_cache.clear!
-    Advert.reset_column_information
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
 
-    expect(migrate).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :body, :text#{text_limit}, null: true#{charset_and_collation}
-        add_column :adverts, :published_at, :datetime, null: true
-      EOS
-      .and migrate_down(<<~EOS.strip)
-        remove_column :adverts, :body
-        remove_column :adverts, :published_at
-      EOS
-    )
+      expect(migrate).to(
+        migrate_up(<<~EOS.strip)
+          add_column :adverts, :body, :text#{text_limit}, null: true#{charset_and_collation}
+          add_column :adverts, :published_at, :datetime, null: true
+        EOS
+        .and migrate_down(<<~EOS.strip)
+          remove_column :adverts, :published_at
+          remove_column :adverts, :body
+        EOS
+      )
 
-    Advert.field_specs.clear # not normally needed
-    class Advert < ActiveRecord::Base
-      fields do
-        name :string, limit: 250, null: true
-        body :text, null: true
+      Advert.field_specs.clear # not normally needed
+      class Advert < ActiveRecord::Base
+        fields do
+          name :string, limit: 250, null: true
+          body :text, null: true
+        end
       end
-    end
 
-    expect(migrate).to(
-      migrate_up("remove_column :adverts, :published_at").and(
-        migrate_down("add_column :adverts, :published_at, :datetime#{datetime_precision}, null: true")
+      expect(migrate).to(
+        migrate_up("remove_column :adverts, :published_at").and(
+          migrate_down("add_column :adverts, :published_at, :datetime#{datetime_precision}, null: true")
+        )
       )
-    )
 
-    nuke_model_class(Advert)
-    class Advert < ActiveRecord::Base
-      fields do
-        title :string, limit: 250, null: true
-        body :text, null: true
+      nuke_model_class(Advert)
+      class Advert < ActiveRecord::Base
+        fields do
+          title :string, limit: 250, null: true
+          body :text, null: true
+        end
       end
-    end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
-        remove_column :adverts, :name
-      EOS
-      .and migrate_down(<<~EOS.strip)
-        remove_column :adverts, :title
-        add_column :adverts, :name, :string, limit: 250, null: true#{charset_and_collation}
-      EOS
-    )
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          add_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
+          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
+        EOS
+      )
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: { name: :title })).to(
-      migrate_up("rename_column :adverts, :name, :title").and(
-        migrate_down("rename_column :adverts, :title, :name")
+      expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: { name: :title })).to(
+        migrate_up("rename_column :adverts, :name, :title").and(
+          migrate_down("rename_column :adverts, :title, :name")
+        )
       )
-    )
 
-    migrate
+      migrate
 
-    class Advert < ActiveRecord::Base
-      fields do
-        title :text, null: true
-        body :text, null: true
+      class Advert < ActiveRecord::Base
+        fields do
+          title :text, null: true
+          body :text, null: true
+        end
       end
-    end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up("change_column :adverts, :title, :text#{text_limit}, null: true#{charset_and_collation}").and(
-        migrate_down("change_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}")
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up("change_column :adverts, :title, :text#{text_limit}, null: true#{charset_and_collation}").and(
+          migrate_down("change_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}")
+        )
       )
-    )
 
-    class Advert < ActiveRecord::Base
-      fields do
-        title :string, default: "Untitled", limit: 250, null: true
-        body :text, null: true
+      class Advert < ActiveRecord::Base
+        fields do
+          title :string, default: "Untitled", limit: 250, null: true
+          body :text, null: true
+        end
       end
-    end
 
-    expect(migrate).to(
-      migrate_up(<<~EOS.strip)
-        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}
-      EOS
-    )
+      expect(migrate).to(
+        migrate_up(<<~EOS.strip)
+          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}
+        EOS
+      )
 
-    ### Limits
+      ### Limits
 
-    class Advert < ActiveRecord::Base
-      fields do
-        price :integer, null: true, limit: 2
+      class Advert < ActiveRecord::Base
+        fields do
+          price :integer, null: true, limit: 2
+        end
       end
-    end
-
-    up, _ = Generators::DeclareSchema::Migration::Migrator.run.tap do |migrations|
-      expect(migrations).to migrate_up("add_column :adverts, :price, :integer, limit: 2, null: true")
-    end
 
-    # Now run the migration, then change the limit:
-
-    ActiveRecord::Migration.class_eval(up)
-    class Advert < ActiveRecord::Base
-      fields do
-        price :integer, null: true, limit: 3
+      up, _ = Generators::DeclareSchema::Migration::Migrator.run.tap do |migrations|
+        expect(migrations).to migrate_up("add_column :adverts, :price, :integer, limit: 2, null: true")
       end
-    end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        change_column :adverts, :price, :integer, limit: 3, null: true
-      EOS
-      .and migrate_down(<<~EOS.strip)
-        change_column :adverts, :price, :integer, limit: 2, null: true
-      EOS
-    )
+      # Now run the migration, then change the limit:
 
-    ActiveRecord::Migration.class_eval("remove_column :adverts, :price")
-    class Advert < ActiveRecord::Base
-      fields do
-        price :decimal, precision: 4, scale: 1, null: true
+      ActiveRecord::Migration.class_eval(up)
+      class Advert < ActiveRecord::Base
+        fields do
+          price :integer, null: true, limit: 3
+        end
       end
-    end
 
-    # Limits are generally not needed for `text` fields, because by default, `text` fields will use the maximum size
-    # allowed for that database type (0xffffffff for LONGTEXT in MySQL unlimited in Postgres, 1 billion in Sqlite).
-    # If a `limit` is given, it will only be used in MySQL, to choose the smallest TEXT field that will accommodate
-    # that limit (0xff for TINYTEXT, 0xffff for TEXT, 0xffffff for MEDIUMTEXT, 0xffffffff for LONGTEXT).
-
-    if defined?(SQLite3)
-      expect(::DeclareSchema::Model::FieldSpec.mysql_text_limits?).to be_falsey
-    end
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          change_column :adverts, :price, :integer, limit: 3, null: true
+        EOS
+        .and migrate_down(<<~EOS.strip)
+          change_column :adverts, :price, :integer, limit: 2, null: true
+        EOS
+      )
 
-    class Advert < ActiveRecord::Base
-      fields do
-        notes :text
-        description :text, limit: 30000
+      ActiveRecord::Migration.class_eval("remove_column :adverts, :price")
+      class Advert < ActiveRecord::Base
+        fields do
+          price :decimal, precision: 4, scale: 1, null: true
+        end
       end
-    end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :price, :decimal, precision: 4, scale: 1, null: true
-        add_column :adverts, :notes, :text#{text_limit}, null: false#{charset_and_collation}
-        add_column :adverts, :description, :text#{', limit: 65535' if defined?(Mysql2)}, null: false#{charset_and_collation}
-      EOS
-    )
-
-    Advert.field_specs.delete :price
-    Advert.field_specs.delete :notes
-    Advert.field_specs.delete :description
+      # Limits are generally not needed for `text` fields, because by default, `text` fields will use the maximum size
+      # allowed for that database type (0xffffffff for LONGTEXT in MySQL unlimited in Postgres, 1 billion in Sqlite).
+      # If a `limit` is given, it will only be used in MySQL, to choose the smallest TEXT field that will accommodate
+      # that limit (0xff for TINYTEXT, 0xffff for TEXT, 0xffffff for MEDIUMTEXT, 0xffffffff for LONGTEXT).
 
-    # In MySQL, limits are applied, rounded up:
-
-    if defined?(Mysql2)
-      expect(::DeclareSchema::Model::FieldSpec.mysql_text_limits?).to be_truthy
+      if defined?(SQLite3)
+        expect(::DeclareSchema::Model::FieldSpec.mysql_text_limits?).to be_falsey
+      end
 
       class Advert < ActiveRecord::Base
         fields do
           notes :text
-          description :text, limit: 250
+          description :text, limit: 30000
         end
       end
 
       expect(Generators::DeclareSchema::Migration::Migrator.run).to(
         migrate_up(<<~EOS.strip)
-          add_column :adverts, :notes, :text, limit: 4294967295, null: false#{charset_and_collation}
-          add_column :adverts, :description, :text, limit: 255, null: false#{charset_and_collation}
+          add_column :adverts, :price, :decimal, precision: 4, scale: 1, null: true
+          add_column :adverts, :notes, :text#{text_limit}, null: false#{charset_and_collation}
+          add_column :adverts, :description, :text#{', limit: 65535' if defined?(Mysql2)}, null: false#{charset_and_collation}
         EOS
       )
 
+      Advert.field_specs.delete :price
       Advert.field_specs.delete :notes
+      Advert.field_specs.delete :description
+
+      # In MySQL, limits are applied, rounded up:
 
-      # Limits that are too high for MySQL will raise an exception.
+      if defined?(Mysql2)
+        expect(::DeclareSchema::Model::FieldSpec.mysql_text_limits?).to be_truthy
 
-      expect do
         class Advert < ActiveRecord::Base
           fields do
             notes :text
-            description :text, limit: 0x1_0000_0000
+            description :text, limit: 250
           end
         end
-      end.to raise_exception(ArgumentError, "limit of 4294967296 is too large for MySQL")
 
-      Advert.field_specs.delete :notes
+        expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+          migrate_up(<<~EOS.strip)
+            add_column :adverts, :notes, :text, limit: 4294967295, null: false#{charset_and_collation}
+            add_column :adverts, :description, :text, limit: 255, null: false#{charset_and_collation}
+          EOS
+        )
+
+        Advert.field_specs.delete :notes
+
+        # Limits that are too high for MySQL will raise an exception.
+
+        expect do
+          class Advert < ActiveRecord::Base
+            fields do
+              notes :text
+              description :text, limit: 0x1_0000_0000
+            end
+          end
+        end.to raise_exception(ArgumentError, "limit of 4294967296 is too large for MySQL")
+
+        Advert.field_specs.delete :notes
+
+        # And in MySQL, unstated text limits are treated as the maximum (LONGTEXT) limit.
+
+        # To start, we'll set the database schema for `description` to match the above limit of 250.
+
+        Advert.connection.execute "ALTER TABLE adverts ADD COLUMN description TINYTEXT"
+        Advert.connection.schema_cache.clear!
+        Advert.reset_column_information
+        expect(Advert.connection.tables - Generators::DeclareSchema::Migration::Migrator.always_ignore_tables).
+          to eq(["adverts"])
+        expect(Advert.columns.map(&:name)).to eq(["id", "body", "title", "description"])
+
+        # Now migrate to an unstated text limit:
+
+        class Advert < ActiveRecord::Base
+          fields do
+            description :text
+          end
+        end
+
+        expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+          migrate_up(<<~EOS.strip)
+            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}
+          EOS
+        )
+
+        # And migrate to a stated text limit that is the same as the unstated one:
+
+        class Advert < ActiveRecord::Base
+          fields do
+            description :text, limit: 0xffffffff
+          end
+        end
+
+        expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+          migrate_up(<<~EOS.strip)
+            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}
+          EOS
+        )
+      end
 
-      # And in MySQL, unstated text limits are treated as the maximum (LONGTEXT) limit.
+      Advert.field_specs.clear
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
+      class Advert < ActiveRecord::Base
+        fields do
+          name :string, limit: 250, null: true
+        end
+      end
 
-      # To start, we'll set the database schema for `description` to match the above limit of 250.
+      up = Generators::DeclareSchema::Migration::Migrator.run.first
+      ActiveRecord::Migration.class_eval up
 
-      Advert.connection.execute "ALTER TABLE adverts ADD COLUMN description TINYTEXT"
       Advert.connection.schema_cache.clear!
       Advert.reset_column_information
-      expect(Advert.connection.tables - Generators::DeclareSchema::Migration::Migrator.always_ignore_tables).
-        to eq(["adverts"])
-      expect(Advert.columns.map(&:name)).to eq(["id", "body", "title", "description"])
 
-      # Now migrate to an unstated text limit:
+      ### Foreign Keys
+
+      # DeclareSchema extends the `belongs_to` macro so that it also declares the
+      # foreign-key field.  It also generates an index on the field.
 
+      class Category < ActiveRecord::Base; end
       class Advert < ActiveRecord::Base
         fields do
-          description :text
+          name :string, limit: 250, null: true
         end
+        belongs_to :category
       end
 
       expect(Generators::DeclareSchema::Migration::Migrator.run).to(
         migrate_up(<<~EOS.strip)
-          change_column :adverts, :description, :text, limit: 4294967295, null: false#{charset_and_collation}
+          add_column :adverts, :category_id, :integer, limit: 8, null: false
+          add_index :adverts, [:category_id], name: :on_category_id
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id" if defined?(Mysql2)}
         EOS
         .and migrate_down(<<~EOS.strip)
-          change_column :adverts, :description, :text#{', limit: 255' if defined?(Mysql2)}, null: true#{charset_and_collation}
+          #{"remove_foreign_key :adverts, name: :on_category_id" if defined?(Mysql2)}
+          remove_index :adverts, name: :on_category_id
+          remove_column :adverts, :category_id
         EOS
       )
 
-      # And migrate to a stated text limit that is the same as the unstated one:
+      Advert.field_specs.delete(:category_id)
+      Advert.index_definitions.delete_if { |spec| spec.fields==["category_id"] }
 
+      # If you specify a custom foreign key, the migration generator observes that:
+
+      class Category < ActiveRecord::Base; end
       class Advert < ActiveRecord::Base
-        fields do
-          description :text, limit: 0xffffffff
-        end
+        fields { }
+        belongs_to :category, foreign_key: "c_id", class_name: 'Category'
       end
 
       expect(Generators::DeclareSchema::Migration::Migrator.run).to(
         migrate_up(<<~EOS.strip)
-          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}
+          add_column :adverts, :c_id, :integer, limit: 8, null: false
+          add_index :adverts, [:c_id], name: :on_c_id
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
         EOS
       )
-    end
-
-    Advert.field_specs.clear
-    Advert.connection.schema_cache.clear!
-    Advert.reset_column_information
-    class Advert < ActiveRecord::Base
-      fields do
-        name :string, limit: 250, null: true
-      end
-    end
-
-    up = Generators::DeclareSchema::Migration::Migrator.run.first
-    ActiveRecord::Migration.class_eval up
 
-    Advert.connection.schema_cache.clear!
-    Advert.reset_column_information
+      Advert.field_specs.delete(:c_id)
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["c_id"] }
 
-    ### Foreign Keys
+      # You can avoid generating the index by specifying `index: false`
 
-    # DeclareSchema extends the `belongs_to` macro so that it also declares the
-    # foreign-key field.  It also generates an index on the field.
-
-    class Category < ActiveRecord::Base; end
-    class Advert < ActiveRecord::Base
-      fields do
-        name :string, limit: 250, null: true
+      class Category < ActiveRecord::Base; end
+      class Advert < ActiveRecord::Base
+        fields { }
+        belongs_to :category, index: false
       end
-      belongs_to :category
-    end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :category_id, :integer, limit: 8, null: false
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          add_column :adverts, :category_id, :integer, limit: 8, null: false
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-        add_index :adverts, [:category_id], name: 'on_category_id'
+      Advert.field_specs.delete(:category_id)
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["category_id"] }
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" if defined?(Mysql2)}
-      EOS
-      .and migrate_down(<<~EOS.strip)
-        remove_column :adverts, :category_id
+      # You can specify the index name with :index
 
-        remove_index :adverts, name: :on_category_id rescue ActiveRecord::StatementInvalid
+      class Category < ActiveRecord::Base; end
+      class Advert < ActiveRecord::Base
+        fields { }
+        belongs_to :category, index: 'my_index'
+      end
 
-        #{"remove_foreign_key(\"adverts\", name: \"on_category_id\")\n" if defined?(Mysql2)}
-      EOS
-    )
+      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: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-    Advert.field_specs.delete(:category_id)
-    Advert.index_definitions.delete_if { |spec| spec.fields==["category_id"] }
+      Advert.field_specs.delete(:category_id)
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["category_id"] }
 
-    # If you specify a custom foreign key, the migration generator observes that:
+      ### Timestamps and Optimimistic Locking
 
-    class Category < ActiveRecord::Base; end
-    class Advert < ActiveRecord::Base
-      fields { }
-      belongs_to :category, foreign_key: "c_id", class_name: 'Category'
-    end
+      # `updated_at` and `created_at` can be declared with the shorthand `timestamps`.
+      # Similarly, `lock_version` can be declared with the "shorthand" `optimimistic_lock`.
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :c_id, :integer, limit: 8, null: false
+      class Advert < ActiveRecord::Base
+        fields do
+          timestamps
+          optimistic_lock
+        end
+      end
 
-        add_index :adverts, [:c_id], name: 'on_c_id'
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          add_column :adverts, :created_at, :datetime, null: true
+          add_column :adverts, :updated_at, :datetime, null: true
+          add_column :adverts, :lock_version, :integer#{lock_version_limit}, null: false, default: 1
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+        .and migrate_down(<<~EOS.strip)
+          #{"remove_foreign_key :adverts, name: :on_c_id\n" +
+            "remove_foreign_key :adverts, name: :on_category_id" if defined?(Mysql2)}
+          remove_column :adverts, :lock_version
+          remove_column :adverts, :updated_at
+          remove_column :adverts, :created_at
+        EOS
+      )
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")" if defined?(Mysql2)}
-      EOS
-    )
+      Advert.field_specs.delete(:updated_at)
+      Advert.field_specs.delete(:created_at)
+      Advert.field_specs.delete(:lock_version)
 
-    Advert.field_specs.delete(:c_id)
-    Advert.index_definitions.delete_if { |spec| spec.fields == ["c_id"] }
+      ### Indices
 
-    # You can avoid generating the index by specifying `index: false`
+      # You can add an index to a field definition
 
-    class Category < ActiveRecord::Base; end
-    class Advert < ActiveRecord::Base
-      fields { }
-      belongs_to :category, index: false
-    end
+      class Advert < ActiveRecord::Base
+        fields do
+          title :string, index: true, limit: 250, null: true
+        end
+      end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :category_id, :integer, limit: 8, null: false
+      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: :on_title
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"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 == ["category_id"] }
+      # You can ask for a unique index
 
-    # You can specify the index name with :index
+      class Advert < ActiveRecord::Base
+        fields do
+          title :string, index: true, unique: true, null: true, limit: 250
+        end
+      end
 
-    class Category < ActiveRecord::Base; end
-    class Advert < ActiveRecord::Base
-      fields { }
-      belongs_to :category, index: 'my_index'
-    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: :on_title, unique: true
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :category_id, :integer, limit: 8, null: false
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
 
-        add_index :adverts, [:category_id], name: 'my_index'
+      # You can specify the name for the index
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")" if defined?(Mysql2)}
-      EOS
-    )
+      class Advert < ActiveRecord::Base
+        fields do
+          title :string, index: 'my_index', limit: 250, null: true
+        end
+      end
 
-    Advert.field_specs.delete(:category_id)
-    Advert.index_definitions.delete_if { |spec| spec.fields == ["category_id"] }
+      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
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-    ### Timestamps and Optimimistic Locking
+      Advert.index_definitions.delete_if { |spec| spec.fields==["title"] }
 
-    # `updated_at` and `created_at` can be declared with the shorthand `timestamps`.
-    # Similarly, `lock_version` can be declared with the "shorthand" `optimimistic_lock`.
+      # You can ask for an index outside of the fields block
 
-    class Advert < ActiveRecord::Base
-      fields do
-        timestamps
-        optimistic_lock
+      class Advert < ActiveRecord::Base
+        index :title
       end
-    end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :created_at, :datetime, null: true
-        add_column :adverts, :updated_at, :datetime, null: true
-        add_column :adverts, :lock_version, :integer#{lock_version_limit}, null: false, default: 1
+      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: :on_title
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
+
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")" if defined?(Mysql2)}
-      EOS
-      .and migrate_down(<<~EOS.strip)
-        remove_column :adverts, :created_at
-        remove_column :adverts, :updated_at
-        remove_column :adverts, :lock_version
+      # The available options for the index function are `:unique` and `:name`
 
-        #{"remove_foreign_key(\"adverts\", name: \"on_category_id\")\n" +
-          "remove_foreign_key(\"adverts\", name: \"on_c_id\")" if defined?(Mysql2)}
-      EOS
-    )
+      class Advert < ActiveRecord::Base
+        index :title, unique: true, name: 'my_index'
+      end
 
-    Advert.field_specs.delete(:updated_at)
-    Advert.field_specs.delete(:created_at)
-    Advert.field_specs.delete(:lock_version)
+      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_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-    ### Indices
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
 
-    # You can add an index to a field definition
+      # You can create an index on more than one field
 
-    class Advert < ActiveRecord::Base
-      fields do
-        title :string, index: true, limit: 250, null: true
+      class Advert < ActiveRecord::Base
+        index [:title, :category_id]
       end
-    end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
+      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, :category_id], name: :on_title_and_category_id
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-        add_index :adverts, [:title], name: 'on_title'
+      Advert.index_definitions.delete_if { |spec| spec.fields==["title", "category_id"] }
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")" if defined?(Mysql2)}
-      EOS
-    )
+      # Finally, you can specify that the migration generator should completely ignore an
+      # index by passing its name to ignore_index in the model.
+      # This is helpful for preserving indices that can't be automatically generated, such as prefix indices in MySQL.
 
-    Advert.index_definitions.delete_if { |spec| spec.fields==["title"] }
+      ### Rename a table
 
-    # You can ask for a unique index
+      # The migration generator respects the `set_table_name` declaration, although as before,
+      # we need to explicitly tell the generator that we want a rename rather than a create and a drop.
 
-    class Advert < ActiveRecord::Base
-      fields do
-        title :string, index: true, unique: true, null: true, limit: 250
+      class Advert < ActiveRecord::Base
+        self.table_name = "ads"
+        fields do
+          title :string, limit: 250, null: true
+          body :text, null: true
+        end
       end
-    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], unique: true, name: 'on_title'
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")" if defined?(Mysql2)}
-      EOS
-    )
+      expect(Generators::DeclareSchema::Migration::Migrator.run("adverts" => "ads")).to(
+        migrate_up(<<~EOS.strip)
+          rename_table :adverts, :ads
+          add_column :ads, :title, :string, limit: 250, null: true#{charset_and_collation}
+          add_column :ads, :body, :text#{', limit: 4294967295' if defined?(Mysql2)}, null: true#{charset_and_collation}
+          #{if defined?(Mysql2)
+              "add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+              "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id"
+            end}
+        EOS
+        .and migrate_down(<<~EOS.strip)
+          #{if defined?(Mysql2)
+              "remove_foreign_key :adverts, name: :on_c_id\n" +
+              "remove_foreign_key :adverts, name: :on_category_id"
+            end}
+          remove_column :ads, :body
+          remove_column :ads, :title
+          rename_table :ads, :adverts
+        EOS
+      )
 
-    Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
+      # Set the table name back to what it should be and confirm we're in sync:
 
-    # You can specify the name for the index
+      nuke_model_class(Advert)
 
-    class Advert < ActiveRecord::Base
-      fields do
-        title :string, index: 'my_index', limit: 250, null: true
+      class Advert < ActiveRecord::Base
+        self.table_name = "adverts"
       end
-    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'
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")" if defined?(Mysql2)}
-      EOS
-    )
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to eq(["", ""])
 
-    Advert.index_definitions.delete_if { |spec| spec.fields==["title"] }
+      ### Rename a table
 
-    # You can ask for an index outside of the fields block
+      # As with renaming columns, we have to tell the migration generator about the rename. Here we create a new class 'Advertisement', and tell ActiveRecord to forget about the Advert class. This requires code that shouldn't be shown to impressionable children.
 
-    class Advert < ActiveRecord::Base
-      index :title
-    end
+      nuke_model_class(Advert)
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
+      class Advertisement < ActiveRecord::Base
+        fields do
+          title :string, limit: 250, null: true
+          body :text, null: true
+        end
+      end
 
-        add_index :adverts, [:title], name: 'on_title'
+      expect(Generators::DeclareSchema::Migration::Migrator.run("adverts" => "advertisements")).to(
+        migrate_up(<<~EOS.strip)
+          rename_table :adverts, :advertisements
+          add_column :advertisements, :title, :string, limit: 250, null: true#{charset_and_collation}
+          add_column :advertisements, :body, :text#{', limit: 4294967295' if defined?(Mysql2)}, null: true#{charset_and_collation}
+          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
+        EOS
+      )
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")" if defined?(Mysql2)}
-      EOS
-    )
+      ### Drop a table
 
-    Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
+      nuke_model_class(Advertisement)
 
-    # The available options for the index function are `:unique` and `:name`
+      # If you delete a model, the migration generator will create a `drop_table` migration.
 
-    class Advert < ActiveRecord::Base
-      index :title, unique: true, name: 'my_index'
-    end
+      # Dropping tables is where the automatic down-migration really comes in handy:
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          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
+        EOS
+      )
+
+      ## STI
+
+      ### Adding an STI subclass
+
+      # Adding a subclass or two should introduce the 'type' column and no other changes
+
+      class Advert < ActiveRecord::Base
+        fields do
+          body :text, null: true
+          title :string, default: "Untitled", limit: 250, null: true
+        end
+      end
+      up = Generators::DeclareSchema::Migration::Migrator.run.first
+      ActiveRecord::Migration.class_eval(up)
+
+      class FancyAdvert < Advert
+      end
+      class SuperFancyAdvert < FancyAdvert
+      end
+
+      up, _ = Generators::DeclareSchema::Migration::Migrator.run do |migrations|
+        expect(migrations).to(
+          migrate_up(<<~EOS.strip)
+            add_column :adverts, :type, :string, limit: 250, null: true#{charset_and_collation}
+            add_index :adverts, [:type], name: :on_type
+          EOS
+          .and migrate_down(<<~EOS.strip)
+            remove_column :adverts, :type
+            remove_index :adverts, name: :on_type
+          EOS
+        )
+      end
+
+      Advert.field_specs.delete(:type)
+      nuke_model_class(SuperFancyAdvert)
+      nuke_model_class(FancyAdvert)
+      Advert.index_definitions.delete_if { |spec| spec.fields==["type"] }
+
+      ## Coping with multiple changes
+
+      # The migration generator is designed to create complete migrations even if many changes to the models have taken place.
+
+      # First let's confirm we're in a known state. One model, 'Advert', with a string 'title' and text 'body':
+
+      ActiveRecord::Migration.class_eval up.gsub(/.*type.*/, '')
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
+
+      expect(Advert.connection.tables - Generators::DeclareSchema::Migration::Migrator.always_ignore_tables).
+        to eq(["adverts"])
+      expect(Advert.columns.map(&:name).sort).to eq(["body", "id", "title"])
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to eq(["", ""])
+
+
+      ### Rename a column and change the default
+
+      Advert.field_specs.clear
+
+      class Advert < ActiveRecord::Base
+        fields do
+          name :string, default: "No Name", limit: 250, null: true
+          body :text, null: true
+        end
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: { title: :name })).to(
+        migrate_up(<<~EOS.strip)
+          rename_column :adverts, :title, :name
+          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
+        EOS
+      )
+
+      ### Rename a table and add a column
+
+      nuke_model_class(Advert)
+      class Ad < ActiveRecord::Base
+        fields do
+          title      :string, default: "Untitled", limit: 250
+          body       :text, null: true
+          created_at :datetime
+        end
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: :ads)).to(
+        migrate_up(<<~EOS.strip)
+          rename_table :adverts, :ads
+          add_column :ads, :created_at, :datetime, null: false
+          change_column :ads, :title, :string, limit: 250, null: false, default: \"Untitled\"#{charset_and_collation}
+        EOS
+      )
+
+      class Advert < ActiveRecord::Base
+        fields do
+          body :text, null: true
+          title :string, default: "Untitled", limit: 250, null: true
+        end
+      end
+
+      ## Legacy Keys
+
+      # DeclareSchema has some support for legacy keys.
+
+      nuke_model_class(Ad)
+
+      class Advert < ActiveRecord::Base
+        fields do
+          body :text, null: true
+        end
+        self.primary_key = "advert_id"
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: { id: :advert_id })).to(
+        migrate_up(<<~EOS.strip)
+          rename_column :adverts, :id, :advert_id
+        EOS
+      )
+
+      nuke_model_class(Advert)
+      ActiveRecord::Base.connection.execute("drop table `adverts`;")
+
+      ## DSL
+
+      # The DSL allows lambdas and constants
+
+      class User < ActiveRecord::Base
+        fields do
+          company :string, limit: 250, ruby_default: -> { "BigCorp" }
+        end
+      end
+      expect(User.field_specs.keys).to eq(['company'])
+      expect(User.field_specs['company'].options[:ruby_default]&.call).to eq("BigCorp")
+
+      ## validates
+
+      # DeclareSchema can accept a validates hash in the field options.
+
+      class Ad < ActiveRecord::Base
+        class << self
+          def validates(field_name, options)
+          end
+        end
+      end
+      expect(Ad).to receive(:validates).with(:company, presence: true, uniqueness: { case_sensitive: false })
+      class Ad < ActiveRecord::Base
+        fields do
+          company :string, limit: 250, index: true, unique: true, validates: { presence: true, uniqueness: { case_sensitive: false } }
+        end
+        self.primary_key = "advert_id"
+      end
+      up, _down = Generators::DeclareSchema::Migration::Migrator.run
+      ActiveRecord::Migration.class_eval(up)
+      expect(Ad.field_specs['company'].options[:validates].inspect).to eq("{:presence=>true, :uniqueness=>{:case_sensitive=>false}}")
+    end
+
+    describe 'serialize' do
+      before do
+        class Ad < ActiveRecord::Base
+          @serialize_args = []
+
+          class << self
+            attr_reader :serialize_args
+
+            def serialize(*args)
+              @serialize_args << args
+            end
+          end
+        end
+      end
+
+      describe 'untyped' do
+        it 'allows serialize: true' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_list :text, limit: 0xFFFF, serialize: true
+            end
+          end
+
+          expect(Ad.serialize_args).to eq([[:allow_list]])
+        end
+
+        it 'converts defaults with .to_yaml' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_list :string, limit: 250, serialize: true, null: true, default: []
+              allow_hash :string, limit: 250, serialize: true, null: true, default: {}
+              allow_string :string, limit: 250, serialize: true, null: true, default: ['abc']
+              allow_null :string, limit: 250, serialize: true, null: true, default: nil
+            end
+          end
+
+          expect(Ad.field_specs['allow_list'].default).to eq("--- []\n")
+          expect(Ad.field_specs['allow_hash'].default).to eq("--- {}\n")
+          expect(Ad.field_specs['allow_string'].default).to eq("---\n- abc\n")
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
+        end
+      end
+
+      describe 'Array' do
+        it 'allows serialize: Array' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_list :string, limit: 250, serialize: Array, null: true
+            end
+          end
+
+          expect(Ad.serialize_args).to eq([[:allow_list, Array]])
+        end
+
+        it 'allows Array defaults' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_list :string, limit: 250, serialize: Array, null: true, default: [2]
+              allow_string :string, limit: 250, serialize: Array, null: true, default: ['abc']
+              allow_empty :string, limit: 250, serialize: Array, null: true, default: []
+              allow_null :string, limit: 250, serialize: Array, null: true, default: nil
+            end
+          end
+
+          expect(Ad.field_specs['allow_list'].default).to eq("---\n- 2\n")
+          expect(Ad.field_specs['allow_string'].default).to eq("---\n- abc\n")
+          expect(Ad.field_specs['allow_empty'].default).to eq(nil)
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
+        end
+      end
+
+      describe 'Hash' do
+        it 'allows serialize: Hash' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_list :string, limit: 250, serialize: Hash, null: true
+            end
+          end
+
+          expect(Ad.serialize_args).to eq([[:allow_list, Hash]])
+        end
+
+        it 'allows Hash defaults' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_loc :string, limit: 250, serialize: Hash, null: true, default: { 'state' => 'CA' }
+              allow_hash :string, limit: 250, serialize: Hash, null: true, default: {}
+              allow_null :string, limit: 250, serialize: Hash, null: true, default: nil
+            end
+          end
+
+          expect(Ad.field_specs['allow_loc'].default).to eq("---\nstate: CA\n")
+          expect(Ad.field_specs['allow_hash'].default).to eq(nil)
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
+        end
+      end
+
+      describe 'JSON' do
+        it 'allows serialize: JSON' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_list :string, limit: 250, serialize: JSON
+            end
+          end
+
+          expect(Ad.serialize_args).to eq([[:allow_list, JSON]])
+        end
+
+        it 'allows JSON defaults' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_hash :string, limit: 250, serialize: JSON, null: true, default: { 'state' => 'CA' }
+              allow_empty_array :string, limit: 250, serialize: JSON, null: true, default: []
+              allow_empty_hash :string, limit: 250, serialize: JSON, null: true, default: {}
+              allow_null :string, limit: 250, serialize: JSON, null: true, default: nil
+            end
+          end
+
+          expect(Ad.field_specs['allow_hash'].default).to eq("{\"state\":\"CA\"}")
+          expect(Ad.field_specs['allow_empty_array'].default).to eq("[]")
+          expect(Ad.field_specs['allow_empty_hash'].default).to eq("{}")
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
+        end
+      end
+
+      class ValueClass
+        delegate :present?, :inspect, to: :@value
+
+        def initialize(value)
+          @value = value
+        end
+
+        class << self
+          def dump(object)
+            if object&.present?
+              object.inspect
+            end
+          end
+
+          def load(serialized)
+            if serialized
+              raise 'not used ???'
+            end
+          end
+        end
+      end
+
+      describe 'custom coder' do
+        it 'allows serialize: ValueClass' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_list :string, limit: 250, serialize: ValueClass
+            end
+          end
+
+          expect(Ad.serialize_args).to eq([[:allow_list, ValueClass]])
+        end
+
+        it 'allows ValueClass defaults' do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_hash :string, limit: 250, serialize: ValueClass, null: true, default: ValueClass.new([2])
+              allow_empty_array :string, limit: 250, serialize: ValueClass, null: true, default: ValueClass.new([])
+              allow_null :string, limit: 250, serialize: ValueClass, null: true, default: nil
+            end
+          end
+
+          expect(Ad.field_specs['allow_hash'].default).to eq("[2]")
+          expect(Ad.field_specs['allow_empty_array'].default).to eq(nil)
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
+        end
+      end
+
+      it 'disallows serialize: with a non-string column type' do
+        expect do
+          class Ad < ActiveRecord::Base
+            fields do
+              allow_list :integer, limit: 8, serialize: true
+            end
+          end
+        end.to raise_exception(ArgumentError, /must be :string or :text/)
+      end
+    end
+
+    context "for Rails #{Rails::VERSION::MAJOR}" do
+      if Rails::VERSION::MAJOR >= 5
+        let(:optional_true) { { optional: true } }
+        let(:optional_false) { { optional: false } }
+      else
+        let(:optional_true) { {} }
+        let(:optional_false) { {} }
+      end
+      let(:optional_flag) { { false => optional_false, true => optional_true } }
+
+      describe 'belongs_to' do
+        before do
+          unless defined?(AdCategory)
+            class AdCategory < ActiveRecord::Base
+              fields { }
+            end
+          end
+
+          class Advert < ActiveRecord::Base
+            fields do
+              name :string, limit: 250, null: true
+              category_id :integer, limit: 8
+              nullable_category_id :integer, limit: 8, null: true
+            end
+          end
+          up = Generators::DeclareSchema::Migration::Migrator.run.first
+          ActiveRecord::Migration.class_eval(up)
+        end
+
+        it 'passes through optional: when given' do
+          class AdvertBelongsTo < ActiveRecord::Base
+            self.table_name = 'adverts'
+            fields { }
+            reset_column_information
+            belongs_to :ad_category, optional: true
+          end
+          expect(AdvertBelongsTo.reflections['ad_category'].options).to eq(optional_true)
+        end
+
+        describe 'contradictory settings' do # contradictory settings are ok--for example, during migration
+          it 'passes through optional: true, null: false' do
+            class AdvertBelongsTo < ActiveRecord::Base
+              self.table_name = 'adverts'
+              fields { }
+              reset_column_information
+              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)
+          end
+
+          it 'passes through optional: false, null: true' do
+            class AdvertBelongsTo < ActiveRecord::Base
+              self.table_name = 'adverts'
+              fields { }
+              reset_column_information
+              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)
+          end
+        end
+
+        [false, true].each do |nullable|
+          context "nullable=#{nullable}" do
+            it 'infers optional: from null:' do
+              eval <<~EOS
+                class AdvertBelongsTo < ActiveRecord::Base
+                  fields { }
+                  belongs_to :ad_category, null: #{nullable}
+                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)
+            end
+
+            it 'infers null: from optional:' do
+              eval <<~EOS
+                class AdvertBelongsTo < ActiveRecord::Base
+                  fields { }
+                  belongs_to :ad_category, optional: #{nullable}
+                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)
+            end
+          end
+        end
+      end
+    end
+
+    describe 'migration base class' do
+      it 'adapts to Rails 4' do
+        class Advert < active_record_base_class.constantize
+          fields do
+            title :string, limit: 100
+          end
+        end
+
+        generate_migrations '-n', '-m'
+
+        migrations = Dir.glob('db/migrate/*declare_schema_migration*.rb')
+        expect(migrations.size).to eq(1), migrations.inspect
+
+        migration_content = File.read(migrations.first)
+        first_line = migration_content.split("\n").first
+        base_class = first_line.split(' < ').last
+        expect(base_class).to eq("(Rails::VERSION::MAJOR >= 5 ? ActiveRecord::Migration[4.2] : ActiveRecord::Migration)")
+      end
+    end
+
+    context 'Does not generate migrations' do
+      it 'for aliased fields bigint -> integer limit 8' do
+        if Rails::VERSION::MAJOR >= 5 || !ActiveRecord::Base.connection.class.name.match?(/SQLite3Adapter/)
+          class Advert < active_record_base_class.constantize
+            fields do
+              price :bigint
+            end
+          end
+
+          generate_migrations '-n', '-m'
+
+          migrations = Dir.glob('db/migrate/*declare_schema_migration*.rb')
+          expect(migrations.size).to eq(1), migrations.inspect
+
+          if defined?(Mysql2) && Rails::VERSION::MAJOR < 5
+            ActiveRecord::Base.connection.execute("ALTER TABLE adverts ADD PRIMARY KEY (id)")
+          end
+
+          class Advert < active_record_base_class.constantize
+            fields do
+              price :integer, limit: 8
+            end
+          end
+
+          expect { generate_migrations '-n', '-g' }.to output("Database and models match -- nothing to change\n").to_stdout
+        end
+      end
+    end
+  end
+
+  context 'Using declare_schema' do
+    # DeclareSchema - Migration Generator
+    it 'generates migrations' do
+      ## The migration generator -- introduction
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to migrate_up("").and migrate_down("")
+
+      class Advert < ActiveRecord::Base
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to migrate_up("").and migrate_down("")
+
+      Generators::DeclareSchema::Migration::Migrator.ignore_tables = ["green_fishes"]
+
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
+
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :name, limit: 250, null: true
+        end
+      end
+
+      up, _ = Generators::DeclareSchema::Migration::Migrator.run.tap do |migrations|
+        expect(migrations).to(
+          migrate_up(<<~EOS.strip)
+            create_table :adverts, id: :bigint#{create_table_charset_and_collation} do |t|
+              t.string :name, limit: 250, null: true#{charset_and_collation}
+            end
+          EOS
+          .and migrate_down("drop_table :adverts")
+        )
+      end
+
+      ActiveRecord::Migration.class_eval(up)
+      expect(Advert.columns.map(&:name)).to eq(["id", "name"])
+
+      if Rails::VERSION::MAJOR < 5
+        # Rails 4 drivers don't always create PK properly. Fix that by dropping and recreating.
+        ActiveRecord::Base.connection.execute("drop table adverts")
+        if defined?(Mysql2)
+          ActiveRecord::Base.connection.execute("CREATE TABLE adverts (id integer PRIMARY KEY AUTO_INCREMENT NOT NULL, name varchar(250)) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin")
+        else
+          ActiveRecord::Base.connection.execute("CREATE TABLE adverts (id integer PRIMARY KEY AUTOINCREMENT  NOT NULL, name varchar(250))")
+        end
+      end
+
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :name, limit: 250, null: true
+          text :body, null: true
+          datetime :published_at, null: true
+        end
+      end
+
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
+
+      expect(migrate).to(
+        migrate_up(<<~EOS.strip)
+          add_column :adverts, :body, :text#{text_limit}, null: true#{charset_and_collation}
+          add_column :adverts, :published_at, :datetime, null: true
+        EOS
+        .and migrate_down(<<~EOS.strip)
+          remove_column :adverts, :published_at
+          remove_column :adverts, :body
+        EOS
+      )
+
+      Advert.field_specs.clear # not normally needed
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :name, limit: 250, null: true
+          text :body, null: true
+        end
+      end
+
+      expect(migrate).to(
+          migrate_up("remove_column :adverts, :published_at").and(
+              migrate_down("add_column :adverts, :published_at, :datetime#{datetime_precision}, null: true")
+          )
+      )
+
+      nuke_model_class(Advert)
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :title, limit: 250, null: true
+          text :body, null: true
+        end
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          add_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
+          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
+        EOS
+      )
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: { name: :title })).to(
+          migrate_up("rename_column :adverts, :name, :title").and(
+              migrate_down("rename_column :adverts, :title, :name")
+          )
+      )
+
+      migrate
+
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          text :title, null: true
+          text :body, null: true
+        end
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+          migrate_up("change_column :adverts, :title, :text#{text_limit}, null: true#{charset_and_collation}").and(
+              migrate_down("change_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}")
+          )
+      )
+
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :title, default: "Untitled", limit: 250, null: true
+          text :body, null: true
+        end
+      end
+
+      expect(migrate).to(
+          migrate_up(<<~EOS.strip)
+          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}
+      EOS
+      )
+
+      ### Limits
+
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          integer :price, null: true, limit: 2
+        end
+      end
+
+      up, _ = Generators::DeclareSchema::Migration::Migrator.run.tap do |migrations|
+        expect(migrations).to migrate_up("add_column :adverts, :price, :integer, limit: 2, null: true")
+      end
+
+      # Now run the migration, then change the limit:
+
+      ActiveRecord::Migration.class_eval(up)
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          integer :price, null: true, limit: 3
+        end
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+          migrate_up(<<~EOS.strip)
+          change_column :adverts, :price, :integer, limit: 3, null: true
+          EOS
+              .and migrate_down(<<~EOS.strip)
+          change_column :adverts, :price, :integer, limit: 2, null: true
+      EOS
+      )
+
+      ActiveRecord::Migration.class_eval("remove_column :adverts, :price")
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          decimal :price, precision: 4, scale: 1, null: true
+        end
+      end
+
+      # Limits are generally not needed for `text` fields, because by default, `text` fields will use the maximum size
+      # allowed for that database type (0xffffffff for LONGTEXT in MySQL unlimited in Postgres, 1 billion in Sqlite).
+      # If a `limit` is given, it will only be used in MySQL, to choose the smallest TEXT field that will accommodate
+      # that limit (0xff for TINYTEXT, 0xffff for TEXT, 0xffffff for MEDIUMTEXT, 0xffffffff for LONGTEXT).
+
+      if defined?(SQLite3)
+        expect(::DeclareSchema::Model::FieldSpec.mysql_text_limits?).to be_falsey
+      end
+
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          text :notes
+          text :description, limit: 30000
+        end
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+          migrate_up(<<~EOS.strip)
+          add_column :adverts, :price, :decimal, precision: 4, scale: 1, null: true
+          add_column :adverts, :notes, :text#{text_limit}, null: false#{charset_and_collation}
+          add_column :adverts, :description, :text#{', limit: 65535' if defined?(Mysql2)}, null: false#{charset_and_collation}
+      EOS
+      )
+
+      Advert.field_specs.delete :price
+      Advert.field_specs.delete :notes
+      Advert.field_specs.delete :description
+
+      # In MySQL, limits are applied, rounded up:
+
+      if defined?(Mysql2)
+        expect(::DeclareSchema::Model::FieldSpec.mysql_text_limits?).to be_truthy
+
+        class Advert < ActiveRecord::Base
+          declare_schema do
+            text :notes
+            text :description, limit: 250
+          end
+        end
+
+        expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+            migrate_up(<<~EOS.strip)
+            add_column :adverts, :notes, :text, limit: 4294967295, null: false#{charset_and_collation}
+            add_column :adverts, :description, :text, limit: 255, null: false#{charset_and_collation}
+        EOS
+        )
+
+        Advert.field_specs.delete :notes
+
+        # Limits that are too high for MySQL will raise an exception.
+
+        expect do
+          class Advert < ActiveRecord::Base
+            declare_schema do
+              text :notes
+              text :description, limit: 0x1_0000_0000
+            end
+          end
+        end.to raise_exception(ArgumentError, "limit of 4294967296 is too large for MySQL")
+
+        Advert.field_specs.delete :notes
+
+        # And in MySQL, unstated text limits are treated as the maximum (LONGTEXT) limit.
+
+        # To start, we'll set the database schema for `description` to match the above limit of 250.
+
+        Advert.connection.execute "ALTER TABLE adverts ADD COLUMN description TINYTEXT"
+        Advert.connection.schema_cache.clear!
+        Advert.reset_column_information
+        expect(Advert.connection.tables - Generators::DeclareSchema::Migration::Migrator.always_ignore_tables).
+            to eq(["adverts"])
+        expect(Advert.columns.map(&:name)).to eq(["id", "body", "title", "description"])
+
+        # Now migrate to an unstated text limit:
+
+        class Advert < ActiveRecord::Base
+          declare_schema do
+            text :description
+          end
+        end
+
+        expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+            migrate_up(<<~EOS.strip)
+            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}
+        EOS
+        )
+
+        # And migrate to a stated text limit that is the same as the unstated one:
+
+        class Advert < ActiveRecord::Base
+          declare_schema do
+            text :description, limit: 0xffffffff
+          end
+        end
+
+        expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+            migrate_up(<<~EOS.strip)
+            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}
+        EOS
+        )
+      end
+
+      Advert.field_specs.clear
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :name, limit: 250, null: true
+        end
+      end
+
+      up = Generators::DeclareSchema::Migration::Migrator.run.first
+      ActiveRecord::Migration.class_eval up
+
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
+
+      ### Foreign Keys
+
+      # DeclareSchema extends the `belongs_to` macro so that it also declares the
+      # foreign-key field.  It also generates an index on the field.
+
+      class Category < ActiveRecord::Base; end
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :name, limit: 250, null: true
+        end
+        belongs_to :category
+      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: :on_category_id
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" if defined?(Mysql2)}
+        EOS
+        .and migrate_down(<<~EOS.strip)
+          #{"remove_foreign_key :adverts, name: :on_category_id" if defined?(Mysql2)}
+          remove_index :adverts, name: :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"] }
+
+      # If you specify a custom foreign key, the migration generator observes that:
+
+      class Category < ActiveRecord::Base; end
+      class Advert < ActiveRecord::Base
+        declare_schema { }
+        belongs_to :category, foreign_key: "c_id", class_name: 'Category'
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          add_column :adverts, :c_id, :integer, limit: 8, null: false
+          add_index :adverts, [:c_id], name: :on_c_id
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
+
+      Advert.field_specs.delete(:c_id)
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["c_id"] }
+
+      # You can avoid generating the index by specifying `index: false`
+
+      class Category < ActiveRecord::Base; end
+      class Advert < ActiveRecord::Base
+        declare_schema { }
+        belongs_to :category, index: false
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          add_column :adverts, :category_id, :integer, limit: 8, null: false
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+       EOS
+      )
+
+      Advert.field_specs.delete(:category_id)
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["category_id"] }
+
+      # You can specify the index name with :index
+
+      class Category < ActiveRecord::Base; end
+      class Advert < ActiveRecord::Base
+        declare_schema { }
+        belongs_to :category, index: 'my_index'
+      end
 
-        add_index :adverts, [:title], unique: true, name: 'my_index'
+      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: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")" if defined?(Mysql2)}
-      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 == ["title"] }
+      ### Timestamps and Optimimistic Locking
 
-    # You can create an index on more than one field
+      # `updated_at` and `created_at` can be declared with the shorthand `timestamps`.
+      # Similarly, `lock_version` can be declared with the "shorthand" `optimimistic_lock`.
 
-    class Advert < ActiveRecord::Base
-      index [:title, :category_id]
-    end
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          timestamps
+          optimistic_lock
+        end
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          add_column :adverts, :created_at, :datetime, null: true
+          add_column :adverts, :updated_at, :datetime, null: true
+          add_column :adverts, :lock_version, :integer#{lock_version_limit}, null: false, default: 1
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+        .and migrate_down(<<~EOS.strip)
+          #{"remove_foreign_key :adverts, name: :on_c_id\n" +
+            "remove_foreign_key :adverts, name: :on_category_id" if defined?(Mysql2)}
+          remove_column :adverts, :lock_version
+          remove_column :adverts, :updated_at
+          remove_column :adverts, :created_at
+        EOS
+      )
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        add_column :adverts, :title, :string, limit: 250, null: true#{charset_and_collation}
+      Advert.field_specs.delete(:updated_at)
+      Advert.field_specs.delete(:created_at)
+      Advert.field_specs.delete(:lock_version)
 
-        add_index :adverts, [:title, :category_id], name: 'on_title_and_category_id'
+      ### Indices
 
-        #{"add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-          "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")" if defined?(Mysql2)}
-      EOS
-    )
+      # You can add an index to a field definition
 
-    Advert.index_definitions.delete_if { |spec| spec.fields==["title", "category_id"] }
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :title, index: true, limit: 250, null: true
+        end
+      end
 
-    # Finally, you can specify that the migration generator should completely ignore an
-    # index by passing its name to ignore_index in the model.
-    # This is helpful for preserving indices that can't be automatically generated, such as prefix indices in MySQL.
+      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: :on_title
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-    ### Rename a table
+      Advert.index_definitions.delete_if { |spec| spec.fields==["title"] }
 
-    # The migration generator respects the `set_table_name` declaration, although as before, we need to explicitly tell the generator that we want a rename rather than a create and a drop.
+      # You can ask for a unique index
 
-    class Advert < ActiveRecord::Base
-      self.table_name = "ads"
-      fields do
-        title :string, limit: 250, null: true
-        body :text, null: true
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :title, index: true, unique: true, null: true, limit: 250
+        end
       end
-    end
 
-    Advert.connection.schema_cache.clear!
-    Advert.reset_column_information
+      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: :on_title, unique: true
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run("adverts" => "ads")).to(
-      migrate_up(<<~EOS.strip)
-        rename_table :adverts, :ads
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
 
-        add_column :ads, :title, :string, limit: 250, null: true#{charset_and_collation}
-        add_column :ads, :body, :text#{', limit: 4294967295' if defined?(Mysql2)}, null: true#{charset_and_collation}
+      # You can specify the name for the index
 
-        #{if defined?(SQLite3)
-            "add_index :ads, [:id], unique: true, name: 'PRIMARY'\n"
-          elsif defined?(Mysql2)
-            "execute \"ALTER TABLE ads DROP PRIMARY KEY, ADD PRIMARY KEY (id)\"\n\n" +
-            "add_foreign_key(\"adverts\", \"categories\", column: \"category_id\", name: \"on_category_id\")\n" +
-            "add_foreign_key(\"adverts\", \"categories\", column: \"c_id\", name: \"on_c_id\")"
-          end}
-      EOS
-      .and migrate_down(<<~EOS.strip)
-        remove_column :ads, :title
-        remove_column :ads, :body
-
-        rename_table :ads, :adverts
-
-        #{if defined?(SQLite3)
-            "add_index :adverts, [:id], unique: true, name: 'PRIMARY'\n"
-          elsif defined?(Mysql2)
-            "execute \"ALTER TABLE adverts DROP PRIMARY KEY, ADD PRIMARY KEY (id)\"\n\n" +
-            "remove_foreign_key(\"adverts\", name: \"on_category_id\")\n" +
-            "remove_foreign_key(\"adverts\", name: \"on_c_id\")"
-          end}
-      EOS
-    )
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :title, index: 'my_index', limit: 250, null: true
+        end
+      end
 
-    # Set the table name back to what it should be and confirm we're in sync:
+      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
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-    nuke_model_class(Advert)
+      Advert.index_definitions.delete_if { |spec| spec.fields==["title"] }
 
-    class Advert < ActiveRecord::Base
-      self.table_name = "adverts"
-    end
+      # You can ask for an index outside of the fields block
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to eq(["", ""])
+      class Advert < ActiveRecord::Base
+        index :title
+      end
 
-    ### Rename a table
+      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: :on_title
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-    # As with renaming columns, we have to tell the migration generator about the rename. Here we create a new class 'Advertisement', and tell ActiveRecord to forget about the Advert class. This requires code that shouldn't be shown to impressionable children.
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
 
-    nuke_model_class(Advert)
+      # The available options for the index function are `:unique` and `:name`
 
-    class Advertisement < ActiveRecord::Base
-      fields do
-        title :string, limit: 250, null: true
-        body :text, null: true
+      class Advert < ActiveRecord::Base
+        index :title, unique: true, name: 'my_index'
       end
-    end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run("adverts" => "advertisements")).to(
-      migrate_up(<<~EOS.strip)
-        rename_table :adverts, :advertisements
+      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_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-        add_column :advertisements, :title, :string, limit: 250, null: true#{charset_and_collation}
-        add_column :advertisements, :body, :text#{', limit: 4294967295' if defined?(Mysql2)}, null: true#{charset_and_collation}
-        remove_column :advertisements, :name
+      Advert.index_definitions.delete_if { |spec| spec.fields == ["title"] }
 
-        #{if defined?(SQLite3)
-            "add_index :advertisements, [:id], unique: true, name: 'PRIMARY'"
-          elsif defined?(Mysql2)
-            "execute \"ALTER TABLE advertisements DROP PRIMARY KEY, ADD PRIMARY KEY (id)\""
-          end}
-      EOS
-      .and migrate_down(<<~EOS.strip)
-        remove_column :advertisements, :title
-        remove_column :advertisements, :body
-        add_column :adverts, :name, :string, limit: 250, null: true#{charset_and_collation}
-
-        rename_table :advertisements, :adverts
-
-        #{if defined?(SQLite3)
-            "add_index :adverts, [:id], unique: true, name: 'PRIMARY'"
-          elsif defined?(Mysql2)
-            "execute \"ALTER TABLE adverts DROP PRIMARY KEY, ADD PRIMARY KEY (id)\""
-          end}
-      EOS
-    )
+      # You can create an index on more than one field
 
-    ### Drop a table
+      class Advert < ActiveRecord::Base
+        index [:title, :category_id]
+      end
 
-    nuke_model_class(Advertisement)
+      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, :category_id], name: :on_title_and_category_id
+          #{"add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+            "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id" if defined?(Mysql2)}
+        EOS
+      )
 
-    # If you delete a model, the migration generator will create a `drop_table` migration.
+      Advert.index_definitions.delete_if { |spec| spec.fields==["title", "category_id"] }
 
-    # Dropping tables is where the automatic down-migration really comes in handy:
+      # Finally, you can specify that the migration generator should completely ignore an
+      # index by passing its name to ignore_index in the model.
+      # This is helpful for preserving indices that can't be automatically generated, such as prefix indices in MySQL.
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to(
-      migrate_up(<<~EOS.strip)
-        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}
+      ### Rename a table
+
+      # The migration generator respects the `set_table_name` declaration, although as before, we need to explicitly tell the generator that we want a rename rather than a create and a drop.
+
+      class Advert < ActiveRecord::Base
+        self.table_name = "ads"
+        declare_schema do
+          string :title, limit: 250, null: true
+          text :body, null: true
         end
-      EOS
-    )
+      end
+
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
 
-    ## STI
+      expect(Generators::DeclareSchema::Migration::Migrator.run("adverts" => "ads")).to(
+        migrate_up(<<~EOS.strip)
+          rename_table :adverts, :ads
+          add_column :ads, :title, :string, limit: 250, null: true#{charset_and_collation}
+          add_column :ads, :body, :text#{', limit: 4294967295' if defined?(Mysql2)}, null: true#{charset_and_collation}
+          #{if defined?(Mysql2)
+              "add_foreign_key :adverts, :categories, column: :category_id, name: :on_category_id\n" +
+              "add_foreign_key :adverts, :categories, column: :c_id, name: :on_c_id"
+            end}
+          EOS
+          .and migrate_down(<<~EOS.strip)
+            #{if defined?(Mysql2)
+                "remove_foreign_key :adverts, name: :on_c_id\n" +
+                "remove_foreign_key :adverts, name: :on_category_id"
+              end}
+            remove_column :ads, :body
+            remove_column :ads, :title
+            rename_table :ads, :adverts
+          EOS
+      )
 
-    ### Adding an STI subclass
+      # Set the table name back to what it should be and confirm we're in sync:
 
-    # Adding a subclass or two should introduce the 'type' column and no other changes
+      nuke_model_class(Advert)
 
-    class Advert < ActiveRecord::Base
-      fields do
-        body :text, null: true
-        title :string, default: "Untitled", limit: 250, null: true
+      class Advert < ActiveRecord::Base
+        self.table_name = "adverts"
       end
-    end
-    up = Generators::DeclareSchema::Migration::Migrator.run.first
-    ActiveRecord::Migration.class_eval(up)
 
-    class FancyAdvert < Advert
-    end
-    class SuperFancyAdvert < FancyAdvert
-    end
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to eq(["", ""])
 
-    up, _ = Generators::DeclareSchema::Migration::Migrator.run do |migrations|
-      expect(migrations).to(
-        migrate_up(<<~EOS.strip)
-          add_column :adverts, :type, :string, limit: 250, null: true#{charset_and_collation}
+      ### Rename a table
+
+      # As with renaming columns, we have to tell the migration generator about the rename. Here we create a new class 'Advertisement', and tell ActiveRecord to forget about the Advert class. This requires code that shouldn't be shown to impressionable children.
 
-          add_index :adverts, [:type], name: 'on_type'
+      nuke_model_class(Advert)
+
+      class Advertisement < ActiveRecord::Base
+        declare_schema do
+          string :title, limit: 250, null: true
+          text :body, null: true
+        end
+      end
+
+      expect(Generators::DeclareSchema::Migration::Migrator.run("adverts" => "advertisements")).to(
+        migrate_up(<<~EOS.strip)
+          rename_table :adverts, :advertisements
+          add_column :advertisements, :title, :string, limit: 250, null: true#{charset_and_collation}
+          add_column :advertisements, :body, :text#{', limit: 4294967295' if defined?(Mysql2)}, null: true#{charset_and_collation}
+          remove_column :advertisements, :name
         EOS
         .and migrate_down(<<~EOS.strip)
-          remove_column :adverts, :type
-
-          remove_index :adverts, name: :on_type rescue ActiveRecord::StatementInvalid
+          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
       )
-    end
 
-    Advert.field_specs.delete(:type)
-    nuke_model_class(SuperFancyAdvert)
-    nuke_model_class(FancyAdvert)
-    Advert.index_definitions.delete_if { |spec| spec.fields==["type"] }
+      ### Drop a table
 
-    ## Coping with multiple changes
+      nuke_model_class(Advertisement)
 
-    # The migration generator is designed to create complete migrations even if many changes to the models have taken place.
+      # If you delete a model, the migration generator will create a `drop_table` migration.
 
-    # First let's confirm we're in a known state. One model, 'Advert', with a string 'title' and text 'body':
+      # Dropping tables is where the automatic down-migration really comes in handy:
 
-    ActiveRecord::Migration.class_eval up.gsub(/.*type.*/, '')
-    Advert.connection.schema_cache.clear!
-    Advert.reset_column_information
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to(
+        migrate_up(<<~EOS.strip)
+          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
+        EOS
+      )
 
-    expect(Advert.connection.tables - Generators::DeclareSchema::Migration::Migrator.always_ignore_tables).
-      to eq(["adverts"])
-    expect(Advert.columns.map(&:name).sort).to eq(["body", "id", "title"])
-    expect(Generators::DeclareSchema::Migration::Migrator.run).to eq(["", ""])
+      ## STI
 
+      ### Adding an STI subclass
 
-    ### Rename a column and change the default
+      # Adding a subclass or two should introduce the 'type' column and no other changes
 
-    Advert.field_specs.clear
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          text :body, null: true
+          string :title, default: "Untitled", limit: 250, null: true
+        end
+      end
+      up = Generators::DeclareSchema::Migration::Migrator.run.first
+      ActiveRecord::Migration.class_eval(up)
 
-    class Advert < ActiveRecord::Base
-      fields do
-        name :string, default: "No Name", limit: 250, null: true
-        body :text, null: true
+      class FancyAdvert < Advert
+      end
+      class SuperFancyAdvert < FancyAdvert
       end
-    end
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: { title: :name })).to(
-      migrate_up(<<~EOS.strip)
-        rename_column :adverts, :title, :name
-        change_column :adverts, :name, :string, limit: 250, null: true, default: "No Name"#{charset_and_collation}
-      EOS
-      .and migrate_down(<<~EOS.strip)
-        rename_column :adverts, :name, :title
-        change_column :adverts, :title, :string, limit: 250, null: true, default: "Untitled"#{charset_and_collation}
-      EOS
-    )
+      up, _ = Generators::DeclareSchema::Migration::Migrator.run do |migrations|
+        expect(migrations).to(
+          migrate_up(<<~EOS.strip)
+            add_column :adverts, :type, :string, limit: 250, null: true#{charset_and_collation}
+            add_index :adverts, [:type], name: :on_type
+          EOS
+          .and migrate_down(<<~EOS.strip)
+            remove_index :adverts, name: :on_type
+            remove_column :adverts, :type
+          EOS
+        )
+      end
 
-    ### Rename a table and add a column
+      Advert.field_specs.delete(:type)
+      nuke_model_class(SuperFancyAdvert)
+      nuke_model_class(FancyAdvert)
+      Advert.index_definitions.delete_if { |spec| spec.fields==["type"] }
 
-    nuke_model_class(Advert)
-    class Ad < ActiveRecord::Base
-      fields do
-        title      :string, default: "Untitled", limit: 250
-        body       :text, null: true
-        created_at :datetime
-      end
-    end
+      ## Coping with multiple changes
 
-    expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: :ads)).to(
-      migrate_up(<<~EOS.strip)
-        rename_table :adverts, :ads
+      # The migration generator is designed to create complete migrations even if many changes to the models have taken place.
 
-        add_column :ads, :created_at, :datetime, null: false
-        change_column :ads, :title, :string, limit: 250, null: false, default: \"Untitled\"#{charset_and_collation}
+      # First let's confirm we're in a known state. One model, 'Advert', with a string 'title' and text 'body':
 
-        #{if defined?(SQLite3)
-            "add_index :ads, [:id], unique: true, name: 'PRIMARY'"
-          elsif defined?(Mysql2)
-            'execute "ALTER TABLE ads DROP PRIMARY KEY, ADD PRIMARY KEY (id)"'
-          end}
-      EOS
-    )
+      ActiveRecord::Migration.class_eval up.gsub(/.*type.*/, '')
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
 
-    class Advert < ActiveRecord::Base
-      fields do
-        body :text, null: true
-        title :string, default: "Untitled", limit: 250, null: true
-      end
-    end
+      expect(Advert.connection.tables - Generators::DeclareSchema::Migration::Migrator.always_ignore_tables).
+          to eq(["adverts"])
+      expect(Advert.columns.map(&:name).sort).to eq(["body", "id", "title"])
+      expect(Generators::DeclareSchema::Migration::Migrator.run).to eq(["", ""])
 
-    ## Legacy Keys
 
-    # DeclareSchema has some support for legacy keys.
+      ### Rename a column and change the default
 
-    nuke_model_class(Ad)
+      Advert.field_specs.clear
 
-    class Advert < ActiveRecord::Base
-      fields do
-        body :text, null: true
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          string :name, default: "No Name", limit: 250, null: true
+          text :body, null: true
+        end
       end
-      self.primary_key = "advert_id"
-    end
-
-    expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: { id: :advert_id })).to(
-      migrate_up(<<~EOS.strip)
-        rename_column :adverts, :id, :advert_id
 
-        #{if defined?(SQLite3)
-            "add_index :adverts, [:advert_id], unique: true, name: 'PRIMARY'"
-          elsif defined?(Mysql2)
-          'execute "ALTER TABLE adverts DROP PRIMARY KEY, ADD PRIMARY KEY (advert_id)"'
-          end}
-      EOS
-    )
+      expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: { title: :name })).to(
+        migrate_up(<<~EOS.strip)
+          rename_column :adverts, :title, :name
+          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
+        EOS
+      )
 
-    nuke_model_class(Advert)
-    ActiveRecord::Base.connection.execute("drop table `adverts`;")
+      ### Rename a table and add a column
 
-    ## DSL
+      nuke_model_class(Advert)
+      class Ad < ActiveRecord::Base
+        declare_schema do
+          string   :title, default: "Untitled", limit: 250
+          text     :body, null: true
+          datetime :created_at
+        end
+      end
 
-    # The DSL allows lambdas and constants
+      expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: :ads)).to(
+        migrate_up(<<~EOS.strip)
+          rename_table :adverts, :ads
+          add_column :ads, :created_at, :datetime, null: false
+          change_column :ads, :title, :string, limit: 250, null: false, default: \"Untitled\"#{charset_and_collation}
+        EOS
+      )
 
-    class User < ActiveRecord::Base
-      fields do
-        company :string, limit: 250, ruby_default: -> { "BigCorp" }
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          text :body, null: true
+          string :title, default: "Untitled", limit: 250, null: true
+        end
       end
-    end
-    expect(User.field_specs.keys).to eq(['company'])
-    expect(User.field_specs['company'].options[:ruby_default]&.call).to eq("BigCorp")
 
-    ## validates
+      ## Legacy Keys
+
+      # DeclareSchema has some support for legacy keys.
 
-    # DeclareSchema can accept a validates hash in the field options.
+      nuke_model_class(Ad)
 
-    class Ad < ActiveRecord::Base
-      class << self
-        def validates(field_name, options)
+      class Advert < ActiveRecord::Base
+        declare_schema do
+          text :body, null: true
         end
+        self.primary_key = "advert_id"
       end
-    end
-    expect(Ad).to receive(:validates).with(:company, presence: true, uniqueness: { case_sensitive: false })
-    class Ad < ActiveRecord::Base
-      fields do
-        company :string, limit: 250, index: true, unique: true, validates: { presence: true, uniqueness: { case_sensitive: false } }
-      end
-      self.primary_key = "advert_id"
-    end
-    up, _down = Generators::DeclareSchema::Migration::Migrator.run
-    ActiveRecord::Migration.class_eval(up)
-    expect(Ad.field_specs['company'].options[:validates].inspect).to eq("{:presence=>true, :uniqueness=>{:case_sensitive=>false}}")
-  end
 
-  describe 'serialize' do
-    before do
-      class Ad < ActiveRecord::Base
-        @serialize_args = []
+      expect(Generators::DeclareSchema::Migration::Migrator.run(adverts: { id: :advert_id })).to(
+        migrate_up(<<~EOS.strip)
+          rename_column :adverts, :id, :advert_id
+        EOS
+      )
 
-        class << self
-          attr_reader :serialize_args
+      nuke_model_class(Advert)
+      ActiveRecord::Base.connection.execute("drop table `adverts`;")
 
-          def serialize(*args)
-            @serialize_args << args
-          end
+      ## DSL
+
+      # The DSL allows lambdas and constants
+
+      class User < ActiveRecord::Base
+        declare_schema do
+          string :company, limit: 250, ruby_default: -> { "BigCorp" }
         end
       end
-    end
+      expect(User.field_specs.keys).to eq(['company'])
+      expect(User.field_specs['company'].options[:ruby_default]&.call).to eq("BigCorp")
 
-    describe 'untyped' do
-      it 'allows serialize: true' do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_list :text, limit: 0xFFFF, serialize: true
-          end
-        end
+      ## validates
 
-        expect(Ad.serialize_args).to eq([[:allow_list]])
-      end
+      # DeclareSchema can accept a validates hash in the field options.
 
-      it 'converts defaults with .to_yaml' do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_list :string, limit: 250, serialize: true, null: true, default: []
-            allow_hash :string, limit: 250, serialize: true, null: true, default: {}
-            allow_string :string, limit: 250, serialize: true, null: true, default: ['abc']
-            allow_null :string, limit: 250, serialize: true, null: true, default: nil
+      class Ad < ActiveRecord::Base
+        class << self
+          def validates(field_name, options)
           end
         end
-
-        expect(Ad.field_specs['allow_list'].default).to eq("--- []\n")
-        expect(Ad.field_specs['allow_hash'].default).to eq("--- {}\n")
-        expect(Ad.field_specs['allow_string'].default).to eq("---\n- abc\n")
-        expect(Ad.field_specs['allow_null'].default).to eq(nil)
       end
+      expect(Ad).to receive(:validates).with(:company, presence: true, uniqueness: { case_sensitive: false })
+      class Ad < ActiveRecord::Base
+        declare_schema do
+          string :company, limit: 250, index: true, unique: true, validates: { presence: true, uniqueness: { case_sensitive: false } }
+        end
+        self.primary_key = "advert_id"
+      end
+      up, _down = Generators::DeclareSchema::Migration::Migrator.run
+      ActiveRecord::Migration.class_eval(up)
+      expect(Ad.field_specs['company'].options[:validates].inspect).to eq("{:presence=>true, :uniqueness=>{:case_sensitive=>false}}")
     end
 
-    describe 'Array' do
-      it 'allows serialize: Array' do
+    describe 'serialize' do
+      before do
         class Ad < ActiveRecord::Base
-          fields do
-            allow_list :string, limit: 250, serialize: Array, null: true
-          end
-        end
+          @serialize_args = []
 
-        expect(Ad.serialize_args).to eq([[:allow_list, Array]])
-      end
+          class << self
+            attr_reader :serialize_args
 
-      it 'allows Array defaults' do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_list :string, limit: 250, serialize: Array, null: true, default: [2]
-            allow_string :string, limit: 250, serialize: Array, null: true, default: ['abc']
-            allow_empty :string, limit: 250, serialize: Array, null: true, default: []
-            allow_null :string, limit: 250, serialize: Array, null: true, default: nil
+            def serialize(*args)
+              @serialize_args << args
+            end
           end
         end
-
-        expect(Ad.field_specs['allow_list'].default).to eq("---\n- 2\n")
-        expect(Ad.field_specs['allow_string'].default).to eq("---\n- abc\n")
-        expect(Ad.field_specs['allow_empty'].default).to eq(nil)
-        expect(Ad.field_specs['allow_null'].default).to eq(nil)
       end
-    end
 
-    describe 'Hash' do
-      it 'allows serialize: Hash' do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_list :string, limit: 250, serialize: Hash, null: true
+      describe 'untyped' do
+        it 'allows serialize: true' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              text :allow_list, limit: 0xFFFF, serialize: true
+            end
           end
-        end
 
-        expect(Ad.serialize_args).to eq([[:allow_list, Hash]])
-      end
+          expect(Ad.serialize_args).to eq([[:allow_list]])
+        end
 
-      it 'allows Hash defaults' do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_loc :string, limit: 250, serialize: Hash, null: true, default: { 'state' => 'CA' }
-            allow_hash :string, limit: 250, serialize: Hash, null: true, default: {}
-            allow_null :string, limit: 250, serialize: Hash, null: true, default: nil
+        it 'converts defaults with .to_yaml' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              string :allow_list, limit: 250, serialize: true, null: true, default: []
+              string :allow_hash, limit: 250, serialize: true, null: true, default: {}
+              string :allow_string, limit: 250, serialize: true, null: true, default: ['abc']
+              string :allow_null, limit: 250, serialize: true, null: true, default: nil
+            end
           end
-        end
 
-        expect(Ad.field_specs['allow_loc'].default).to eq("---\nstate: CA\n")
-        expect(Ad.field_specs['allow_hash'].default).to eq(nil)
-        expect(Ad.field_specs['allow_null'].default).to eq(nil)
+          expect(Ad.field_specs['allow_list'].default).to eq("--- []\n")
+          expect(Ad.field_specs['allow_hash'].default).to eq("--- {}\n")
+          expect(Ad.field_specs['allow_string'].default).to eq("---\n- abc\n")
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
+        end
       end
-    end
 
-    describe 'JSON' do
-      it 'allows serialize: JSON' do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_list :string, limit: 250, serialize: JSON
+      describe 'Array' do
+        it 'allows serialize: Array' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              string :allow_list, limit: 250, serialize: Array, null: true
+            end
           end
+
+          expect(Ad.serialize_args).to eq([[:allow_list, Array]])
         end
 
-        expect(Ad.serialize_args).to eq([[:allow_list, JSON]])
+        it 'allows Array defaults' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              string :allow_list, limit: 250, serialize: Array, null: true, default: [2]
+              string :allow_string, limit: 250, serialize: Array, null: true, default: ['abc']
+              string :allow_empty, limit: 250, serialize: Array, null: true, default: []
+              string :allow_null, limit: 250, serialize: Array, null: true, default: nil
+            end
+          end
+
+          expect(Ad.field_specs['allow_list'].default).to eq("---\n- 2\n")
+          expect(Ad.field_specs['allow_string'].default).to eq("---\n- abc\n")
+          expect(Ad.field_specs['allow_empty'].default).to eq(nil)
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
+        end
       end
 
-      it 'allows JSON defaults' do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_hash :string, limit: 250, serialize: JSON, null: true, default: { 'state' => 'CA' }
-            allow_empty_array :string, limit: 250, serialize: JSON, null: true, default: []
-            allow_empty_hash :string, limit: 250, serialize: JSON, null: true, default: {}
-            allow_null :string, limit: 250, serialize: JSON, null: true, default: nil
+      describe 'Hash' do
+        it 'allows serialize: Hash' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              string :allow_list, limit: 250, serialize: Hash, null: true
+            end
           end
-        end
 
-        expect(Ad.field_specs['allow_hash'].default).to eq("{\"state\":\"CA\"}")
-        expect(Ad.field_specs['allow_empty_array'].default).to eq("[]")
-        expect(Ad.field_specs['allow_empty_hash'].default).to eq("{}")
-        expect(Ad.field_specs['allow_null'].default).to eq(nil)
-      end
-    end
+          expect(Ad.serialize_args).to eq([[:allow_list, Hash]])
+        end
 
-    class ValueClass
-      delegate :present?, :inspect, to: :@value
+        it 'allows Hash defaults' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              string :allow_loc, limit: 250, serialize: Hash, null: true, default: { 'state' => 'CA' }
+              string :allow_hash, limit: 250, serialize: Hash, null: true, default: {}
+              string :allow_null, limit: 250, serialize: Hash, null: true, default: nil
+            end
+          end
 
-      def initialize(value)
-        @value = value
+          expect(Ad.field_specs['allow_loc'].default).to eq("---\nstate: CA\n")
+          expect(Ad.field_specs['allow_hash'].default).to eq(nil)
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
+        end
       end
 
-      class << self
-        def dump(object)
-          if object&.present?
-            object.inspect
+      describe 'JSON' do
+        it 'allows serialize: JSON' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              string :allow_list, limit: 250, serialize: JSON
+            end
           end
+
+          expect(Ad.serialize_args).to eq([[:allow_list, JSON]])
         end
 
-        def load(serialized)
-          if serialized
-            raise 'not used ???'
+        it 'allows JSON defaults' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              string :allow_hash, limit: 250, serialize: JSON, null: true, default: { 'state' => 'CA' }
+              string :allow_empty_array, limit: 250, serialize: JSON, null: true, default: []
+              string :allow_empty_hash, limit: 250, serialize: JSON, null: true, default: {}
+              string :allow_null, limit: 250, serialize: JSON, null: true, default: nil
+            end
           end
+
+          expect(Ad.field_specs['allow_hash'].default).to eq("{\"state\":\"CA\"}")
+          expect(Ad.field_specs['allow_empty_array'].default).to eq("[]")
+          expect(Ad.field_specs['allow_empty_hash'].default).to eq("{}")
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
         end
       end
-    end
 
-    describe 'custom coder' do
-      it 'allows serialize: ValueClass' do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_list :string, limit: 250, serialize: ValueClass
-          end
+      class ValueClass
+        delegate :present?, :inspect, to: :@value
+
+        def initialize(value)
+          @value = value
         end
 
-        expect(Ad.serialize_args).to eq([[:allow_list, ValueClass]])
-      end
+        class << self
+          def dump(object)
+            if object&.present?
+              object.inspect
+            end
+          end
 
-      it 'allows ValueClass defaults' do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_hash :string, limit: 250, serialize: ValueClass, null: true, default: ValueClass.new([2])
-            allow_empty_array :string, limit: 250, serialize: ValueClass, null: true, default: ValueClass.new([])
-            allow_null :string, limit: 250, serialize: ValueClass, null: true, default: nil
+          def load(serialized)
+            if serialized
+              raise 'not used ???'
+            end
           end
         end
-
-        expect(Ad.field_specs['allow_hash'].default).to eq("[2]")
-        expect(Ad.field_specs['allow_empty_array'].default).to eq(nil)
-        expect(Ad.field_specs['allow_null'].default).to eq(nil)
       end
-    end
 
-    it 'disallows serialize: with a non-string column type' do
-      expect do
-        class Ad < ActiveRecord::Base
-          fields do
-            allow_list :integer, limit: 8, serialize: true
+      describe 'custom coder' do
+        it 'allows serialize: ValueClass' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              string :allow_list, limit: 250, serialize: ValueClass
+            end
           end
-        end
-      end.to raise_exception(ArgumentError, /must be :string or :text/)
-    end
-  end
 
-  context "for Rails #{Rails::VERSION::MAJOR}" do
-    if Rails::VERSION::MAJOR >= 5
-      let(:optional_true) { { optional: true } }
-      let(:optional_false) { { optional: false } }
-    else
-      let(:optional_true) { {} }
-      let(:optional_false) { {} }
-    end
-    let(:optional_flag) { { false => optional_false, true => optional_true } }
+          expect(Ad.serialize_args).to eq([[:allow_list, ValueClass]])
+        end
 
-    describe 'belongs_to' do
-      before do
-        unless defined?(AdCategory)
-          class AdCategory < ActiveRecord::Base
-            fields { }
+        it 'allows ValueClass defaults' do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              string :allow_hash, limit: 250, serialize: ValueClass, null: true, default: ValueClass.new([2])
+              string :allow_empty_array, limit: 250, serialize: ValueClass, null: true, default: ValueClass.new([])
+              string :allow_null, limit: 250, serialize: ValueClass, null: true, default: nil
+            end
           end
+
+          expect(Ad.field_specs['allow_hash'].default).to eq("[2]")
+          expect(Ad.field_specs['allow_empty_array'].default).to eq(nil)
+          expect(Ad.field_specs['allow_null'].default).to eq(nil)
         end
+      end
 
-        class Advert < ActiveRecord::Base
-          fields do
-            name :string, limit: 250, null: true
-            category_id :integer, limit: 8
-            nullable_category_id :integer, limit: 8, null: true
+      it 'disallows serialize: with a non-string column type' do
+        expect do
+          class Ad < ActiveRecord::Base
+            declare_schema do
+              integer :allow_list, limit: 8, serialize: true
+            end
           end
-        end
-        up = Generators::DeclareSchema::Migration::Migrator.run.first
-        ActiveRecord::Migration.class_eval(up)
+        end.to raise_exception(ArgumentError, /must be :string or :text/)
       end
+    end
 
-      it 'passes through optional: when given' do
-        class AdvertBelongsTo < ActiveRecord::Base
-          self.table_name = 'adverts'
-          fields { }
-          reset_column_information
-          belongs_to :ad_category, optional: true
-        end
-        expect(AdvertBelongsTo.reflections['ad_category'].options).to eq(optional_true)
+    context "for Rails #{Rails::VERSION::MAJOR}" do
+      if Rails::VERSION::MAJOR >= 5
+        let(:optional_true) { { optional: true } }
+        let(:optional_false) { { optional: false } }
+      else
+        let(:optional_true) { {} }
+        let(:optional_false) { {} }
       end
+      let(:optional_flag) { { false => optional_false, true => optional_true } }
+
+      describe 'belongs_to' do
+        before do
+          unless defined?(AdCategory)
+            class AdCategory < ActiveRecord::Base
+              declare_schema { }
+            end
+          end
 
-      describe 'contradictory settings' do # contradictory settings are ok--for example, during migration
-        it 'passes through optional: true, null: false' do
-          class AdvertBelongsTo < ActiveRecord::Base
-            self.table_name = 'adverts'
-            fields { }
-            reset_column_information
-            belongs_to :ad_category, optional: true, null: false
+          class Advert < ActiveRecord::Base
+            declare_schema do
+              string :name, limit: 250, null: true
+              integer :category_id, limit: 8
+              integer :nullable_category_id, limit: 8, null: true
+            end
           end
-          expect(AdvertBelongsTo.reflections['ad_category'].options).to eq(optional_true)
-          expect(AdvertBelongsTo.field_specs['ad_category_id'].options&.[](:null)).to eq(false)
+          up = Generators::DeclareSchema::Migration::Migrator.run.first
+          ActiveRecord::Migration.class_eval(up)
         end
 
-        it 'passes through optional: false, null: true' do
+        it 'passes through optional: when given' do
           class AdvertBelongsTo < ActiveRecord::Base
             self.table_name = 'adverts'
-            fields { }
+            declare_schema { }
             reset_column_information
-            belongs_to :ad_category, optional: false, null: true
+            belongs_to :ad_category, optional: 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.reflections['ad_category'].options).to eq(optional_true)
         end
-      end
 
-      [false, true].each do |nullable|
-        context "nullable=#{nullable}" do
-          it 'infers optional: from null:' do
-            eval <<~EOS
-              class AdvertBelongsTo < ActiveRecord::Base
-                fields { }
-                belongs_to :ad_category, null: #{nullable}
-              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)
+        describe 'contradictory settings' do # contradictory settings are ok--for example, during migration
+          it 'passes through optional: true, null: false' do
+            class AdvertBelongsTo < ActiveRecord::Base
+              self.table_name = 'adverts'
+              declare_schema { }
+              reset_column_information
+              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)
           end
 
-          it 'infers null: from optional:' do
-            eval <<~EOS
-              class AdvertBelongsTo < ActiveRecord::Base
-                fields { }
-                belongs_to :ad_category, optional: #{nullable}
-              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)
+          it 'passes through optional: false, null: true' do
+            class AdvertBelongsTo < ActiveRecord::Base
+              self.table_name = 'adverts'
+              declare_schema { }
+              reset_column_information
+              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)
           end
         end
-      end
-    end
-  end
 
-  describe 'migration base class' do
-    it 'adapts to Rails 4' do
-      class Advert < active_record_base_class.constantize
-        fields do
-          title :string, limit: 100
+        [false, true].each do |nullable|
+          context "nullable=#{nullable}" do
+            it 'infers optional: from null:' do
+              eval <<~EOS
+                class AdvertBelongsTo < ActiveRecord::Base
+                  declare_schema { }
+                  belongs_to :ad_category, null: #{nullable}
+                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)
+            end
+
+            it 'infers null: from optional:' do
+              eval <<~EOS
+                class AdvertBelongsTo < ActiveRecord::Base
+                  declare_schema { }
+                  belongs_to :ad_category, optional: #{nullable}
+                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)
+            end
+          end
         end
       end
-
-      generate_migrations '-n', '-m'
-
-      migrations = Dir.glob('db/migrate/*declare_schema_migration*.rb')
-      expect(migrations.size).to eq(1), migrations.inspect
-
-      migration_content = File.read(migrations.first)
-      first_line = migration_content.split("\n").first
-      base_class = first_line.split(' < ').last
-      expect(base_class).to eq("(Rails::VERSION::MAJOR >= 5 ? ActiveRecord::Migration[4.2] : ActiveRecord::Migration)")
     end
-  end
 
-  context 'Does not generate migrations' do
-    it 'for aliased fields bigint -> integer limit 8' do
-      if Rails::VERSION::MAJOR >= 5 || !ActiveRecord::Base.connection.class.name.match?(/SQLite3Adapter/)
+    describe 'migration base class' do
+      it 'adapts to Rails 4' do
         class Advert < active_record_base_class.constantize
-          fields do
-            price :bigint
+          declare_schema do
+            string :title, limit: 100
           end
         end
 
@@ -1210,17 +2234,39 @@ RSpec.describe 'DeclareSchema Migration Generator' do
         migrations = Dir.glob('db/migrate/*declare_schema_migration*.rb')
         expect(migrations.size).to eq(1), migrations.inspect
 
-        if defined?(Mysql2) && Rails::VERSION::MAJOR < 5
-          ActiveRecord::Base.connection.execute("ALTER TABLE adverts ADD PRIMARY KEY (id)")
-        end
+        migration_content = File.read(migrations.first)
+        first_line = migration_content.split("\n").first
+        base_class = first_line.split(' < ').last
+        expect(base_class).to eq("(Rails::VERSION::MAJOR >= 5 ? ActiveRecord::Migration[4.2] : ActiveRecord::Migration)")
+      end
+    end
 
-        class Advert < active_record_base_class.constantize
-          fields do
-            price :integer, limit: 8
+    context 'Does not generate migrations' do
+      it 'for aliased fields bigint -> integer limit 8' do
+        if Rails::VERSION::MAJOR >= 5 || !ActiveRecord::Base.connection.class.name.match?(/SQLite3Adapter/)
+          class Advert < active_record_base_class.constantize
+            declare_schema do
+              bigint :price
+            end
+          end
+
+          generate_migrations '-n', '-m'
+
+          migrations = Dir.glob('db/migrate/*declare_schema_migration*.rb')
+          expect(migrations.size).to eq(1), migrations.inspect
+
+          if defined?(Mysql2) && Rails::VERSION::MAJOR < 5
+            ActiveRecord::Base.connection.execute("ALTER TABLE adverts ADD PRIMARY KEY (id)")
+          end
+
+          class Advert < active_record_base_class.constantize
+            declare_schema do
+              integer :price, limit: 8
+            end
           end
-        end
 
-        expect { generate_migrations '-n', '-g' }.to output("Database and models match -- nothing to change\n").to_stdout
+          expect { generate_migrations '-n', '-g' }.to output("Database and models match -- nothing to change\n").to_stdout
+        end
       end
     end
   end