declare_schema 0.1.3 → 0.3.0

data/lib/generators/declare_schema/migration/templates/migration.rb.erb

@@ -1,4 +1,4 @@
-class <%= @migration_class_name %> < ActiveRecord::Migration<%= Rails::VERSION::MAJOR > 4 ? '[4.2]' : '' %>
+class <%= @migration_class_name %> < (Rails::VERSION::MAJOR >= 5 ? ActiveRecord::Migration[4.2] : ActiveRecord::Migration)
   def self.up
     <%= @up %>
   end

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

@@ -9,9 +9,18 @@ module DeclareSchema
             private
 
             def eval_template(template_name)
-              source  = File.expand_path(find_in_source_paths(template_name))
-              context = instance_eval('binding')
-              ERB.new(::File.binread(source), trim_mode: '-').result(context)
+              source = File.expand_path(find_in_source_paths(template_name))
+              erb = ERB.new(::File.read(source).force_encoding(Encoding::UTF_8), trim_mode: '>')
+              erb.filename = source
+              begin
+                erb.result(binding)
+              rescue Exception => ex
+                raise ex.class, <<~EOS
+                  #{ex.message}
+                  #{erb.src}
+                    #{ex.backtrace.join("\n  ")}
+                EOS
+              end
             end
           end
         end

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

@@ -4,6 +4,39 @@ require_relative './eval_template'
 
 module DeclareSchema
   module Support
+    class IndentedBuffer
+      def initialize(indent: 0)
+        @string = +""
+        @indent = indent
+        @column = 0
+        @indent_amount = 2
+      end
+
+      def to_string
+        @string
+      end
+
+      def indent!
+        @indent += @indent_amount
+        yield
+        @indent -= @indent_amount
+      end
+
+      def newline!
+        @column = 0
+        @string << "\n"
+      end
+
+      def <<(str)
+        if (difference = @indent - @column) > 0
+          @string << ' ' * difference
+        end
+        @column += difference
+        @string << str
+        newline!
+      end
+    end
+
     module Model
       class << self
         def included(base)
