Sublease

Sublease is a tenanting engine for Rails 4.2 and greater applications using a shared database or schema. It's a Rails Engine designed to be lightweight, simple to implement, and easy to use. Sublease works with existing as well as new applications.

Ruby Versions

The following Ruby MRI and jRuby versions or greater are supported. Sublease was not built for or tested against other versions.

Ruby >= 2.3.1 jRuby >= 9.1.8.0

Rails Versions

Sublease is built and tested to run using Rails version 4.2 or greater. While Sublease will run on Rails 4.1.16, it is not officially supported.

Installation

On the model that you want tenanted, add the fields 'domain' and 'subdomain' through a migration. Both of these fields should be strings.
Add this line to your application's Gemfile:
```
gem 'sublease'
```
And then execute:
```
$ bundle install
```
Or install it yourself as:
```
$ gem install sublease
```
Finally, install the Sublease configuration file. This will add config/initializers/sublease.rb to you application.
```
 $ rails generate sublease:install
```

Usage

Models

Sublease works by create controlled has_many and belongs_to relationships between your tenant and any other model. The has_many_subleases model should inherit from Sublease::Tenant and the belongs_to_subleases model should inherit from Sublease::Lodger. For instance, if your application allowed for accounts to be created that would be shared by many users, your models would look like this:

class Account < Sublease::Tenant
  has_many_subleases(:users)
end

class User < Sublease::Lodger
  belongs_to_sublease(:account)
end

The relationships work just like normal has_many and belongs_to ActiveRecord Relationships even taking the same options. The difference is that the relationship is immutable and all dependencies on the relationship are overridden to call the destroy method. This is to ensure that all callback are called on the model in the event of a delete or destroy method call.

Scoping For Unique Records

When adding unique record scope on your model, just do it as you would normally in ActiveRecord. Sublease is designed to be simple and not replace things that Rails and ActiveRecord can do just fine. Using the example above, if you wanted to scope a user's email to be unique per account, you might add a validator like so:

class User < Sublease::Lodger
  belongs_to_sublease(:account)

  validates :email, presence: true, uniqueness: { case_sensitive: false, scope: :account_id }
end

Moving Tenants

In most cases, once a record is tenanted it stays with it's tenant. Sublease prevents switching tenants by default. However, sometimes it is necessary to move a record from one tenant to another. To do this set the allow_sublease_change property to true. Using the example above, we'll move user 1 from account 1 to account 2.

$ user = User.find 1
$ user.allow_sublease_change = true
$ user.account_id = 2
$ user.save

Controllers

Sublease can change your tenant on the fly based on a requests subdomain, domain, or both. This switching is handled in any controller you want by including Sublease::TenantSwitcher. In the example below, we include it into ApplicationController which means that every controller in the application will check the request to make sure the correct tenant is set. You might not want every request to a controller checking to set the tenant so make sure you only add it to the controllers that need it.

class ApplicationController < ActionController::Base

  include Sublease::TenantSwitcher
end

The current tenant can be accessed from Sublease.current_tenant. Use this to set the tenant for new records or even to show records belonging to that tenant.

Configuration

Sublease can be configured to set a default subdomain and/or domain. It can also be configured to determine by which method to switch the tenant: subdomain, domain, or subdomain and domain. See config/initializers/sublease.rb for all options.

Development

After checking out the repo, run bundle to install dependencies. Then, run rake test to run the tests.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bacrossland/sublease. All pull requests should be against the development branch. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Sublease project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.