/schema_plus_multischema

Extends ActiveRecord with support for using multiple schemas within a single database

Primary LanguageRubyMIT LicenseMIT

Gem Version Build Status Coverage Status

SchemaPlusMultischema

SchemaPlusMultischema adds support for using multiple schemas with ActiveRecord. Note that the gem only adds functionality if the database schema search path is not DBMS default (schema_search_path='$user,public').

Then following features are supported:

  • ActiveRecord::Connection#tables returns each table name in the form "schema.table"

  • Schema dump includes the schema definitions, search path and creates each table in its appropriate schema. In addition, it all foreign key references will contain table references in its appropriate schema.

Support is currently limited to Postgresql. See details below.

SchemaPlusMultischema is part of the SchemaPlus family of Ruby on Rails ActiveRecord extension gems.

Installation

As usual:

gem "schema_plus_multischema"                # in a Gemfile
gem.add_dependency "schema_plus_multischema" # in a .gemspec

Compatibility

SchemaPlusMultischema is tested on:

  • ruby 2.1.5 with activerecord 4.2, using postgresql

SchemaPlusMultischema should be a no-op if used with sqlite3 or mysql.

Background

Your PostgreSQL database might have multiple schemas, that provide namespaces for tables. For example, you could define:

connection.execute "CREATE SCHEMA first"
connection.execute "CREATE SCHEMA second"

ActiveRecord's PostgreSQL connection adapter lets you set PostgreSQL's search_path to choose which schemas to look at:

connection.schema_search_path = "first,second"

And ActiveRecord let you use schema names in migrations, such as

create_table 'first.my_table' do ...
create_table 'second.my_table' do ...

But without SchemaPlusMultischema, ActiveRecord's introspection doesn't handle them properly. It does find all tables that are in the current search path, but it doesn't prefix them with their schema names. The schema dump schema/dump.rb doesn't take into account the schemas at all and the dump will be invalid. Futhermore, if there are tables with the same name in different schemas, only 1 of the tables will be dumped.

Features

With SchemaPlusMultischema installed, it activates its features whenever your schema search path differs from PostgreSQL's default ("$user",public). If schema search path is PostgreSQL's default, then SchemaPlusMultischema stays out of the way and the behavior is the same as pure ActiveRecord.

connection.tables

The output of ActiveRecord's connection.tables method will have table name prefixed with its schema. E.g.

connection.tables  # => ["first.my_table", "second.my_table"]

Schema dump

The schema dump (db/schema.rb) will include the schema setup, and the table definitions will be prefixed with their schemas. E.g.

    connection.execute "CREATE SCHEMA IF NOT EXISTS first"
    connection.execute "CREATE SCHEMA IF NOT EXISTS second"
    connection.schema_search_path = "first,second"

    create_table "first.my_table" do ...
    create_table "second.my_table" do ...

If you're using the schema_plus_foreign_keys gem, foreign key associations will also contain table definitions with prefixed schemas. E.g.

    create_table "first.my_table" do
      ...
      t.integer :my_table_id, null: false, foreign_key: {references: "second.my_table"...

History

  • 0.1.1 - Fix to work with postgresql 9.5; upgrade schema_plus_core dependency
  • 0.1.0 - Initial release

Development & Testing

Are you interested in contributing to SchemaPlusMultischema? 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:

  • schema_dev: SchemaPlus::Multischema uses schema_dev to facilitate running rspec tests on the matrix of ruby, activerecord, 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.

  • schema_plus_core: SchemaPlus::Multischema uses the SchemaPlus::Core API that provides middleware callback stacks to make it easy to extend ActiveRecord's behavior. If that API is missing something you need for your contribution, please head over to schema_plus_core and open an issue or pull request.
  • schema_monkey: SchemaPlus::Multischema is implemented as a schema_monkey client, using schema_monkey's convention-based protocols for extending ActiveRecord and using middleware stacks.