declare_schema 0.1.3 → 0.2.0.pre.1

data/spec/lib/declare_schema/prepare_testapp.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tmpdir'
+
+TESTAPP_PATH = ENV['TESTAPP_PATH'] || File.join(Dir.tmpdir, 'declare_schema_testapp') unless defined?(TESTAPP_PATH)
+FileUtils.chdir(TESTAPP_PATH)
+
+system "rm -rf app/models/ad* app/models/alpha*"
+system "rm -rf test/models/ad* test/models/alpha*"
+system "rm -rf test/fixtures/ad* test/fixtures/alpha*"
+system "rm -rf db/migrate/*"
+system "mkdir -p #{TESTAPP_PATH}/app/assets/config"
+system "echo '' >> #{TESTAPP_PATH}/app/assets/config/manifest.js"
+
+require "#{TESTAPP_PATH}/config/environment"
+
+require 'rails/generators'
+Rails::Generators.configure!(Rails.application.config.generators)
+
+(ActiveRecord::Base.connection.tables - Generators::DeclareSchema::Migration::Migrator.always_ignore_tables).each do |table|
+  ActiveRecord::Base.connection.execute("DROP TABLE #{ActiveRecord::Base.connection.quote_table_name(table)}")
+end
+
+ActiveRecord::Base.send(:descendants).each do |model|
+  unless model.name['Active'] || model.name['Application']
+    nuke_model_class(model)
+  end
+end

data/spec/spec_helper.rb

@@ -22,6 +22,32 @@ RSpec.configure do |config|
 
   RSpec::Support::ObjectFormatter.default_instance.max_formatted_output_length = 2_000
 
+  def active_record_base_class
+    if Rails::VERSION::MAJOR == 4
+      'ActiveRecord::Base'
+    else
+      'ApplicationRecord'
+    end
+  end
+
+  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
+
+  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 }
+      if defined?(ApplicationRecord)
+        direct_descendants[ApplicationRecord] = direct_descendants[ApplicationRecord].to_a.reject { |descendant| descendant == klass }
+      end
+    end
+    Object.instance_eval { remove_const(klass.name.to_sym) rescue nil }
+  end
+
   def with_modified_env(options, &block)
     ClimateControl.modify(options, &block)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: declare_schema
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0.pre.1
 platform: ruby
 authors:
 - Invoca Development adapted from hobo_fields by Tom Locke
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-08 00:00:00.000000000 Z
+date: 2020-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -68,24 +68,22 @@ files:
 - lib/generators/declare_schema/migration/templates/migration.rb.erb
 - lib/generators/declare_schema/model/USAGE
 - lib/generators/declare_schema/model/model_generator.rb
-- lib/generators/declare_schema/model/templates/model_injection.rb.erb
 - lib/generators/declare_schema/support/eval_template.rb
 - lib/generators/declare_schema/support/model.rb
 - lib/generators/declare_schema/support/thor_shell.rb
+- spec/lib/declare_schema/api_spec.rb
 - spec/lib/declare_schema/field_declaration_dsl_spec.rb
+- spec/lib/declare_schema/generator_spec.rb
+- spec/lib/declare_schema/interactive_primary_key_spec.rb
+- spec/lib/declare_schema/migration_generator_spec.rb
+- spec/lib/declare_schema/prepare_testapp.rb
 - spec/spec_helper.rb
-- test/api.rdoctest
-- test/generators.rdoctest
-- test/interactive_primary_key.rdoctest
-- test/migration_generator.rdoctest
-- test/migration_generator_comments.rdoctestDISABLED
-- test/prepare_testapp.rb
 - test_responses.txt
 homepage: https://github.com/Invoca/declare_schema
 licenses: []
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -101,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubygems_version: 3.0.3
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Database migration generator for Rails
 test_files: []

data/lib/generators/declare_schema/model/templates/model_injection.rb.erb

@@ -1,25 +0,0 @@
-
-  fields do
-<% for attribute in field_attributes -%>
-    <%= "%-#{max_attribute_length}s" % attribute.name %> :<%= attribute.type %><%=
-      case attribute.type.to_s
-      when 'string'
-        ', limit: 255'
-      else
-        ''
-      end
-    %>
-<% end -%>
-<% if options[:timestamps] -%>
-    timestamps
-<% end -%>
-  end
-
-<% for bt in bts -%>
-  belongs_to :<%= bt %>
-<% end -%>
-<%= "\n" unless bts.empty? -%>
-<% for hm in hms -%>
-  has_many :<%= hm %>, dependent: :destroy
-<% end -%>
-<%= "\n" unless hms.empty? -%>

