ec-pg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e69e45c69cb62b8cc005170eadd586bb1d9e5531255aed6c9102130f483ccb2
+  data.tar.gz: 784dd9d174de14fd939609f611cc568f987841d325825889d5fdec9161fef105
+SHA512:
+  metadata.gz: 5b0db8b630775523543fa285d1e19d12812914adac35dda60e801b48375d80c31a413c0e4eb7d245ef3bfe2016421cb49aa43f238daa0de7787ac87c55391fb6
+  data.tar.gz: 1809e37d26dde7ec53fda58133856e62295e6702478d7ea82462965483ec634317c8ff0570aa64d93f6d820674f895197b1a49ede5891e6491df58d015fb6a84

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"ec-pg" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["gmhawash@gmail.com"](mailto:"gmhawash@gmail.com").

data/Guardfile

@@ -0,0 +1,70 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exist?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.call("routing/#{m[1]}_routing"),
+      rspec.spec.call("controllers/#{m[1]}_controller"),
+      rspec.spec.call("acceptance/#{m[1]}")
+    ]
+  end
+
+  # Rails config changes
+  watch(rails.spec_helper)     { rspec.spec_dir }
+  watch(rails.routes)          { "#{rspec.spec_dir}/routing" }
+  watch(rails.app_controller)  { "#{rspec.spec_dir}/controllers" }
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.call("features/#{m[1]}") }
+  watch(rails.layouts)       { |m| rspec.spec.call("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || "spec/acceptance"
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 gmhawash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,254 @@
+# ec-pg
+
+Multi-tenancy for Rails + PostgreSQL. Supports three isolation strategies — schema-per-tenant, database sharding, and row-level security (RLS) — with thread-safe context management and optional Rack middleware for automatic per-request switching.
+
+## Requirements
+
+- Ruby >= 3.2.0
+- Rails / ActiveRecord >= 7.1
+- PostgreSQL adapter (`pg`)
+
+## Installation
+
+```ruby
+gem 'ec-pg', github: 'binnablus/ec-pg'
+```
+
+## Strategies
+
+| Strategy | Isolation level | Best for |
+|---|---|---|
+| Schema-per-tenant | PostgreSQL schema (`search_path`) | Strong isolation, moderate tenant count |
+| Sharding | ActiveRecord multi-database | Horizontal scale, data locality |
+| Row-Level Security | PostgreSQL RLS policies | Lightweight isolation in a shared schema |
+
+The three strategies can be used independently or combined.
+
+---
+
+## Configuration
+
+```ruby
+# config/initializers/ec_pg.rb
+Ec::Pg.configure do |c|
+  c.default_schema    = 'public'        # schema when none is active
+  c.shared_schemas    = ['public']      # always appended to search_path
+  c.number_of_shards  = 4              # total shards in the cluster
+  c.rls_mode          = :local         # :local (per-transaction) or :session
+
+  # Required when using the ContextSwitcher middleware.
+  # Return a hash with :shard and/or :schema keys.
+  c.get_context_method = ->(request) {
+    subdomain = request.host.split('.').first
+    { schema: subdomain }
+  }
+
+  # Paths that bypass context switching (substring match)
+  c.context_switch_exclude_paths = ['health', 'status', 'metrics']
+
+  c.logger = Logger.new($stdout)
+end
+```
+
+---
+
+## Schema-per-tenant
+
+Each tenant lives in its own PostgreSQL schema. The gem sets `search_path` for the duration of a block and restores it automatically.
+
+### Model setup
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include Ec::Pg::SchemaMixin
+  acts_as_namespaced
+end
+```
+
+### Usage
+
+```ruby
+# Block form — preferred
+Ec::Pg::SchemaManager.with_schema('acme') do
+  User.all   # queries acme.users
+end
+
+# Stateful form
+Ec::Pg::SchemaManager.apply!('acme')
+User.all
+Ec::Pg::SchemaManager.reset!
+
+# Inspect current schema
+Ec::Pg::SchemaManager.current_schema  # => 'acme'
+Ec::Pg::SchemaManager.active?         # => true
+```
+
+Schema names are validated (alphanumeric + underscores only) to prevent SQL injection.
+
+---
+
+## Sharding
+
+Wraps ActiveRecord's `connected_to` to route queries to the right shard.
+
+### database.yml
+
+```yaml
+production:
+  primary: &primary
+    adapter: postgresql
+    # ...
+  shard_one:
+    <<: *primary
+    database: app_shard_one
+  shard_two:
+    <<: *primary
+    database: app_shard_two
+```
+
+### Model setup
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include Ec::Pg::ShardMixin
+
+  # :solo — multiple shards pointing to the same DB (dev/test)
+  # :sharded — separate database per shard
+  acts_as_sharded(
+    mode: :sharded,
+    writing_database_identifier: :shard_one,
+    reading_database_identifier: :shard_one_replica   # optional
+  )
+end
+```
+
+### Usage
+
+```ruby
+Ec::Pg::ShardManager.with_shard(:shard_one) do
+  User.all   # routed to shard_one
+end
+
+Ec::Pg::ShardManager.with_shard(:shard_two, role: :reading) do
+  Report.all
+end
+
+Ec::Pg::ShardManager.current_shard   # => :shard_one (or :default)
+```
+
+---
+
+## Row-Level Security
+
+Sets PostgreSQL session variables that your RLS policies can read (e.g. `current_setting('app.tenant_id')`).
+
+### PostgreSQL policy example
+
+```sql
+CREATE POLICY tenant_isolation ON users
+  USING (tenant_id = current_setting('app.tenant_id')::uuid);
+```
+
+### Model setup
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include Ec::Pg::RlsMixin
+
+  acts_as_rls(
+    mode: :local,    # variables reset when transaction ends
+    variables: {
+      tenant_id: 'app.tenant_id',
+      user_id:   'app.user_id'
+    }
+  )
+end
+```
+
+### Usage
+
+```ruby
+User.with_rls(variables: { tenant_id: 'acme-uuid', user_id: 42 }) do
+  User.all   # policy restricts to acme rows
+end
+```
+
+#### Modes
+
+| Mode | Variable lifetime |
+|---|---|
+| `:local` (default) | Reset at transaction end |
+| `:session` | Persist until explicitly cleared |
+
+---
+
+## Combining strategies
+
+Use `Ec::Pg.switch` to set both shard and schema in one call:
+
+```ruby
+Ec::Pg.switch(shard: :shard_two, schema: 'acme') do
+  User.all
+end
+
+# Inspect
+Ec::Pg.current_shard   # => :shard_two
+Ec::Pg.current_schema  # => 'acme'
+```
+
+---
+
+## Rack middleware
+
+Add `ContextSwitcher` to automatically resolve tenant context from each request:
+
+```ruby
+# config/application.rb
+config.middleware.use Ec::Pg::Middleware::ContextSwitcher
+```
+
+`get_context_method` (configured above) is called on every request. If it raises, the middleware returns `422 Unprocessable Entity` with a JSON error body. Paths matching any entry in `context_switch_exclude_paths` bypass the switcher entirely.
+
+---
+
+## Thread safety
+
+Context is stored in thread-local variables. Each thread/fiber has its own isolated context, and block forms (`with_schema`, `with_shard`, `with_rls`) always restore the previous context — even when an exception is raised.
+
+---
+
+## Low-level context API
+
+```ruby
+# Read
+Ec::Pg::Context.shard    # => :shard_one or nil
+Ec::Pg::Context.schema   # => 'acme' or nil
+Ec::Pg::Context.current  # => { shard: :shard_one, schema: 'acme' }
+Ec::Pg::Context.active?  # => true if any key is set
+
+# Write
+Ec::Pg::Context.set(shard: :shard_one, schema: 'acme')
+Ec::Pg::Context.delete(:shard)
+Ec::Pg::Context.clear!
+
+# Temporary override (block-scoped)
+Ec::Pg::Context.with(schema: 'other') { ... }
+```
+
+---
+
+## Development
+
+```bash
+bin/setup       # install dependencies
+rake spec       # run test suite
+bin/console     # interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/binnablus/ec-pg. Contributors are expected to follow the [code of conduct](https://github.com/binnablus/ec-pg/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/config/locales/en.yml

@@ -0,0 +1,2 @@
+en:
+  example: Example

data/lib/ec/pg/configuration.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+#
+module Ec
+  module Pg
+    class Configuration
+      attr_accessor :logger
+      attr_accessor :default_schema
+      attr_accessor :shared_schemas
+      attr_reader :rls_mode
+      attr_reader :number_of_shards
+      attr_reader :get_context_method
+      attr_accessor :context_switch_exclude_paths
+
+      def initialize
+        self.logger = Logger.new($stdout)
+        self.default_schema = 'public'
+        self.number_of_shards = 1
+        self.rls_mode = :local
+        self.context_switch_exclude_paths = []
+      end
+
+      def number_of_shards=(value)
+        if value.is_a?(Integer)
+          @number_of_shards = value 
+        else
+          raise ArgumentError, "'#{value}': number_of_shards must be an integer"
+        end
+      end
+
+      def rls_mode=(value)
+        if RlsMixin::RlsModes.include?(value.to_sym)
+          @rls_mode = value.to_sym
+        else
+          raise ArgumentError, "'#{value}': rls_mode must be :local or :session"
+        end
+      end
+
+      def get_context_method=(value) 
+        if value.is_a?(Proc)
+          @get_context_method = value
+        else
+          raise ArgumentError, "'#{value}': must be a proc or lambda"
+        end
+      end
+    end
+  end
+end

data/lib/ec/pg/context.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Ec
+  module Pg
+    # Thread-safe store for the current multi-tenant context.
+    #
+    # Each key is namespaced under a per-thread hash so that Sidekiq workers,
+    # Puma threads, and Fiber-based servers never bleed context across requests.
+    #
+    # Usage (low-level):
+    #
+    #   Context.set(tenant_id: "abc")
+    #   Context.get(:tenant_id)         # => "abc"
+    #   Context.with(tenant_id: "xyz") { ... }   # restores previous value on exit
+    #   Context.clear!
+    #
+    module Context
+      ThreadKey = :__ec_pg_activerecord_multi_tenant
+      ManagedKeys = %i[shard schema].freeze
+
+      module_function
+
+      # Convenience accessors -------------------------------------------------
+
+      def shard;              get(:shard);             end
+      def shard=(val);        set(shard: val);        end
+      def schema;             get(:schema);            end
+      def schema=(val);       set(schema: val);       end
+
+      # Returns a shallow copy of the entire current context hash.
+      def current
+        store.dup
+      end
+
+      # Returns the value stored under +key+, or +nil+.
+      def get(key)
+        store[key.to_sym]
+      end
+
+      # Stores +value+ under +key+ for the current thread.
+      def set(key_values = {})
+        store.merge!(key_values)
+      end
+
+      # Removes +key+ from the current thread's context.
+      def delete(key)
+        store.delete(key.to_sym)
+      end
+
+      # Yields with +key+ temporarily set to +value+, then restores the
+      # previous value (or removes the key if it wasn't set before).
+      def with(key_values = {})
+        keys = key_values.keys
+        stashed = store.slice(*keys)
+        set(key_values)
+        yield
+      ensure
+        store.except!(*keys)
+        set(stashed)
+        store.compact!
+      end
+
+      def active?
+        ManagedKeys.any? { |k| store.key?(k) }
+      end
+
+      def clear!
+        Thread.current[ThreadKey] = {}
+      end
+
+      def store
+        Thread.current[ThreadKey] ||= {}
+      end
+    end
+  end
+end

data/lib/ec/pg/middleware/context_switcher.rb

@@ -0,0 +1,34 @@
+module Ec 
+  module Pg 
+    class ContextSwitcher 
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        request = ActionDispatch::Request.new(env)
+
+        ignore_paths = Ec::Pg.configuration.context_switch_exclude_paths || []
+
+        if ignore_paths.any? && request.path =~ Regexp.new("^\/(#{ignore_paths.join('|')})")
+          @app.call(env)
+        else
+          context = get_selected_context(request)
+
+          Ec::Pg.switch(shard: context[:shard], schema: context[:schema]) do
+            @app.call(env)
+          end
+        end
+
+      rescue => e
+        Ec::Pg.configuration.logger.error(ActiveSupport::LogSubscriber.new.send(:color, e.inspect, :red))
+        [422, {"Content-Type" => 'application/json'}, [{"message": "Schema Context Not Found"}.to_json]]
+      end
+
+      private
+      def get_selected_context(request)
+        Ec::Pg.configuration.get_context_method.call(request)
+      end
+    end
+  end
+end

data/lib/ec/pg/railtie.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ec
+  module Pg
+    class Railtie < Rails::Railtie
+      # config.before_initialize do
+      #   Ec::Pg.reset!
+      # end
+      #
+      # config.to_prepare do
+      #   Ec::Pg::Schema.init!
+      # end
+      #
+      # config.after_initialize do
+      #   if ENV['AR_DEBUG']
+      #     ActiveSupport::Notifications.subscribe "sql.active_record" do |*args|
+      #       event = ActiveSupport::Notifications::Event.new(*args)
+      #
+      #       event.name      # => "process_action.action_controller"
+      #       event.duration  # => 10 (in milliseconds)
+      #       event.payload   # => {:extra=>information}
+      #
+      #       puts event.payload[:sql].green
+      #       puts event.payload[:connection].instance_variable_get('@config')
+      #     end
+      #   end
+      # end
+      #
+      # rake_tasks do
+      #   load 'tasks/ec-pg-ar.rake'
+      #   if DH::PG.configuration.db_migrate_tenants
+      #     require_relative '../support/migration_tasks_enhancer'
+      #   end
+      # end
+    end
+  end
+end

data/lib/ec/pg/rls_manager.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+module Ec
+  module Pg
+    # Manages ActiveRecord database shard switching.
+    #
+    # Leverages ActiveRecord's native multi-database support (AR 6.1+) via
+    # +connected_to(shard:)+.  Falls back to manual connection swapping for
+    # connection configurations that are not registered as named shards.
+    #
+    # == Configuration in database.yml (Rails multi-db style)
+    #
+    #   production:
+    #     primary:
+    #       <<: *default
+    #       database: app_primary
+    #     db_sharded_shard_1:
+    #       <<: *default
+    #       database: app_shard_one
+    #       migrations_paths: db/migrate_shards
+    #
+    # == Usage
+    #
+    #   ShardManager.with_shard(:shard_one) { User.all }
+    #   ShardManager.with_shard(:shard_one, role: :reading) { User.all }
+    #
+    module RlsManager
+      class UnregisteredVariable < StandardError; end
+      module_function
+
+      # Executes +block+ with the AR connection switched to +shard_name+.
+      #
+      # @param shard_name [Symbol] the registered shard key
+      # @param role       [Symbol] :writing (default) or :reading
+      # @param klass      [Class]  the AR base class whose connection pool to switch
+      #                            (default: ActiveRecord::Base)
+      # @yield  block to run in shard context
+      # @return the return value of +block+
+      def with_rls(rls_mode: nil, registered_variables: {}, variables: {}, connection: nil, &block)
+        connection ||= ActiveRecord::Base.connection 
+        rls_mode ||= Ec::Pg.configuration.rls_mode || :local
+
+        selected_variables = variable_value_for(registered_variables, variables)
+
+        if rls_mode == :local
+          wrap_in_transaction(connection) do
+            apply_rls(connection, rls_mode, selected_variables)
+            block.call
+          end
+        else
+          begin
+            apply_rls(connection, rls_mode, selected_variables)
+            block.call
+          ensure
+            reset!(connection: connection, variables: selected_variables.keys)
+          end
+        end
+      end
+
+      # Resets the RLS variable to its default (empty) value.
+      # For :session mode this uses RESET; for :local mode this is a no-op
+      # because the variable resets automatically at transaction end.
+      def reset!(connection:, variables:)
+        variables.each do |variable|
+          reset_variable!(connection, variable)
+        end
+      end
+
+      private
+      # Executes the SQL to set the RLS variable.
+      def apply_rls(connection, rls_mode, selected_variables)
+        connection.execute(sanitized_query(rls_mode, selected_variables))
+      end
+
+      def sanitized_query(mode, selected_variables)
+        local = if mode == :local 
+          'LOCAL' 
+        end
+
+        selected_variables.map do |variable, value|
+          ("SET %s #{variable} = #{value};" % local).squeeze(' ')
+        end.join(' ')
+      end
+
+      # Wraps the block in a transaction, reusing an existing one if open.
+      def wrap_in_transaction(connection, &block)
+        if connection.transaction_open?
+          block.call
+        else
+          connection.transaction(&block)
+        end
+      end
+      
+      def variable_value_for(registered_variables, variables) 
+        {}.tap do |hash|
+          variables.each do |key, value| 
+            if registered_variables.has_key?(key)
+              hash[registered_variables[key]] = value
+            else 
+              raise UnregisteredVariable, "'#{key}' has not been registered through acts_as_rls."
+            end
+          end
+        end
+      end
+
+      def reset_variable!(connection, variable)
+        connection.execute("RESET #{variable}")
+      rescue StandardError
+        # Swallow reset errors: connection may have been released or variable
+        # may not support RESET (application-level variables cannot be RESET in
+        # some Postgres versions; in that case use SET to empty string instead).
+        begin
+          connection.execute("SET #{variable} TO DEFAULT")
+        rescue StandardError
+          nil
+        end
+      end
+
+      module_function :sanitized_query, :apply_rls, :wrap_in_transaction, :variable_value_for, :reset_variable!
+    end
+  end
+end