Gem Version Build Status Coverage Status Dependency Status

SchemaMonkey

SchemaMonkey is a behind-the-scenes gem to facilitate writing extensions to ActiveRecord (typically other gems, but could also be in an application). It provides:

  • A "middleware"-style interface to key ActiveRecord internal functions. For example, there's a middleware hook to let you insert a handler for migration column definition options, and there are several hooks to insert handlers for the various parts of a schema dump.

  • A convention-based protocol for include'ing custom modules into ActiveRecord. You just define your modules and SchemaMonkey will automatically include them in the right places.

The middleware interface has two benefits: it provides a clean API so that the gem or aplication code doesn't need to monkey-patch ActiveRecord (SchemaMonkey does all the monkey-patching for you), and it lets multiple client gems operate in parallel without concern about conflicting monkey-patches.

Installation

As usual:

# In a gem's .gemspec:
spec.add_dependency "schema_monkey", "~> <MAJOR>.<MINOR>", ">= <MAJOR>.<MINOR>.<PATCH>"

# In an applications Gemfile:
gem "schema_monkey", "~> <MAJOR>.<MINOR>", ">= <MAJOR>.<MINOR>.<PATCH>"

SchemaMonkey follows semantic versioning; it's a good idea to explicitly use the ~> and >= dependencies to make sure your gem's clients don't accidentally pull in a version of SchemaMonkey that your gem isn't compatible with.

To use with a rails app, also include

gem "schema_monkey_rails"

which creates a Railtie to insert SchemaMonkey appropriately into the rails stack.

Compatibility

SchemaMonkey is tested on:

  • ruby 1.9.3 with activerecord 4.2, using mysql2, sqlite3 or postgresql
  • ruby 2.1.5 with activerecord 4.2, using mysql2, sqlite3 or postgresql

Usage

Sorry -- no real documentation yet. See examples in schema_plus_indexes and schema_plus_pg_indexes

Development & Testing

Are you interested in contributing to schema_monkey? Thanks! Please follow the standard protocol: fork, feature branch, develop, push, and issue pull request.

Some things to know about to help you develop and test:

  • SchemaMonkey is a wrapper around two subparts:

    • SchemaMonkey::Tool provides the convention-based mechanism for registering clients that extend ActiveRecord using include's and middleware.
    • SchemaMonkey::CoreExtensions defines the ActiveRecord extension API. It is itself just the first client registered with SchemaMonkey::Tool. Ugh. Currently no specs for SchemaMonkey::CoreExtensions; testing indirectly by testing the client gems that use it. Working on it...

One day might actually split these into separate gems to decouple their development and testing. And actually the middleware mechanism of SchemaMonkey::Tool could be a split out separate gem.

  • schema_dev: SchemaMonkey uses schema_dev to facilitate running rspec tests on the matrix of ruby, rails, and database versions that the gem supports, both locally and on travis-ci

To to run rspec locally on the full matrix, do:

    $ schema_dev bundle install
    $ schema_dev rspec

You can also run on just one configuration at a time; For info, see schema_dev --help or the schema_dev README.

The matrix of configurations is specified in schema_dev.yml in the project root.