@@ -26,9 +59,51 @@ module DeclareSchema
 
             def inject_declare_schema_code_into_model_file
               gsub_file(model_path, /  # attr_accessible :title, :body\n/m, "")
-              inject_into_class model_path, class_name do
-                eval_template('model_injection.rb.erb')
+              inject_into_class(model_path, class_name) do
+                declare_model_fields_and_associations
+              end
+            end
+
+            private
+
+            def declare_model_fields_and_associations
+              buffer = ::DeclareSchema::Support::IndentedBuffer.new(indent: 2)
+              buffer.newline!
+              buffer << 'fields do'
+              buffer.indent! do
+                field_attributes.each do |attribute|
+                  decl = "%-#{max_attribute_length}s" % attribute.name + ' ' +
+                    attribute.type.to_sym.inspect +
+                    case attribute.type.to_s
+                    when 'string'
+                      ', limit: 255'
+                    else
+                      ''
+                    end
+                  buffer << decl
+                end
+                if options[:timestamps]
+                  buffer.newline!
+                  buffer << 'timestamps'
+                end
+              end
+              buffer << 'end'
+
+              if bts.any?
+                buffer.newline!
+                bts.each do |bt|
+                  buffer << "belongs_to #{bt.to_sym.inspect}"
+                end
               end
+              if hms.any?
+                buffer.newline
+                hms.each do |hm|
+                  buffer << "has_many #{hm.to_sym.inspect}, dependent: :destroy"
+                end
+              end
+              buffer.newline!
+
+              buffer.to_string
             end
 
             protected

data/spec/lib/declare_schema/api_spec.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'rails'
+require 'rails/generators'
+
+RSpec.describe 'DeclareSchema API' do
+  before do
+    load File.expand_path('prepare_testapp.rb', __dir__)
+  end
+
+  describe 'example models' do
+    it 'generates a model' do
+      expect(system("bundle exec rails generate declare_schema:model advert title:string body:text")).to be_truthy
+
+      # The above will generate the test, fixture and a model file like this:
+      # model_declaration = Rails::Generators.invoke('declare_schema:model', ['advert2', 'title:string', 'body:text'])
+      # expect(model_declaration.first).to eq([["Advert"], nil, "app/models/advert.rb", nil,
+      #                                       [["AdvertTest"], "test/models/advert_test.rb", nil, "test/fixtures/adverts.yml"]])
+
+      expect(File.read("#{TESTAPP_PATH}/app/models/advert.rb")).to eq(<<~EOS)
+        class Advert < #{active_record_base_class}
+
+          fields do
+            title :string, limit: 255
+            body  :text
+          end
+
+        end
+      EOS
+      system("rm -rf #{TESTAPP_PATH}/app/models/advert2.rb #{TESTAPP_PATH}/test/models/advert2.rb #{TESTAPP_PATH}/test/fixtures/advert2.rb")
+
+      # The migration generator uses this information to create a migration.
+      # The following creates and runs the migration:
+
+      expect(system("bundle exec rails generate declare_schema:migration -n -m")).to be_truthy
+
+      # We're now ready to start demonstrating the API
+
+      Rails.application.config.autoload_paths += ["#{TESTAPP_PATH}/app/models"]
+
+      $LOAD_PATH << "#{TESTAPP_PATH}/app/models"
+
+      unless Rails::VERSION::MAJOR >= 6
+        # TODO: get this to work on Travis for Rails 6
+        Rails::Generators.invoke('declare_schema:migration', %w[-n -m])
+      end
+
+      require 'advert'
+
+      ## The Basics
+
+      # The main feature of DeclareSchema, aside from the migration generator, is the ability to declare rich types for your fields. For example, you can declare that a field is an email address, and the field will be automatically validated for correct email address syntax.
+
+      ### Field Types
+
+      # Field values are returned as the type you specify.
+
+      Advert.destroy_all
+
+      a = Advert.new(body: "This is the body", id: 1, title: "title")
+      expect(a.body).to eq("This is the body")
+
+      # This also works after a round-trip to the database
+
+      a.save!
+      expect(a.reload.body).to eq("This is the body")
+
+      ## Names vs. Classes
+
+      ## Model extensions
+
+      # DeclareSchema adds a few features to your models.
+
+      ### `Model.attr_type`
+
+      # Returns the type (i.e. class) declared for a given field or attribute
+
+      Advert.connection.schema_cache.clear!
+      Advert.reset_column_information
+
+      expect(Advert.attr_type(:title)).to eq(String)
+      expect(Advert.attr_type(:body)).to eq(String)
+
+      ## Field validations
+
+      # DeclareSchema gives you some shorthands for declaring some common validations right in the field declaration
+
+      ### Required fields
+
+      # The `:required` argument to a field gives a `validates_presence_of`:
+
+      class AdvertWithRequiredTitle < ActiveRecord::Base
+        self.table_name = 'adverts'
+
+        fields do
+          title :string, :required, limit: 255
+        end
+      end
+
+      a = AdvertWithRequiredTitle.new
+      expect(a.valid? || a.errors.full_messages).to eq(["Title can't be blank"])
+      a.id = 2
+      a.body = "hello"
+      a.title = "Jimbo"
+      a.save!
+
+      ### Unique fields
+
+      # The `:unique` argument in a field declaration gives `validates_uniqueness_of`:
+
+      class AdvertWithUniqueTitle < ActiveRecord::Base
+        self.table_name = 'adverts'
+
+        fields do
+          title :string, :unique, limit: 255
+        end
+      end
+
+      a = AdvertWithUniqueTitle.new :title => "Jimbo", id: 3, body: "hello"
+      expect(a.valid? || a.errors.full_messages).to eq(["Title has already been taken"])
+      a.title = "Sambo"
+      a.save!
+    end
+  end
+end

data/spec/lib/declare_schema/field_declaration_dsl_spec.rb

@@ -3,11 +3,15 @@
 require_relative '../../../lib/declare_schema/field_declaration_dsl'
 
 RSpec.describe DeclareSchema::FieldDeclarationDsl do
-  class TestModel < ActiveRecord::Base
-    fields do
-      name :string, limit: 127
+  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
 

data/spec/lib/declare_schema/generator_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+RSpec.describe 'DeclareSchema Migration Generator' do
+  before do
+    load File.expand_path('prepare_testapp.rb', __dir__)
+  end
+
+  it "generates nested models" do
+    Rails::Generators.invoke('declare_schema:model', %w[alpha/beta one:string two:integer])
+
+    expect(File.exist?('app/models/alpha/beta.rb')).to be_truthy
+
+    expect(File.read('app/models/alpha/beta.rb')).to eq(<<~EOS)
+      class Alpha::Beta < #{active_record_base_class}
+  
+        fields do
+          one :string, limit: 255
+          two :integer
+        end
+  
+      end
+    EOS
+
+    expect(File.read('app/models/alpha.rb')).to eq(<<~EOS)
+      module Alpha
+        def self.table_name_prefix
+          'alpha_'
+        end
+      end
+    EOS
+
+    expect(File.read('test/models/alpha/beta_test.rb')).to eq(<<~EOS)
+      require 'test_helper'
+      
+      class Alpha::BetaTest < ActiveSupport::TestCase
+        # test "the truth" do
+        #   assert true
+        # end
+      end
+    EOS
+
+    expect(File.exist?('test/fixtures/alpha/beta.yml')).to be_truthy
+
+    $LOAD_PATH << "#{TESTAPP_PATH}/app/models"
+
+    expect(system("bundle exec rails generate declare_schema:migration -n -m")).to be_truthy
+
+    expect(File.exist?('db/schema.rb')).to be_truthy
+
+    expect(File.exist?("db/development.sqlite3") || File.exist?("db/test.sqlite3")).to be_truthy
+
+    module Alpha; end
+    require 'alpha/beta'
+
+    expect { Alpha::Beta }.to_not raise_exception
+  end
+end

data/spec/lib/declare_schema/interactive_primary_key_spec.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+RSpec.describe 'DeclareSchema Migration Generator interactive primary key' do
+  before do
+    load File.expand_path('prepare_testapp.rb', __dir__)
+  end
+
+  it "allows alternate primary keys" do
+    class Foo < ActiveRecord::Base
+      fields do
+      end
+      self.primary_key = "foo_id"
+    end
+
+    Rails::Generators.invoke('declare_schema:migration', %w[-n -m])
+    expect(Foo.primary_key).to eq('foo_id')
+
+    ### migrate from
+    # rename from custom primary_key
+    class Foo < ActiveRecord::Base
+      fields do
+      end
+      self.primary_key = "id"
+    end
+
+    puts "\n\e[45m Please enter 'id' (no quotes) at the next prompt \e[0m"
+    Rails::Generators.invoke('declare_schema:migration', %w[-n -m])
+    expect(Foo.primary_key).to eq('id')
+
+    nuke_model_class(Foo)
+
+    ### migrate to
+
+    # rename to custom primary_key
+    class Foo < ActiveRecord::Base
+      fields do
+      end
+      self.primary_key = "foo_id"
+    end
+
+    puts "\n\e[45m Please enter 'drop id' (no quotes) at the next prompt \e[0m"
+    Rails::Generators.invoke('declare_schema:migration', %w[-n -m])
+    expect(Foo.primary_key).to eq('foo_id')
+
+    ### ensure it doesn't cause further migrations
+
+    # check no further migrations
+    up, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up).to eq("")
+  end
+end

