README.md in apartment-1.0.2 vs README.md in apartment-1.1.0
- old
+ new
@@ -6,18 +6,26 @@
Apartment provides tools to help you deal with multiple tenants in your Rails
application. If you need to have certain data sequestered based on account or company,
but still allow some data to exist in a common tenant, Apartment can help.
+## HELP!
+
+In order to help drive the direction of development and clean up the codebase, we'd like to take a poll
+on how people are currently using Apartment. If you can take 5 seconds (1 question) to answer
+this poll, we'd greatly appreciated it.
+
+[View Poll](http://www.poll-maker.com/poll391552x4Bfb41a9-15)
+
## Excessive Memory Issues on ActiveRecord 4.x
> If you're noticing ever growing memory issues (ie growing with each tenant you add)
> when using Apartment, that's because there's [an issue](https://github.com/rails/rails/issues/19578)
> with how ActiveRecord maps Postgresql data types into AR data types.
-> This has been patched and will be release for AR 4.2.2. It's apparently hard
+> This has been patched and will be released for AR 4.2.2. It's apparently hard
> to backport to 4.1 unfortunately.
-> If you want to use this today, you can use our [4.2.1 patched version](https://github.com/influitive/rails/tree/v4.2.1.memfix) on our github account using the code sample below.
+> If you're noticing high memory usage from ActiveRecord with Apartment please upgrade.
```ruby
gem 'rails', '4.2.1', github: 'influitive/rails', tag: 'v4.2.1.memfix'
```
@@ -116,19 +124,49 @@
config.middleware.use 'Apartment::Elevators::Subdomain'
end
end
```
-If you want to exclude a domain, for example if you don't want your application to treate www like a subdomain, in an initializer in your application, you can set the following:
+By default, the subdomain elevator assumes that the parent domain consists of two segments, e.g. 'example.com'. If this isn't the case, you can adjust the `tld_length` (top level domain length) configuration variable, which defaults to 1. For example, if you are using 'localhost' in development:
+```ruby
+# config/initializers/apartment.rb
+Apartment.configure do |config|
+ ...
+ config.tld_length = 0 if Rails.env == 'development'
+end
+```
+If you want to exclude a domain, for example if you don't want your application to treat www like a subdomain, in an initializer in your application, you can set the following:
+
```ruby
# config/initializers/apartment/subdomain_exclusions.rb
Apartment::Elevators::Subdomain.excluded_subdomains = ['www']
```
This functions much in the same way as Apartment.excluded_models. This example will prevent switching your tenant when the subdomain is www. Handy for subdomains like: "public", "www", and "admin" :)
+**Switch on first subdomain**
+To switch on the first subdomain, which analyzes the chain of subdomains of the request and switches to a tenant schema of the first name in the chain (e.g. owls.birds.animals.com would switch to "owl"). It can be used like so:
+
+```ruby
+# application.rb
+module MyApplication
+ class Application < Rails::Application
+ config.middleware.use 'Apartment::Elevators::FirstSubdomain'
+ end
+end
+```
+
+If you want to exclude a domain, for example if you don't want your application to treate www like a subdomain, in an initializer in your application, you can set the following:
+
+```ruby
+# config/initializers/apartment/subdomain_exclusions.rb
+Apartment::Elevators::FirstSubdomain.excluded_subdomains = ['www']
+```
+
+This functions much in the same way as the Subdomain elevator.
+
**Switch on domain**
To switch based on full domain (excluding subdomains *ie 'www'* and top level domains *ie '.com'* ) use the following:
```ruby
# application.rb
@@ -185,10 +223,20 @@
return tenant_name
end
end
```
+### Dropping Tenants
+
+To drop tenants using Apartment, use the following command:
+
+```ruby
+Apartment::Tenant.drop('tenant_name')
+```
+
+When method is called, the schema is dropped and all data from itself will be lost. Be careful with this method.
+
## Config
The following config options should be set up in a Rails initializer such as:
config/initializers/apartment.rb
@@ -223,11 +271,11 @@
```ruby
config.default_schema = "some_other_schema"
```
-With that set, all excluded models will use this schema as the table name prefix instead of `public` and `reset` on `Apartment::Tenant` will return to this schema also
+With that set, all excluded models will use this schema as the table name prefix instead of `public` and `reset` on `Apartment::Tenant` will return to this schema as well.
## Persistent Schemas
Apartment will normally just switch the `schema_search_path` whole hog to the one passed in. This can lead to problems if you want other schemas to always be searched as well. Enter `persistent_schemas`. You can configure a list of other schemas that will always remain in the search path, while the default gets swapped out:
```ruby
@@ -373,9 +421,36 @@
to ensure there is no conflict between your environments. This is mainly for the benefit of your development
and test environments. If you wish to turn this option off in production, you could do something like:
```ruby
config.prepend_environment = !Rails.env.production?
+```
+
+## Tenants on different servers
+
+You can store your tenants in different databases on one or more servers.
+To do it, specify your `tenant_names` as a hash, keys being the actual tenant names,
+values being a hash with the database configuration to use.
+
+Example:
+
+```ruby
+config.tenant_names = {
+ 'tenant1' => {
+ adapter: 'postgresql',
+ host: 'some_server',
+ port: 5555,
+ database: 'postgres' # this is not the name of the tenant's db
+ # but the name of the database to connect to, before creating the tenant's db
+ # mandatory in postgresql
+ }
+}
+# or using a lambda:
+config.tenant_names = lambda do
+ Tenant.all.each_with_object({}) do |tenant, hash|
+ hash[tenant.name] = tenant.db_configuration
+ end
+end
```
## Delayed::Job
### Has been removed... See apartment-sidekiq for a better backgrounding experience