declare_schema 0.1.0 → 0.2.0

data/test/generators.rdoctest

@@ -1,60 +0,0 @@
-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

@@ -1,56 +0,0 @@
--*- 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

@@ -1,846 +0,0 @@
-# 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}}"