EZ

Easy domain modeling in Rails without migrations.

Version 1.9.7

For educational purposes only.

Tested against Rails 5.1.4.

NOTE: For Rails < 5.0, use version 1.3.

Highlights

• Applies schema changes based on a file named db/models.yml.
• Schema migrations are determined automatically and applied to the database.
• Optionally generates routes, controllers, and/or views based on the models.
• Schema migrations are applied by running rails server, rails console, or by typing reload! in the console. rails db:migrate is not affected.
• Embraces Rails column naming conventions by inferring columns types based on the name.
• Enhances the Rails Console with customized AwesomePrint and Hirb integration
• Adds two new ActiveRecord methods: .sample(n = 1) and .none?

Installation

gem 'ez'

Start the server or console to force the initial generation of db/models.yml.

If a file named .ez in the project directory is present, or in the user's home folder, it controls the behavior of the gem.

Alternatively, you can run rails ez:generate_yml to generate these files without running your app.

Usage and Configuration

1. Use db/models.yml to define your schema. Database schema changes are applied directly without affecting migrations. (rails db:migrate will also trigger the changes).
2. Foreign-key indexes are generated automatically.
3. Use rails db:migrate:preview to perform a "dry run" based your db/models.yml file.
4. Use the .ez file to control functionality.
5. See the section on Migrations below.

Config setting	Default	Description
models	true	Watches models.yml for changes. Set to false to turn off all functionality
timestamps	true	Generates created_at and updated_at columns on every model.
restful_routes	true	Adds resources :<tablename> to routes.rb for each model
controllers	true	Generates one controller per model with 7 empty methods.
views	true	Generates the view folder for each model, with 7 empty views.

WARNING! Development vs Production

Renaming a column in db/models.yml appear to the gem as if you dropped the old column and created a new column. You will lose any data you had in that column. Same goes for renaming models: the old table will be dropped.

In production, this could be catastrophic. Therefore, this gem will not delete tables or columns in production, but only add tables and add columns. This could be problematic for apps that need to drop tables or columns from the production database, but this hopefully an edge case.

Syntax Guide for db/models.yml

It's just YAML. We recommend text instead of string columns (because of recent SQLite3 changes) but both are supported.

Book:
  title: text
  author_id: integer
  created_at: datetime
  updated_at: datetime
  paperback: boolean

Author:
  last_name: text
  first_name: text
  book_count: integer

(Optional) Variations

1. The colon after the model name is optional.

2. Rails conventions are embraced in db/models.yml resulting in these sensible defaults:

   • If a column type isn't specified, it's assumed to be a text column.
   • Column names ending in _id and _count are assumed to be of type integer.
   • Column names ending in _at are assumed to be of type datetime.
   • Column names ending in _on are assumed to be of type date.

Also, note that _id columns are assumed to be foreign keys and will automatically generate a database index for that column.

So the above models could be written as:

Book
  title
  author_id
  created_at
  updated_at
  paperback: boolean

Author
  last_name
  first_name
  book_count

Default Values You can specify default values for columns right after the column type:

Book
  title
  author_id
  created_at
  updated_at
  paperback: boolean(false)

Author
  last_name
  first_name
  book_count: integer(0)

• Boolean columns are assumed to be given a default of false if not otherwise specified.

ActiveRecord Enhancements

• .sample method to choose a random row, or .sample(5) for five sample rows.
• .none? method on a collection: Product.where(in_stock: true).none?
• .to_ez to generate a snippet from legacy models that you can paste into models.yml.

Beginner-friendly Rails Console

• Shows helpful instructions when console starts, including the list of model classes found in the application.
• Solves the "no connection" message in Rails >= 4.0.1 (if you try to inspect a model without making a query first) by establishing an initial connection to the development database.
• Activates AwesomePrint.
• Uses Hirb for table-like display.
• Configures Hirb to allow nice table output for ActiveRecord::Relation collections
• Configures Hirb to produce hash-like output for single ActiveRecord objects

Migrations

This gem is expecting that the student will not use database migrations to control the schema. It is ok to use both migrations and models.yml, but be aware of the following:

• If at least one migration file is detected, this gem will not remove tables in development mode that would normally removed via models.yml because it is not possible to know if the table is controlled by migrations or not.
• Wherever possible, it's best to translate a migration required for a third-party gem (say, for Devise) into an entry in models.yml so that everything is managed in one place.
• Pull requests for integrating new features into ez are encouraged.

Switching To Rails Migrations

There will (hopefully) come a time when the student wishes to graduate to proper database migrations, probably for managing a production application. To switch to normal Rails migrations:

1. Remove the ez gem and run bundle install
2. Delete any .ez file in the project root

From this point forward, migrations can be used as expected.