// the find
citusdata/activerecord-multi-tenant
Rails/ActiveRecord support for distributed multi-tenant databases like Postgres+Citus
A Rails gem that automatically injects tenant_id into ActiveRecord queries so Citus can route them to the right shard without you rewriting every query. Maintained by the Citus team, so it tracks Citus changes directly. Aimed at Rails shops scaling a single-tenant app out to a distributed Postgres cluster.
The query rewriter patches Arel at a low level, meaning existing scopes and associations get tenant filtering for free without model-by-model changes. Write-only mode is a practical migration escape hatch — you can backfill tenant_id in the background before enforcing NOT NULL. Sidekiq middleware is included, which is the most common way tenant context gets silently dropped in background jobs. The test suite runs against real Postgres with the Citus extension, not mocks, so edge cases in query rewriting actually get caught.
Rails support tops out at 7.0 per the README, and Rails 7.1/8 users are on their own — the last push was November 2024 so it's unclear if 7.1+ support landed or was just never documented. Only works with ActiveRecord; if you're using Sequel or a raw query layer for performance-critical paths, you're integrating tenant filtering yourself. There's no built-in support for cross-tenant queries in admin or analytics contexts — the workaround of using tenant_id 0 for 'global' records is a convention, not enforced infrastructure, so it will leak if someone forgets. Citus-specific — if you outgrow it and move to a different sharding strategy, the entire abstraction layer needs to come out.