Sandboxy allows you to use virtual data-oriented environments inside a Rails application while being able to switch between them at runtime. It achieves that by using a combination of Rack Middleware and ActiveRecord.
Table of Contents
- To do
Sandboxy works with Rails 5 onwards. You can add it to your
And then execute:
Or install it yourself as:
$ gem install sandboxy
If you always want to be up to date fetch the latest from GitHub in your
gem 'sandboxy', github: 'jonhue/sandboxy'
Now run the generator:
$ rails g sandboxy
To wrap things up, migrate the changes into your database:
$ rails db:migrate
Add Sandboxy to the models where you want to separate records depending on their environments:
class Foo < ApplicationRecord sandboxy end
In most use cases you would want to add
sandboxy to a lot of ActiveRecord models if not all. To simplify that you could create a new class and let all your models inherit from it:
class SharedSandbox < ApplicationRecord self.abstract_class = true sandboxy end class Foo < SharedSandbox end
By default you can only access records belonging to the current environment (defined by
Sandboxy.environment = 'test' Foo.all # => returns all test foo's Sandboxy.environment = 'sandbox' Foo.all # => returns all sandbox foo's
Now to access the records belonging to a certain environment regardless of your current environment, you can use:
Foo.live_environment # => returns all live foo's Foo.sandbox_environment # => returns all sandbox foo's Foo.desandbox # => returns all foo's
Let's check to which environment this
foo = Foo.create! foo.live_environment? # => false foo.sandbox_environment? # => true
You should keep in mind that when you create a new record, it will automatically belong to your app's current environment.
Don't worry, you can move records between environments:
foo.move_environment_live foo.live_environment? # => true foo.move_environment_sandbox foo.sandbox_environment? # => true
At runtime you can always switch environments anywhere in your application by setting
Sandboxy.environment. You can set it to any string you like. That makes Sandboxy super flexible.
Sandboxy.environment = 'live' Sandboxy.live_environment? # => true Sandboxy.sandbox_environment? # => false
Sandbox & APIs
It's flexibility allows Sandboxy to work really well with APIs.
Typically an API provides two sets of authentication credentials for a consumer - one for live access and one for sandbox/testing.
Whenever you authenticate your API's consumer, just make sure to set
Sandboxy.environment accordingly to the credential the consumer used. From thereon, Sandboxy will make sure that your consumer only reads & updates data from the environment he is in.
You can configure Sandboxy by passing a block to
configure. This can be done in
Sandboxy.configure do |config| config.default = 'sandbox' end
default Set your environment default. This is the environment that your app boots with. By default it gets refreshed with every new request to your server. Takes a string. Defaults to
retain Retain your current app environment on new requests. If set to
false, your app will return to your default environment on every new request. Takes a boolean. Defaults to
Tests are written with Shoulda on top of
Test::Unit with Factory Girl being used instead of fixtures. Tests are run using rake.
- Fork this repository
- Clone your forked git locally
- Install dependencies
$ bundle install
- Run tests
$ rake test
Test coverage can be calculated using SimpleCov. Make sure you have the simplecov gem installed.
- Add SimpleCov to the Gemfile
- Uncomment the relevant section in
- Run tests
$ rake test
We use GitHub projects to coordinate the work on this project.
To propose your ideas, initiate the discussion by adding a new issue.
We hope that you will consider contributing to Sandboxy. Please read this short overview for some information about how to get started:
Sandboxy follows Semantic Versioning 2.0 as defined at http://semver.org.