activerecord-tenanted: one database per tenant for Rails

Tenants get separate stores, not a scope clause

Most multi-tenant Rails designs put every customer in the same database and add a tenant_id column to every table. activerecord-tenanted takes the other route. The repository description says it enables a Rails application to have separate databases for each tenant, and the README reframes the goal as hosting multiple isolated tenants.

The design is rooted in three stated principles. Data at rest is persisted in a separate store for each tenant, isolated either physically or logically from other tenants. Data in transit is only sent to users with authenticated access to the tenant instance. And all tenant-related code execution must happen within a well-defined isolated tenant context with controls around data access and transmission.

The distinction matters for how you evaluate the gem. A tenant_id filter is a convention that every query has to remember, and a forgotten filter leaks one customer's rows into another's page. A separate store makes that class of mistake structurally harder, because the connection itself is scoped. The cost is operational: one schema per tenant, migrations that have to reach every store, and a connection pool that has to grow with the number of live tenants.

The bet is that application code never mentions tenants

The stated ambition is unusually blunt: developing a multi-tenant Rails app should be as easy as developing a single-tenant app, and your code should not have to know about tenanting. The hope expressed in the documentation is that you will rarely need to think about managing tenant isolation, and that as long as you are following Rails conventions, the gem and the framework will keep your tenants' data safe.

That is a design claim about where responsibility sits. Rather than asking developers to remember a scoping convention on every query, the gem extends or integrates tightly with Rails so that data persisted or transmitted happens within an isolated tenant context without developers having to think about it.

Reading the principles together gives you the intended failure mode. If tenant isolation depends on the application code following Rails conventions, then the gem's safety property is conditional on how faithfully the codebase follows those conventions. That is a reasonable bargain for a team with strong Rails habits and a much weaker one for a codebase with a lot of raw SQL, background jobs that boot outside a request, or a habit of reaching for `ActiveRecord::Base.connection` directly. Nothing in the repository documents how those cases are handled, so this is the first question to ask the maintainers.

Only the sqlite3 adapter is fully supported

This is the constraint that will decide the answer for most production applications, and it is placed in a prominent note near the top of the documentation rather than buried. Only the sqlite3 database adapter is fully supported right now, and the documentation invites readers with a use case for tenanting one of the other databases supported by Rails to reach out to the maintainers.

Read that carefully. Fully supported is not the same as unsupported. The other Rails adapters may work, and the maintainers are asking for use cases, which implies some demand exists for other databases. But nothing in the repository states which adapters are partially working, how partial they are, or whether the isolation guarantees hold on them. For a system handling customer data, an undocumented guarantee is not a guarantee.

The practical implication is that this gem currently targets local development, prototypes, small single-node deployments and test setups where a separate SQLite file per tenant is a natural fit. The multi-database story is on the roadmap by implication, not by statement. If your production system runs PostgreSQL, adopting this gem means either accepting an unsupported configuration or waiting.

Adding the gem to a Rails application

Installation is a single Bundler command, which is the whole documented setup step:

bundle add activerecord-tenanted

After that, the README redirects you to a separate guide file, GUIDE.md, for detailed configuration and usage. That file exists at the root of the repository alongside the README, the gemspec, the Rakefile, a CHANGELOG.md, a CONTRIBUTING.md and a `.ruby-version` file. The important thing to notice is that the front page of the repository deliberately contains no usage example at all: no model code, no tenant declaration, no migration step, and no configuration snippet.

That is a choice about what this documentation is for. The README explains the reasoning and points at the guide for the mechanics, so a reader who wants to know how tenants are declared or how the tenant store is chosen has to open GUIDE.md. Anyone evaluating the gem for adoption should read that guide before estimating the work, because the amount of configuration between a bare Rails app and a working tenant isolation setup is where the real cost of this approach becomes visible.

The test suite is split into a fast and a slow half

Contributing to activerecord-tenanted means running one of three commands, and the repository is explicit about which to use when. Fast unit tests run by `bin/test-unit`, slower integration tests run by `bin/test-integration`, and `bin/ci` gives a full test feedback loop.

That split is more informative than it looks. A gem whose central promise is that tenant isolation happens without application code noticing needs integration tests that exercise real requests against real tenant stores, and those are the slow ones. The unit tests cover the pieces in isolation, while `bin/ci` is what you run before opening a pull request. The `bin` directory, the `test` directory and the Rakefile are all present at the root, and there is a `gemfiles` directory alongside an `Appraisals` file, which is the standard Ruby pattern for running the suite against several dependency versions at once. For a gem tied to Rails internals, that matrix is where compatibility regressions will show up, so it is worth checking what Rails versions the appraisal set covers before you rely on it.

MIT terms and a release line below 1.0

Licensing is the easy part. The gem is available as open source under the terms of the MIT License, and the repository carries an MIT-LICENSE file at the root. For a gem intended to sit inside an application you distribute yourself, that is the least surprising outcome and there is nothing in the repository suggesting additional terms or restrictions on use.

The release history is where the caution belongs. The recent tags are v0.7.0 on 2026-06-08, v0.8.0 on 2026-08-04 and v0.9.0 on 2026-10-19, and the last push was on 2026-10-19. Three releases inside roughly four months is a brisk cadence, and it is also a project below 1.0, where the usual convention still applies: minor versions may break compatibility.

The counterweight is the CHANGELOG.md file in the repository root, which is where you would look to see exactly what changed between v0.8.0 and v0.9.0 before upgrading a production application. A gem moving this fast through pre-1.0 versions on a public Rails API means reading the changelog is not optional work, it is part of the upgrade. The other practical cost of this release line is that your Gemfile.lock will be pinned to a version below 1.0, and any team policy about depending on stable APIs has to make an exception for it.

Editorial conclusion

activerecord-tenanted suits a Rails team that wants physical data separation per customer without hand written scoping in every model, and that can live with sqlite3 as the tenant store. It is the wrong choice for a deployment on PostgreSQL or MySQL today, because only sqlite3 is fully supported. Before adopting it, read GUIDE.md for the configuration surface, confirm the adapter your production database uses against the maintainers, and plan for a pre-1.0 API that has already moved through v0.7.0, v0.8.0 and v0.9.0 in 2026 alone.

Frequently asked questions

Official sources

1. basecamp/activerecord-tenanted on GitHub
2. Issues
3. License: MIT
4. README
5. Releases