declare_schema 0.1.0

data/test/generators.rdoctest

@@ -0,0 +1,60 @@
+doctest: prepare testapp environment
+doctest_require: 'prepare_testapp'
+
+doctest: generate declare_schema:model
+>> Rails::Generators.invoke 'declare_schema:model', %w(alpha/beta one:string two:integer)
+
+
+doctest: model file exists
+>> File.exist? 'app/models/alpha/beta.rb'
+=> true
+
+doctest: model content matches
+>> File.read 'app/models/alpha/beta.rb'
+=> "class Alpha::Beta < #{Rails::VERSION::MAJOR > 4 ? 'ApplicationRecord' : 'ActiveRecord::Base'}\n\n  fields do\n    one :string, limit: 255\n    two :integer\n  end\n\nend\n"
+
+doctest: module file exists
+>> File.exist? 'app/models/alpha.rb'
+=> true
+
+doctest: module content matches
+>> File.read 'app/models/alpha.rb'
+=> "module Alpha\n  def self.table_name_prefix\n    'alpha_'\n  end\nend\n"
+
+
+doctest: test file exists
+>> File.exist? 'test/models/alpha/beta_test.rb'
+=> true
+
+doctest: test content matches
+>> File.read 'test/models/alpha/beta_test.rb'
+=>
+require 'test_helper'
+
+class Alpha::BetaTest < ActiveSupport::TestCase
+  # test "the truth" do
+  #   assert true
+  # end
+end
+
+doctest: fixture file exists
+>> File.exist? 'test/fixtures/alpha/beta.yml'
+=> true
+
+
+doctest: generate declare_schema:migration
+>> require_relative "#{Rails.root}/app/models/alpha.rb" if Rails::VERSION::MAJOR > 5
+>> require_relative "#{Rails.root}/app/models/alpha/beta.rb" if Rails::VERSION::MAJOR > 5
+>> Rails::Generators.invoke 'declare_schema:migration', %w(-n -m)
+
+doctest: schema.rb file exists
+>> File.exist? 'db/schema.rb'
+=> true
+
+doctest: db file exists
+>> File.exist? 'db/development.sqlite3'
+=> true
+
+doctest: Alpha::Beta class exists
+>> Alpha::Beta
+# will error if class doesn't exist

data/test/interactive_primary_key.rdoctest

@@ -0,0 +1,56 @@
+-*- indent-tabs-mode:nil; -*-
+
+# DeclareSchema - Migration Generator
+
+Our test requires to prepare the testapp:
+{.hidden}
+
+    doctest_require: 'prepare_testapp'
+
+{.hidden}
+
+And requires also that you enter the right choice when prompted. OK we're ready to get going.
+
+## Alternate Primary Keys
+
+### create
+   doctest: create table with custom primary_key
+   >>
+    class Foo < ActiveRecord::Base
+      fields do
+      end
+      self.primary_key="foo_id"
+    end
+   >> Rails::Generators.invoke 'declare_schema:migration', %w(-n -m)
+   >> Foo.primary_key
+   => 'foo_id'
+
+### migrate from
+   doctest: rename from custom primary_key
+   >>
+    class Foo < ActiveRecord::Base
+      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)
+   >> Foo.primary_key
+   => 'id'
+
+### migrate to
+
+   doctest: rename to custom primary_key
+   >>
+    class Foo < ActiveRecord::Base
+      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)
+   >> Foo.primary_key
+   => 'foo_id'
+
+### ensure it doesn't cause further migrations
+
+   doctest: check no further migrations
+   >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+   >> up
+   => ""

data/test/migration_generator.rdoctest