data/test/api.rdoctest

@@ -1,136 +0,0 @@
-# DeclareSchema API
-
-In order for the API examples to run we need to load the rails generators of our testapp:
-{.hidden}
-
-    doctest: prepare testapp environment
-    doctest_require: 'prepare_testapp'
-{.hidden}
-
-## Example Models
-
-Let's define some example models that we can use to demonstrate the API. With DeclareSchema we can use the 'declare_schema:model' generator like so:
-
-    $ rails generate declare_schema:model advert title:string body:text
-
-This will generate the test, fixture and a model file like this:
-
-    >> Rails::Generators.invoke 'declare_schema:model', %w(advert title:string body:text)
-{.hidden}
-
-    class Advert < ActiveRecord::Base
-      fields do
-        title :string
-        body :text, limit: 0xffff, null: true
-      end
-    end
-
-The migration generator uses this information to create a migration. The following creates and runs the migration so we're ready to go.
-
-    $ rails generate declare_schema:migration -n -m
-
-We're now ready to start demonstrating the API
-
-    >> require_relative "#{Rails.root}/app/models/advert.rb" if Rails::VERSION::MAJOR > 5
-    >> Rails::Generators.invoke 'declare_schema:migration', %w(-n -m)
-    >> Rails::Generators.invoke 'declare_schema:migration', %w(-n -m)
-{.hidden}
-
-## 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.
-
-        >> a = Advert.new :body => "This is the body", id: 1, title: "title"
-        >> a.body.class
-        => String
-
-This also works after a round-trip to the database
-
-        >> a.save
-        >> b = Advert.find(a.id)
-        >> b.body.class
-        => String
-
-## Names vs. Classes
-
-The full set of available symbolic names is
-
- * `:integer`
- * `:float`
- * `:decimal`
- * `:string`
- * `:text`
- * `:boolean`
- * `:date`
- * `:datetime`
- * `:html`
- * `:textile`
- * `:markdown`
- * `:password`
-
-You can add your own types too. More on that later.
-
-
-## 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
-        >> Advert.attr_type :title
-        => String
-        >> Advert.attr_type :body
-        => 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 Advert
-           fields do
-             title :string, :required, limit: 255
-           end
-         end
-        >> a = Advert.new
-        >> a.valid?
-        => false
-        >> a.errors.full_messages
-        => ["Title can't be blank"]
-        >> a.id = 2
-        >> a.body = "hello"
-        >> a.title = "Jimbo"
-        >> a.save
-        => true
-
-
-### Unique fields
-
-The `:unique` argument in a field declaration gives `validates_uniqueness_of`:
-
-        >>
-         class Advert
-           fields do
-             title :string, :unique, limit: 255
-           end
-         end
-        >> a = Advert.new :title => "Jimbo", id: 3, body: "hello"
-        >> a.valid?
-        => false
-        >> a.errors.full_messages
-        => ["Title has already been taken"]
-        >> a.title = "Sambo"
-        >> a.save
-        => true

data/test/generators.rdoctest

@@ -1,62 +0,0 @@
-doctest: prepare testapp environment
-doctest_require: 'prepare_testapp'
-
-doctest: generate declare_schema:model
->> begin; Rails::Generators.invoke 'declare_schema:model', %w(alpha/beta one:string two:integer); rescue => ex; $stderr.puts "#{ex.class}: #{ex}\n#{ex.backtrace.join("\n")}"; end
-
-
-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
->> puts "#{Rails.root}/app/models/alpha.rb"
->> require "#{Rails.root}/app/models/alpha.rb" if Rails::VERSION::MAJOR > 4
->> require "#{Rails.root}/app/models/alpha/beta.rb" if Rails::VERSION::MAJOR > 4
->> Rails::Generators.invoke 'declare_schema:migration', %w(-n -m)
-
-doctest: schema.rb file exists
->> system("ls -al db")
->> File.exist? 'db/schema.rb'
-=> true
-
-doctest: db file exists
->> File.exist?("db/development.sqlite3") || File.exist?("db/test.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}}"