data/spec/lib/declare_schema/migration_generator_spec.rb

@@ -0,0 +1,795 @@
+# frozen_string_literal: true
+
+require 'rails'
+
+RSpec.describe 'DeclareSchema Migration Generator' do
+  before do
+    load File.expand_path('prepare_testapp.rb', __dir__)
+  end
+
+  # DeclareSchema - Migration Generator
+  it 'generates migrations' do
+    ## The migration generator -- introduction
+
+    up_down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up_down).to eq(["", ""])
+
+    class Advert < ActiveRecord::Base
+    end
+
+    up_down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up_down).to eq(["", ""])
+
+    Generators::DeclareSchema::Migration::Migrator.ignore_tables = ["green_fishes"]
+
+    Advert.connection.schema_cache.clear!
+    Advert.reset_column_information
+
+    class Advert < ActiveRecord::Base
+      fields do
+        name :string, limit: 255, null: true
+      end
+    end
+    up, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up).to eq(<<~EOS.strip)
+      create_table :adverts, id: :bigint do |t|
+        t.string :name, limit: 255
+      end
+    EOS
+    expect(down).to eq("drop_table :adverts")
+
+    ActiveRecord::Migration.class_eval(up)
+    expect(Advert.columns.map(&:name)).to eq(["id", "name"])
+
+    class Advert < ActiveRecord::Base
+      fields do
+        name :string, limit: 255, null: true
+        body :text, null: true
+        published_at :datetime, null: true
+      end
+    end
+    up, down = migrate
+    expect(up).to eq(<<~EOS.strip)
+      add_column :adverts, :body, :text
+      add_column :adverts, :published_at, :datetime
+
+      add_index :adverts, [:id], unique: true, name: 'PRIMARY_KEY'
+    EOS
+    # TODO: ^ TECH-4975 add_index should not be there
+
+    expect(down).to eq(<<~EOS.strip)
+      remove_column :adverts, :body
+      remove_column :adverts, :published_at
+    EOS
+
+    Advert.field_specs.clear # not normally needed
+    class Advert < ActiveRecord::Base
+      fields do
+        name :string, limit: 255, null: true
+        body :text, null: true
+      end
+    end
+
+    up, down = migrate
+    expect(up).to eq("remove_column :adverts, :published_at")
+    expect(down).to eq("add_column :adverts, :published_at, :datetime")
+
+    nuke_model_class(Advert)
+    class Advert < ActiveRecord::Base
+      fields do
+        title :string, limit: 255, null: true
+        body :text, null: true
+      end
+    end
+
+    up, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up).to eq(<<~EOS.strip)
+      add_column :adverts, :title, :string, limit: 255
+      remove_column :adverts, :name
+    EOS
+
+    expect(down).to eq(<<~EOS.strip)
+      remove_column :adverts, :title
+      add_column :adverts, :name, :string, limit: 255
+    EOS
+
+    up, down = Generators::DeclareSchema::Migration::Migrator.run(adverts: { name: :title })
+    expect(up).to eq("rename_column :adverts, :name, :title")
+    expect(down).to eq("rename_column :adverts, :title, :name")
+
+    migrate
+
+    class Advert < ActiveRecord::Base
+      fields do
+        title :text, null: true
+        body :text, null: true
+      end
+    end
+
+    up_down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up_down).to eq(["change_column :adverts, :title, :text",
+                           "change_column :adverts, :title, :string, limit: 255"])
+
+    class Advert < ActiveRecord::Base
+      fields do
+        title :string, default: "Untitled", limit: 255, null: true
+        body :text, null: true
+      end
+    end
+
+    up, down = migrate
+    expect(up.split(',').slice(0,3).join(',')).to eq('change_column :adverts, :title, :string')
+    expect(up.split(',').slice(3,2).sort.join(',')).to eq(" default: \"Untitled\", limit: 255")
+    expect(down).to eq("change_column :adverts, :title, :string, limit: 255")
+
+
+    ### Limits
+
+    class Advert < ActiveRecord::Base
+      fields do
+        price :integer, null: true, limit: 2
+      end
+    end
+
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up).to eq("add_column :adverts, :price, :integer, limit: 2")
+
+    # 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
+      end
+    end
+
+    up, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up).to eq("change_column :adverts, :price, :integer, limit: 3")
+    expect(down).to eq("change_column :adverts, :price, :integer, limit: 2")
+
+    # Note that limit on a decimal column is ignored (use :scale and :precision)
+
+    ActiveRecord::Migration.class_eval("remove_column :adverts, :price")
+    class Advert < ActiveRecord::Base
+      fields do
+        price :decimal, null: true, limit: 4
+      end
+    end
+
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up).to eq("add_column :adverts, :price, :decimal")
+
+    # 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).
+
+    expect(::DeclareSchema::Model::FieldSpec.mysql_text_limits?).to be_falsey
+    class Advert < ActiveRecord::Base
+      fields do
+        notes :text
+        description :text, limit: 30000
+      end
+    end
+
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up).to eq(<<~EOS.strip)
+      add_column :adverts, :price, :decimal
+      add_column :adverts, :notes, :text, null: false
+      add_column :adverts, :description, :text, null: false
+    EOS
+
+    # (There is no limit on `add_column ... :description` above since these tests are run against SQLite.)
+
+    Advert.field_specs.delete :price
+    Advert.field_specs.delete :notes
+    Advert.field_specs.delete :description
+
+    # In MySQL, limits are applied, rounded up:
+
+    ::DeclareSchema::Model::FieldSpec::instance_variable_set(:@mysql_text_limits, true)
+    expect(::DeclareSchema::Model::FieldSpec.mysql_text_limits?).to be_truthy
+    class Advert < ActiveRecord::Base
+      fields do
+        notes :text
+        description :text, limit: 200
+      end
+    end
+
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up).to eq(<<~EOS.strip)
+      add_column :adverts, :notes, :text, null: false, limit: 4294967295
+      add_column :adverts, :description, :text, null: false, limit: 255
+    EOS
+
+    Advert.field_specs.delete :notes
+
+    # Limits that are too high for MySQL will raise an exception.
+
+    ::DeclareSchema::Model::FieldSpec::instance_variable_set(:@mysql_text_limits, true)
+    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
+        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 255.
+
+    expect(::DeclareSchema::Model::FieldSpec.mysql_text_limits?).to be_truthy
+    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
+
+    up, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up).to eq("change_column :adverts, :description, :text, limit: 4294967295, null: false")
+    expect(down).to eq("change_column :adverts, :description, :text")
+
+    # TODO TECH-4814: The above test should have this output:
+    # TODO => "change_column :adverts, :description, :text, limit: 255
+
+    # 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
+
+    up, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up).to eq("change_column :adverts, :description, :text, limit: 4294967295, null: false")
+    expect(down).to eq("change_column :adverts, :description, :text")
+    ::DeclareSchema::Model::FieldSpec::instance_variable_set(:@mysql_text_limits, false)
+
+    Advert.field_specs.clear
+    Advert.connection.schema_cache.clear!
+    Advert.reset_column_information
+    class Advert < ActiveRecord::Base
+      fields do
+        name :string, limit: 255, 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
+      fields do
+        name :string, limit: 255, null: true
+      end
+      belongs_to :category
+    end
+
+    up, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :category_id, :integer, limit: 8, null: false
+      add_index :adverts, [:category_id], name: 'on_category_id'
+    EOS
+    expect(down.sub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      remove_column :adverts, :category_id
+      remove_index :adverts, name: :on_category_id rescue ActiveRecord::StatementInvalid
+    EOS
+
+    Advert.field_specs.delete(:category_id)
+    Advert.index_specs.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 { }
+      belongs_to :category, foreign_key: "c_id", class_name: 'Category'
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :c_id, :integer, limit: 8, null: false
+      add_index :adverts, [:c_id], name: 'on_c_id'
+    EOS
+
+    Advert.field_specs.delete(:c_id)
+    Advert.index_specs.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
+      fields { }
+      belongs_to :category, index: false
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up.gsub(/\n+/, "\n")).to eq("add_column :adverts, :category_id, :integer, limit: 8, null: false")
+
+    Advert.field_specs.delete(:category_id)
+    Advert.index_specs.delete_if { |spec| spec.fields == ["category_id"] }
+
+    # You can specify the index name with :index
+
+    class Category < ActiveRecord::Base; end
+    class Advert < ActiveRecord::Base
+      fields { }
+      belongs_to :category, index: 'my_index'
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :category_id, :integer, limit: 8, null: false
+      add_index :adverts, [:category_id], name: 'my_index'
+    EOS
+
+    Advert.field_specs.delete(:category_id)
+    Advert.index_specs.delete_if { |spec| spec.fields == ["category_id"] }
+
+    ### Timestamps and Optimimistic Locking
+
+    # `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
+      fields do
+        timestamps
+        optimistic_lock
+      end
+    end
+    up, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :created_at, :datetime
+      add_column :adverts, :updated_at, :datetime
+      add_column :adverts, :lock_version, :integer, null: false, default: 1
+    EOS
+    expect(down.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      remove_column :adverts, :created_at
+      remove_column :adverts, :updated_at
+      remove_column :adverts, :lock_version
+    EOS
+
+    Advert.field_specs.delete(:updated_at)
+    Advert.field_specs.delete(:created_at)
+    Advert.field_specs.delete(:lock_version)
+
+    ### Indices
+
+    # You can add an index to a field definition
+
+    class Advert < ActiveRecord::Base
+      fields do
+        title :string, index: true, limit: 255, null: true
+      end
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :title, :string, limit: 255
+      add_index :adverts, [:title], name: 'on_title'
+    EOS
+
+    Advert.index_specs.delete_if { |spec| spec.fields==["title"] }
+
+    # You can ask for a unique index
+
+    class Advert < ActiveRecord::Base
+      fields do
+        title :string, index: true, unique: true, null: true, limit: 255
+      end
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :title, :string, limit: 255
+      add_index :adverts, [:title], unique: true, name: 'on_title'
+    EOS
+
+    Advert.index_specs.delete_if { |spec| spec.fields == ["title"] }
+
+    # You can specify the name for the index
+
+    class Advert < ActiveRecord::Base
+      fields do
+        title :string, index: 'my_index', limit: 255, null: true
+      end
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :title, :string, limit: 255
+      add_index :adverts, [:title], name: 'my_index'
+    EOS
+
+    Advert.index_specs.delete_if { |spec| spec.fields==["title"] }
+
+    # You can ask for an index outside of the fields block
+
+    class Advert < ActiveRecord::Base
+      index :title
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :title, :string, limit: 255
+      add_index :adverts, [:title], name: 'on_title'
+    EOS
+
+    Advert.index_specs.delete_if { |spec| spec.fields == ["title"] }
+
+    # The available options for the index function are `:unique` and `:name`
+
+    class Advert < ActiveRecord::Base
+      index :title, unique: true, name: 'my_index'
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :title, :string, limit: 255
+      add_index :adverts, [:title], unique: true, name: 'my_index'
+    EOS
+
+    Advert.index_specs.delete_if { |spec| spec.fields == ["title"] }
+
+    # You can create an index on more than one field
+
+    class Advert < ActiveRecord::Base
+      index [:title, :category_id]
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run.first
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :title, :string, limit: 255
+      add_index :adverts, [:title, :category_id], name: 'on_title_and_category_id'
+    EOS
+
+    Advert.index_specs.delete_if { |spec| spec.fields==["title", "category_id"] }
+
+    # Finally, you can specify that the migration generator should completely ignore an
+    # index by passing its name to ignore_index in the model.
+    # This is helpful for preserving indices that can't be automatically generated, such as prefix indices in MySQL.
+
+    ### 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"
+      fields do
+        title :string, limit: 255, null: true
+        body :text, null: true
+      end
+    end
+
+    Advert.connection.schema_cache.clear!
+    Advert.reset_column_information
+
+    up, down = Generators::DeclareSchema::Migration::Migrator.run("adverts" => "ads")
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      rename_table :adverts, :ads
+      add_column :ads, :title, :string, limit: 255
+      add_column :ads, :body, :text
+      add_index :ads, [:id], unique: true, name: 'PRIMARY_KEY'
+    EOS
+    expect(down.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      remove_column :ads, :title
+      remove_column :ads, :body
+      rename_table :ads, :adverts
+      add_index :adverts, [:id], unique: true, name: 'PRIMARY_KEY'
+    EOS
+
+    # Set the table name back to what it should be and confirm we're in sync:
+
+    Advert.field_specs.delete(:title)
+    Advert.field_specs.delete(:body)
+    class Advert < ActiveRecord::Base
+      self.table_name = "adverts"
+    end
+
+    expect(Generators::DeclareSchema::Migration::Migrator.run).to eq(["", ""])
+
+    ### 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.
+
+    nuke_model_class(Advert)
+
+    class Advertisement < ActiveRecord::Base
+      fields do
+        title :string, limit: 255, null: true
+        body :text, null: true
+      end
+    end
+    up, down = Generators::DeclareSchema::Migration::Migrator.run("adverts" => "advertisements")
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      rename_table :adverts, :advertisements
+      add_column :advertisements, :title, :string, limit: 255
+      add_column :advertisements, :body, :text
+      remove_column :advertisements, :name
+      add_index :advertisements, [:id], unique: true, name: 'PRIMARY_KEY'
+    EOS
+    expect(down.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      remove_column :advertisements, :title
+      remove_column :advertisements, :body
+      add_column :adverts, :name, :string, limit: 255
+      rename_table :advertisements, :adverts
+      add_index :adverts, [:id], unique: true, name: 'PRIMARY_KEY'
+    EOS
+
+    ### Drop a table
+
+    nuke_model_class(Advertisement)
+
+    # If you delete a model, the migration generator will create a `drop_table` migration.
+
+    # Dropping tables is where the automatic down-migration really comes in handy:
+
+    up, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up).to eq("drop_table :adverts")
+    expect(down.gsub(/,.*/m, '')).to eq("create_table \"adverts\"")
+
+    ## 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: 255, 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, down = Generators::DeclareSchema::Migration::Migrator.run
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      add_column :adverts, :type, :string, limit: 255
+      add_index :adverts, [:type], name: 'on_type'
+    EOS
+    expect(down.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      remove_column :adverts, :type
+      remove_index :adverts, name: :on_type rescue ActiveRecord::StatementInvalid
+    EOS
+
+    Advert.field_specs.delete(:type)
+    nuke_model_class(SuperFancyAdvert)
+    nuke_model_class(FancyAdvert)
+    Advert.index_specs.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: 255, null: true
+        body :text, null: true
+      end
+    end
+    up, down = Generators::DeclareSchema::Migration::Migrator.run(adverts: { title: :name })
+    expect(up).to eq(<<~EOS.strip)
+      rename_column :adverts, :title, :name
+      change_column :adverts, :name, :string, limit: 255, default: \"No Name\"
+    EOS
+
+    expect(down).to eq(<<~EOS.strip)
+      rename_column :adverts, :name, :title
+      change_column :adverts, :title, :string, limit: 255, default: \"Untitled\"
+    EOS
+
+    ### Rename a table and add a column
+
+    nuke_model_class(Advert)
+    class Ad < ActiveRecord::Base
+      fields do
+        title      :string, default: "Untitled", limit: 255
+        body       :text, null: true
+        created_at :datetime
+      end
+    end
+    up = Generators::DeclareSchema::Migration::Migrator.run(adverts: :ads).first
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      rename_table :adverts, :ads
+      add_column :ads, :created_at, :datetime, null: false
+      change_column :ads, :title, :string, limit: 255, null: false, default: \"Untitled\"
+      add_index :ads, [:id], unique: true, name: 'PRIMARY_KEY'
+    EOS
+
+    class Advert < ActiveRecord::Base
+      fields do
+        body :text, null: true
+        title :string, default: "Untitled", limit: 255, 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
+    up, _down = Generators::DeclareSchema::Migration::Migrator.run(adverts: { id: :advert_id })
+    expect(up.gsub(/\n+/, "\n")).to eq(<<~EOS.strip)
+      rename_column :adverts, :id, :advert_id
+      add_index :adverts, [:advert_id], unique: true, name: 'PRIMARY_KEY'
+    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: 255, 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: 255, 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
+
+  if Rails::VERSION::MAJOR >= 5
+    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: 255, 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 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: 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: 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
+
+      Rails::Generators.invoke('declare_schema:migration', %w[-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
+end