@@ -0,0 +1,846 @@
+# DeclareSchema - Migration Generator
+
+Our test requires to prepare the testapp:
+{.hidden}
+
+    doctest_require: 'prepare_testapp'
+
+{.hidden}
+
+## The migration generator -- introduction
+
+The migration generator works by:
+
+ * Loading all of the models in your Rails app
+ * Using the Rails schema-dumper to extract information about the current state of the database.
+ * Calculating the changes that are required to bring the database into sync with your application.
+
+Normally you would run the migration generator as a regular Rails generator. You would type
+
+    $ rails generate declare_schema:migration
+
+in your Rails app, and the migration file would be created in `db/migrate`.
+
+In order to demonstrate the generator in this doctest script however, we'll be using the Ruby API instead. The method `Generators::DeclareSchema::Migration::Migrator.run` returns a pair of strings -- the up migration and the down migration.
+
+At the moment the database is empty and no ActiveRecord models exist, so the generator is going to tell us there is nothing to do.
+
+    >> Generators::DeclareSchema::Migration::Migrator.run
+    => ["", ""]
+
+
+### Models without `fields do` are ignored
+
+The migration generator only takes into account classes that use DeclareSchema, i.e. classes with a `fields do` declaration. Models without this are ignored:
+
+    >> class Advert < ActiveRecord::Base; end
+    >> Generators::DeclareSchema::Migration::Migrator.run
+    => ["", ""]
+
+You can also tell DeclareSchema to ignore additional tables.  You can place this command in your environment.rb or elsewhere:
+
+    >> Generators::DeclareSchema::Migration::Migrator.ignore_tables = ["green_fishes"]
+
+### Create the table
+
+Here we see a simple `create_table` migration along with the `drop_table` down migration
+
+    >>
+     class Advert < ActiveRecord::Base
+       fields do
+         name :string, limit: 255, null: true
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    =>
+     "create_table :adverts do |t|
+       t.string :name
+     end"
+    >> down
+    => "drop_table :adverts"
+
+Normally we would run the generated migration with `rake db:create`. We can achieve the same effect directly in Ruby like this:
+
+    >> ActiveRecord::Migration.class_eval up
+    >> Advert.columns.map(&:name)
+    => ["id", "name"]
+
+We'll define a method to make that easier next time
+
+    >>
+     def migrate(renames={})
+       up, down = Generators::DeclareSchema::Migration::Migrator.run(renames)
+       ActiveRecord::Migration.class_eval(up)
+       ActiveRecord::Base.send(:descendants).each { |model| model.reset_column_information }
+       [up, down]
+     end
+
+We'll have a look at the migration generator in more detail later, first we'll have a look at the extra features DeclareSchema has added to the model.
+
+
+### Add fields
+
+If we add a new field to the model, the migration generator will add it to the database.
+
+    >>
+     class Advert
+       fields do
+         name :string, limit: 255, null: true
+         body :text, null: true
+         published_at :datetime, null: true
+       end
+     end
+    >> up, down = migrate
+    >> up
+    =>
+     "add_column :adverts, :body, :text
+     add_column :adverts, :published_at, :datetime"
+    >> down
+    =>
+     "remove_column :adverts, :body
+     remove_column :adverts, :published_at"
+    >>
+
+### Remove fields
+
+If we remove a field from the model, the migration generator removes the database column. Note that we have to explicitly clear the known fields to achieve this in rdoctest -- in a Rails context you would simply edit the file
+
+    >> 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
+    >> up
+    => "remove_column :adverts, :published_at"
+    >> down
+    => "add_column :adverts, :published_at, :datetime"
+
+### Rename a field
+
+Here we rename the `name` field to `title`. By default the generator sees this as removing `name` and adding `title`.
+
+    >> Advert.field_specs.clear # not normally needed
+     class Advert < ActiveRecord::Base
+       fields do
+         title :string, limit: 255, null: true
+         body :text, null: true
+       end
+     end
+    >> # Just generate - don't run the migration:
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    => "add_column :adverts, :title, :string, limit: 255
+        remove_column :adverts, :name"
+    >> down
+    => "remove_column :adverts, :title
+        add_column :adverts, :name, :string, limit: 255"
+
+When run as a generator, the migration-generator won't make this assumption. Instead it will prompt for user input to resolve the ambiguity. When using the Ruby API, we can ask for a rename instead of an add + drop by passing in a hash:
+
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run(adverts: { name: :title })
+    >> up
+    => "rename_column :adverts, :name, :title"
+    >> down
+    => "rename_column :adverts, :title, :name"
+
+Let's apply that change to the database
+
+    >> migrate
+
+
+### Change a type
+
+    >>
+     class Advert
+       fields do
+         title :text, null: true
+         body :text, null: true
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    => "change_column :adverts, :title, :text"
+    >> down
+    => "change_column :adverts, :title, :string, limit: 255"
+
+
+### Add a default
+
+    >>
+     class Advert
+       fields do
+         title :string, default: "Untitled", limit: 255, null: true
+         body :text, null: true
+       end
+     end
+    >> up, down = migrate
+    >> up.split(',').slice(0,3).join(',')
+    => 'change_column :adverts, :title, :string'
+    >> up.split(',').slice(3,2).sort.join(',')
+    => " default: \"Untitled\", limit: 255"
+    >> down
+    => "change_column :adverts, :title, :string, limit: 255"
+
+
+### Limits
+
+    >>
+     class Advert
+       fields do
+         price :integer, null: true, limit: 2
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    => "add_column :adverts, :price, :integer, limit: 2"
+
+Now run the migration, then change the limit:
+
+    >> ActiveRecord::Migration.class_eval up
+    >>
+     class Advert
+       fields do
+         price :integer, null: true, limit: 3
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    => "change_column :adverts, :price, :integer, limit: 3"
+    >> down
+    => "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
+       fields do
+         price :decimal, null: true, limit: 4
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    => "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).
+
+    >> ::DeclareSchema::Model::FieldSpec.mysql_text_limits?
+    => false
+    >>
+     class Advert
+       fields do
+         notes :text
+         description :text, limit: 30000
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    => "add_column :adverts, :price, :decimal
+        add_column :adverts, :notes, :text, null: false
+        add_column :adverts, :description, :text, null: false"
+
+(There is no limit on `add_column ... :description` above since these tests are run against SQLite.)
+
+Cleanup
+{.hidden}
+    >> Advert.field_specs.delete :price
+    >> Advert.field_specs.delete :notes
+    >> Advert.field_specs.delete :description
+{.hidden}
+
+In MySQL, limits are applied, rounded up:
+
+    >> ::DeclareSchema::Model::FieldSpec::instance_variable_set(:@mysql_text_limits, true)
+    >> ::DeclareSchema::Model::FieldSpec.mysql_text_limits?
+    => true
+    >>
+     class Advert
+       fields do
+         notes :text
+         description :text, limit: 200
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    => "add_column :adverts, :notes, :text, null: false
+        add_column :adverts, :description, :text, null: false, limit: 255"
+
+Cleanup
+{.hidden}
+
+    >> Advert.field_specs.delete :notes
+{.hidden}
+
+Limits that are too high will for MySQL will raise an exception.
+
+    >> ::DeclareSchema::Model::FieldSpec::instance_variable_set(:@mysql_text_limits, true)
+    >> ::DeclareSchema::Model::FieldSpec.mysql_text_limits?
+    => true
+    >>
+      begin
+        class Advert
+          fields do
+            notes :text
+            description :text, limit: 0x1_0000_0000
+          end
+        end
+      rescue => ex
+        "#{ex.class}: #{ex.message}"
+      end
+    => "ArgumentError: limit of 4294967296 is too large for MySQL"
+
+Cleanup
+{.hidden}
+
+    >> Advert.field_specs.delete :notes
+{.hidden}
+
+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.
+
+    >> ::DeclareSchema::Model::FieldSpec.mysql_text_limits?
+    => true
+    >> Advert.connection.execute "ALTER TABLE adverts ADD COLUMN description TINYTEXT"
+    >> Advert.connection.schema_cache.clear!
+    >> Advert.reset_column_information
+    >> Advert.connection.tables
+    => ["adverts"]
+    >> Advert.columns.map(&:name)
+    => ["id", "body", "title", "description"]
+
+Now migrate to an unstated text limit:
+
+    >>
+     class Advert
+       fields do
+         description :text
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    => "change_column :adverts, :description, :text, null: false"
+    >> down
+    => "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
+       fields do
+         description :text, limit: 0xffffffff
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> up
+    => "change_column :adverts, :description, :text, null: false"
+    >> down
+    => "change_column :adverts, :description, :text"
+    >> ::DeclareSchema::Model::FieldSpec::instance_variable_set(:@mysql_text_limits, false)
+
+Cleanup
+{.hidden}
+    >> 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, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> ActiveRecord::Migration.class_eval up
+    >> Advert.connection.schema_cache.clear!
+    >> Advert.reset_column_information
+{.hidden}
+
+
+### 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
+           belongs_to :category
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :category_id, :integer, limit: 8, null: false
+            add_index :adverts, [:category_id], name: 'on_category_id'"
+        >> down.sub(/\n+/, "\n")
+        => "remove_column :adverts, :category_id
+            remove_index :adverts, name: :on_category_id rescue ActiveRecord::StatementInvalid"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.field_specs.delete(:category_id)
+        >> Advert.index_specs.delete_if {|spec| spec.fields==["category_id"]}
+{.hidden}
+
+If you specify a custom foreign key, the migration generator observes that:
+
+        >>
+         class Category < ActiveRecord::Base; end
+         class Advert
+           belongs_to :category, foreign_key: "c_id", class_name: 'Category'
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :c_id, :integer, limit: 8, null: false
+            add_index :adverts, [:c_id], name: 'on_c_id'"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.field_specs.delete(:c_id)
+        >> Advert.index_specs.delete_if { |spec| spec.fields==["c_id"] }
+{.hidden}
+
+You can avoid generating the index by specifying `index: false`
+
+        >>
+         class Category < ActiveRecord::Base; end
+         class Advert
+           belongs_to :category, index: false
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :category_id, :integer, limit: 8, null: false"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.field_specs.delete(:category_id)
+        >> Advert.index_specs.delete_if {|spec| spec.fields==["category_id"]}
+{.hidden}
+
+You can specify the index name with :index
+
+        >>
+         class Category < ActiveRecord::Base; end
+         class Advert
+           belongs_to :category, index: 'my_index'
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :category_id, :integer, limit: 8, null: false
+            add_index :adverts, [:category_id], name: 'my_index'"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.field_specs.delete(:category_id)
+        >> Advert.index_specs.delete_if {|spec| spec.fields==["category_id"]}
+{.hidden}
+
+### 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
+           fields do
+             timestamps
+             optimistic_lock
+           end
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :created_at, :datetime
+            add_column :adverts, :updated_at, :datetime
+            add_column :adverts, :lock_version, :integer, null: false, default: 1"
+        >> down.gsub(/\n+/, "\n")
+        => "remove_column :adverts, :created_at
+            remove_column :adverts, :updated_at
+            remove_column :adverts, :lock_version"
+        >>
+
+Cleanup:
+{.hidden}
+
+        >> Advert.field_specs.delete(:updated_at)
+        >> Advert.field_specs.delete(:created_at)
+        >> Advert.field_specs.delete(:lock_version)
+{.hidden}
+
+### Indices
+
+You can add an index to a field definition
+
+        >>
+         class Advert
+           fields do
+             title :string, index: true, limit: 255, null: true
+           end
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :title, :string, limit: 255
+            add_index :adverts, [:title], name: 'on_title'"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.index_specs.delete_if { |spec| spec.fields==["title"] }
+{.hidden}
+
+You can ask for a unique index
+
+        >>
+         class Advert
+           fields do
+             title :string, index: true, unique: true, null: true, limit: 255
+           end
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :title, :string, limit: 255
+            add_index :adverts, [:title], unique: true, name: 'on_title'"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.index_specs.delete_if { |spec| spec.fields==["title"] }
+{.hidden}
+
+You can specify the name for the index
+
+        >>
+         class Advert
+           fields do
+             title :string, index: 'my_index', limit: 255, null: true
+           end
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :title, :string, limit: 255
+            add_index :adverts, [:title], name: 'my_index'"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.index_specs.delete_if {|spec| spec.fields==["title"]}
+{.hidden}
+
+You can ask for an index outside of the fields block
+
+        >>
+         class Advert
+           index :title
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :title, :string, limit: 255
+            add_index :adverts, [:title], name: 'on_title'"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.index_specs.delete_if { |spec| spec.fields==["title"] }
+{.hidden}
+
+The available options for the index function are `:unique` and `:name`
+
+        >>
+         class Advert
+           index :title, unique: true, name: 'my_index'
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :title, :string, limit: 255
+            add_index :adverts, [:title], unique: true, name: 'my_index'"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.index_specs.delete_if {|spec| spec.fields==["title"]}
+{.hidden}
+
+You can create an index on more than one field
+
+        >>
+         class Advert
+           index [:title, :category_id]
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :title, :string, limit: 255
+            add_index :adverts, [:title, :category_id], name: 'on_title_and_category_id'"
+
+Cleanup:
+{.hidden}
+
+        >> Advert.index_specs.delete_if { |spec| spec.fields==["title", "category_id"] }
+{.hidden}
+
+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
+       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")
+    >> up.gsub(/\n+/, "\n")
+    => "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'"
+    >> down.gsub(/\n+/, "\n")
+    => "remove_column :ads, :title
+        remove_column :ads, :body
+        rename_table :ads, :adverts
+        add_index :adverts, [:id], unique: true, name: 'PRIMARY_KEY'"
+
+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; self.table_name="adverts"; end
+    >> Generators::DeclareSchema::Migration::Migrator.run
+    => ["", ""]
+
+### 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.
+{.hidden}
+
+    >>
+     def nuke_model_class(klass)
+       ActiveSupport::DescendantsTracker.instance_eval do
+         direct_descendants = class_variable_get('@@direct_descendants')
+         direct_descendants[ActiveRecord::Base] = direct_descendants[ActiveRecord::Base].to_a.reject { |descendant| descendant == klass }
+       end
+      Object.instance_eval { remove_const klass.name.to_sym }
+     end
+    >> nuke_model_class(Advert)
+{.hidden}
+
+    >>
+     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")
+    >> up.gsub(/\n+/, "\n")
+    => "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'"
+    >> down.gsub(/\n+/, "\n")
+    => "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'"
+
+### Drop a table
+
+    >> nuke_model_class(Advertisement)
+{.hidden}
+
+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
+    >> up
+    => "drop_table :adverts"
+    >> down.gsub(/,.*/m, '')
+    => "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, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> ActiveRecord::Migration.class_eval up
+
+         class FancyAdvert < Advert
+         end
+         class SuperFancyAdvert < FancyAdvert
+         end
+        >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+        >> up.gsub(/\n+/, "\n")
+        => "add_column :adverts, :type, :string, limit: 255
+            add_index :adverts, [:type], name: 'on_type'"
+        >> down.gsub(/\n+/, "\n")
+        => "remove_column :adverts, :type
+            remove_index :adverts, name: :on_type rescue ActiveRecord::StatementInvalid"
+
+Cleanup
+{.hidden}
+
+        >> Advert.field_specs.delete(:type)
+        >> nuke_model_class(SuperFancyAdvert)
+        >> nuke_model_class(FancyAdvert)
+        >> Advert.index_specs.delete_if { |spec| spec.fields==["type"] }
+{.hidden}
+
+
+## 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
+
+    >> Advert.connection.tables
+    => ["adverts"]
+    >> Advert.columns.map(&:name).sort
+    => ["body", "id", "title"]
+    >> Generators::DeclareSchema::Migration::Migrator.run
+    => ["", ""]
+
+
+### Rename a column and change the default
+
+    >> Advert.field_specs.clear
+    >>
+     class Advert
+       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 })
+    >> up
+    => "rename_column :adverts, :title, :name
+        change_column :adverts, :name, :string, limit: 255, default: \"No Name\""
+    >> down
+    => "rename_column :adverts, :name, :title
+        change_column :adverts, :title, :string, limit: 255, default: \"Untitled\""
+
+
+### Rename a table and add a column
+
+    >> nuke_model_class(Advert)
+{.hidden}
+
+    >>
+     class Ad < ActiveRecord::Base
+       fields do
+         title      :string, default: "Untitled", limit: 255
+         body       :text, null: true
+         created_at :datetime
+       end
+     end
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run(adverts: :ads)
+    >> up.gsub(/\n+/, "\n")
+    => "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'"
+
+    >>
+     class Advert < ActiveRecord::Base
+       fields do
+         body :text, null: true
+         title :string, default: "Untitled", limit: 255, null: true
+       end
+     end
+{.hidden}
+
+## 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 })
+    >> up.gsub(/\n+/, "\n")
+    => "rename_column :adverts, :id, :advert_id
+        add_index :adverts, [:advert_id], unique: true, name: 'PRIMARY_KEY'"
+
+    >> nuke_model_class(Advert)
+    >> ActiveRecord::Base.connection.execute "drop table `adverts`;"
+{.hidden}
+
+## DSL
+
+The DSL allows lambdas and constants
+
+    >>
+        class User < ActiveRecord::Base
+          fields do
+            company :string, limit: 255, ruby_default: -> { "BigCorp" }
+          end
+        end
+    >> User.field_specs.keys
+    => ['company']
+    >> User.field_specs['company'].options[:ruby_default]&.call
+    => "BigCorp"
+
+
+## validates
+
+DeclareSchema can accept a validates hash in the field options.
+
+    >> $company_validates_options = :none
+    >>
+       class Ad < ActiveRecord::Base; end;
+       def Ad.validates(field_name, options)
+         $company_validates_options = "got field_name: #{field_name}, options: #{options.inspect}"
+       end
+    >>
+      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
+    >> # expect(Ad).to receive(:validates).with(:company, presence: true, uniqueness: { case_sensitive: false })
+    >> up, down = Generators::DeclareSchema::Migration::Migrator.run
+    >> ActiveRecord::Migration.class_eval up
+    >> $company_validates_options
+    => "got field_name: company, options: {:presence=>true, :uniqueness=>{:case_sensitive=>false}}"
+    >> Ad.field_specs['company'].options[:validates].inspect
+    => "{:presence=>true, :uniqueness=>{:case_sensitive=>false}}"