ros-apartment 3.1.0 → 3.3.0

data/README.md

@@ -1,7 +1,7 @@
 # Apartment
 
 [![Gem Version](https://badge.fury.io/rb/ros-apartment.svg)](https://badge.fury.io/rb/ros-apartment)
-[![Code Climate](https://api.codeclimate.com/v1/badges/b0dc327380bb8438f991/maintainability)](https://codeclimate.com/github/rails-on-services/apartment/maintainability)
+[![codecov](https://codecov.io/gh/rails-on-services/apartment/graph/badge.svg?token=Q4I5QL78SA)](https://codecov.io/gh/rails-on-services/apartment)
 
 *Multitenancy for Rails and ActiveRecord*
 
@@ -9,21 +9,17 @@ 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.
 
-## Apartment drop in replacement gem
+## Apartment Fork: ros-apartment
 
-After having reached out via github issues and email directly, no replies ever
-came. Since we wanted to upgrade our application to Rails 6 we decided to fork
-and start some development to support Rails 6. Because we don't have access
-to the apartment gem itself, the solution was to release it under a different
-name but providing the exact same API as it was before.
+This gem is a fork of the original Apartment gem, which is no longer maintained. We have continued development under the name `ros-apartment` to keep the gem up-to-date and compatible with the latest versions of Rails. `ros-apartment` is designed as a drop-in replacement for the original, allowing you to seamlessly transition your application without code changes.
 
-## Help wanted
+## Community Support
 
-We were never involved with the development of Apartment gem in the first place
-and this project started out of our own needs. We will be more than happy
-to collaborate to maintain the gem alive and supporting the latest versions
-of ruby and rails, but your help is appreciated. Either by reporting bugs you
-may find or proposing improvements to the gem itself. Feel free to reach out.
+This project thrives on community support. Whether you have an idea for a new feature, find a bug, or need help with `ros-apartment`, we encourage you to participate! For questions and troubleshooting, check out our [Discussions board](https://github.com/rails-on-services/apartment/discussions) to connect with the community. You can also open issues or submit pull requests directly. We are committed to maintaining `ros-apartment` and ensuring it remains a valuable tool for Rails developers.
+
+### Maintainer Update
+
+As of May 2024, Apartment is maintained with the support of [CampusESP](https://www.campusesp.com). We continue to keep Apartment open-source under the MIT license. We also want to recognize and thank the previous maintainers for their valuable contributions to this project.
 
 ## Installation
 
@@ -47,10 +43,6 @@ Configure as needed using the docs below.
 That's all you need to set up the Apartment libraries. If you want to switch tenants
 on a per-user basis, look under "Usage - Switching tenants per request", below.
 
-> NOTE: If using [postgresql schemas](http://www.postgresql.org/docs/9.0/static/ddl-schemas.html) you must use:
->
-> * for Rails 3.1.x: _Rails ~> 3.1.2_, it contains a [patch](https://github.com/rails/rails/pull/3232) that makes prepared statements work with multiple schemas
-
 ## Usage
 
 ### Video Tutorial
@@ -356,7 +348,7 @@ Please note that our custom logger inherits from `ActiveRecord::LogSubscriber` s
 
 **Example log output:**
 
-<img src="documentation/images/log_example.png">
+<img src="docs/images/log_example.png">
 
 ```ruby
 Apartment.configure do |config|
@@ -630,24 +622,50 @@ $ APARTMENT_DISABLE_INIT=true DATABASE_URL=postgresql://localhost:1234/buk_devel
 # 1
 ```
 
-## Contributing
+## Contribution Guidelines
+
+We welcome and appreciate contributions to `ros-apartment`! Whether you want to report a bug, propose a new feature, or submit a pull request, your help keeps this project thriving. Please review the guidelines below to ensure a smooth collaboration process.
+
+### How to Contribute
+
+1. **Check Existing Issues and Discussions**
+   - Before opening a new issue, please check the [issue tracker](https://github.com/rails-on-services/apartment/issues) and our [Discussions board](https://github.com/rails-on-services/apartment/discussions) to see if the topic has already been reported or discussed. This helps us avoid duplication and focus on solving the issue efficiently.
+
+2. **Submitting a Bug Report**
+   - Ensure your report includes a clear description of the problem, steps to reproduce, and relevant logs or error messages.
+   - If possible, provide a minimal reproducible example or a failing test case that demonstrates the issue.
+
+3. **Proposing a Feature**
+   - For new features, open an issue to discuss your idea before starting development. This allows the maintainers and community to provide feedback and ensure the feature aligns with the project's goals.
+   - Please be as detailed as possible when describing the feature, its use case, and its potential impact on the existing functionality.
+
+4. **Submitting a Pull Request**
+   - Fork the repository and create a feature branch (`git checkout -b my-feature-branch`).
+   - Follow the existing code style and ensure your changes are well-documented and tested.
+   - Run the tests locally to verify that your changes do not introduce new issues.
+   - Use [Appraisal](https://github.com/thoughtbot/appraisal) to test against multiple Rails versions. Ensure all tests pass for supported Rails versions.
+   - Submit your pull request to the `development` branch, not `main`.
+   - Include a detailed description of your changes and reference any related issue numbers (e.g., "Fixes #123" or "Closes #456").
+
+5. **Code Review and Merging Process**
+   - The maintainers will review your pull request and may provide feedback or request changes. We appreciate your patience during this process, as we strive to maintain a high standard for code quality.
+   - Once approved, your pull request will be merged into the `development` branch. Periodically, we merge the `development` branch into `main` for official releases.
+
+6. **Testing**
+   - Ensure your code is thoroughly tested. We do not merge code changes without adequate tests. Use RSpec for unit and integration tests.
+   - If your contribution affects multiple versions of Rails, use Appraisal to verify compatibility across versions.
+   - Rake tasks (see the Rakefile) are available to help set up your test databases and run tests.
 
-* In both `spec/dummy/config` and `spec/config`, you will see `database.yml.sample` files
-  * Copy them into the same directory but with the name `database.yml`
-  * Edit them to fit your own settings
-* Rake tasks (see the Rakefile) will help you setup your dbs necessary to run tests
-* Please issue pull requests to the `development` branch. All development happens here, master is used for releases.
-* Ensure that your code is accompanied with tests. No code will be merged without tests
+### Code of Conduct
 
-* If you're looking to help, check out the TODO file for some upcoming changes I'd like to implement in Apartment.
+We are committed to providing a welcoming and inclusive environment for all contributors. Please review and adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) when participating in the project.
 
-### Running bundle install
+### Questions and Support
 
-mysql2 gem in some cases fails to install.
-If you face problems running bundle install in OSX, try installing the gem running:
+If you have any questions or need support while contributing or using `ros-apartment`, visit our [Discussions board](https://github.com/rails-on-services/apartment/discussions) to ask questions and connect with the maintainer team and community.
 
-`gem install mysql2 -v '0.5.3' -- --with-ldflags=-L/usr/local/opt/openssl/lib --with-cppflags=-I/usr/local/opt/openssl/include`
+We look forward to your contributions and thank you for helping us keep `ros-apartment` a reliable and robust tool for the Rails community!
 
 ## License
 
-Apartment is released under the [MIT License](http://www.opensource.org/licenses/MIT).
+Apartment remains an open-source project under the [MIT License](http://www.opensource.org/licenses/MIT). We value open-source principles and aim to make multitenancy accessible to all Rails developers.

data/Rakefile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 begin
-  require 'bundler'
+  require('bundler')
 rescue StandardError
   'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
@@ -13,7 +13,7 @@ require 'appraisal'
 require 'rspec'
 require 'rspec/core/rake_task'
 
-RSpec::Core::RakeTask.new(spec: %w[db:copy_credentials db:test:prepare]) do |spec|
+RSpec::Core::RakeTask.new(spec: %w[db:load_credentials db:test:prepare]) do |spec|
   spec.pattern = 'spec/**/*_spec.rb'
   # spec.rspec_opts = '--order rand:47078'
 end
@@ -26,6 +26,7 @@ namespace :spec do
   end
 end
 
+desc 'Start an interactive console with Apartment loaded'
 task :console do
   require 'pry'
   require 'apartment'
@@ -37,19 +38,36 @@ task default: :spec
 
 namespace :db do
   namespace :test do
-    task prepare: %w[postgres:drop_db postgres:build_db mysql:drop_db mysql:build_db]
+    case ENV.fetch('DATABASE_ENGINE', nil)
+    when 'postgresql'
+      task(prepare: %w[postgres:drop_db postgres:build_db])
+    when 'mysql'
+      task(prepare: %w[mysql:drop_db mysql:build_db])
+    when 'sqlite'
+      task(:prepare) do
+        puts 'No need to prepare sqlite3 database'
+      end
+    else
+      task(:prepare) do
+        puts 'No database engine specified, skipping db:test:prepare'
+      end
+    end
   end
 
   desc "copy sample database credential files over if real files don't exist"
-  task :copy_credentials do
-    require 'fileutils'
-    apartment_db_file = 'spec/config/database.yml'
-    rails_db_file = 'spec/dummy/config/database.yml'
+  task :load_credentials do
+    # If no DATABASE_ENGINE is specified, we default to sqlite so that a db config is generated
+    db_engine = ENV.fetch('DATABASE_ENGINE', 'sqlite')
 
-    unless File.exist?(apartment_db_file)
-      FileUtils.copy("#{apartment_db_file}.sample", apartment_db_file, verbose: true)
-    end
-    FileUtils.copy("#{rails_db_file}.sample", rails_db_file, verbose: true) unless File.exist?(rails_db_file)
+    next unless db_engine && %w[postgresql mysql sqlite].include?(db_engine)
+
+    # Load and write spec db config
+    db_config_string = ERB.new(File.read("spec/config/#{db_engine}.yml.erb")).result
+    File.write('spec/config/database.yml', db_config_string)
+
+    # Load and write dummy app db config
+    db_config = YAML.safe_load(db_config_string)
+    File.write('spec/dummy/config/database.yml', { test: db_config['connections'][db_engine] }.to_yaml)
   end
 end
 
@@ -67,11 +85,11 @@ namespace :postgres do
     params << "-p#{pg_config['port']}" if pg_config['port']
 
     begin
-      `createdb #{params.join(' ')}`
+      system("createdb #{params.join(' ')}")
     rescue StandardError
       'test db already exists'
     end
-    ActiveRecord::Base.establish_connection pg_config
+    ActiveRecord::Base.establish_connection(pg_config)
     migrate
   end
 
@@ -83,7 +101,7 @@ namespace :postgres do
     params << "-U#{pg_config['username']}"
     params << "-h#{pg_config['host']}" if pg_config['host']
     params << "-p#{pg_config['port']}" if pg_config['port']
-    `dropdb #{params.join(' ')}`
+    system("dropdb #{params.join(' ')}")
   end
 end
 
@@ -96,14 +114,14 @@ namespace :mysql do
     params = []
     params << "-h #{my_config['host']}" if my_config['host']
     params << "-u #{my_config['username']}" if my_config['username']
-    params << "-p#{my_config['password']}" if my_config['password']
-    params << "--port #{my_config['port']}" if my_config['port']
+    params << "-p #{my_config['password']}" if my_config['password']
+    params << "-P #{my_config['port']}" if my_config['port']
     begin
-      `mysqladmin #{params.join(' ')} create #{my_config['database']}`
+      system("mysqladmin #{params.join(' ')} create #{my_config['database']}")
     rescue StandardError
       'test db already exists'
     end
-    ActiveRecord::Base.establish_connection my_config
+    ActiveRecord::Base.establish_connection(my_config)
     migrate
   end
 
@@ -113,13 +131,12 @@ namespace :mysql do
     params = []
     params << "-h #{my_config['host']}" if my_config['host']
     params << "-u #{my_config['username']}" if my_config['username']
-    params << "-p#{my_config['password']}" if my_config['password']
-    params << "--port #{my_config['port']}" if my_config['port']
-    `mysqladmin #{params.join(' ')} drop #{my_config['database']} --force`
+    params << "-p #{my_config['password']}" if my_config['password']
+    params << "-P #{my_config['port']}" if my_config['port']
+    system("mysqladmin #{params.join(' ')} drop #{my_config['database']} --force")
   end
 end
 
-# TODO: clean this up
 def config
   Apartment::Test.config['connections']
 end
@@ -133,7 +150,9 @@ def my_config
 end
 
 def migrate
-  # TODO: Figure out if there is any other possibility that can/should be
-  # passed here as the second argument for the migration context
-  ActiveRecord::MigrationContext.new('spec/dummy/db/migrate', ActiveRecord::SchemaMigration).migrate
+  if ActiveRecord.version.release < Gem::Version.new('7.1')
+    ActiveRecord::MigrationContext.new('spec/dummy/db/migrate', ActiveRecord::SchemaMigration).migrate
+  else
+    ActiveRecord::MigrationContext.new('spec/dummy/db/migrate').migrate
+  end
 end

data/docs/adapters.md

@@ -0,0 +1,177 @@
+# Apartment Adapters - Design & Architecture
+
+**Key files**: `lib/apartment/adapters/*.rb`
+
+## Purpose
+
+Adapters translate abstract tenant operations into database-specific implementations. Each database has fundamentally different isolation mechanisms, requiring separate strategies.
+
+## Design Decision: Why Adapter Pattern?
+
+**Problem**: PostgreSQL uses schemas, MySQL uses databases, SQLite uses files. A unified API across these different approaches requires abstraction.
+
+**Solution**: Adapter pattern with shared base class defining lifecycle, database-specific subclasses implementing mechanics.
+
+**Trade-off**: Adds complexity but enables multi-database support without polluting core logic.
+
+## Adapter Hierarchy
+
+See `lib/apartment/adapters/` for implementations:
+- `abstract_adapter.rb` - Shared lifecycle, callbacks, error handling
+- `postgresql_adapter.rb` - Schema-based isolation (3 variants)
+- `mysql2_adapter.rb` - Database-per-tenant
+- `sqlite3_adapter.rb` - File-per-tenant
+- JDBC variants for JRuby
+
+## AbstractAdapter - Design Rationale
+
+**File**: `lib/apartment/adapters/abstract_adapter.rb`
+
+### Why Callbacks?
+
+Provides extension points for logging, notifications, analytics without modifying core adapter code. Users can hook into `:create` and `:switch` events.
+
+### Why Ensure Blocks in switch()?
+
+**Critical decision**: Always rollback to previous tenant, even if block raises. Prevents tenant context leakage across requests/jobs. If rollback fails, fall back to default tenant as last resort.
+
+**Alternative considered**: Let exceptions propagate without cleanup. Rejected because it leaves connections in wrong tenant state.
+
+### Why Query Cache Management?
+
+Rails disables query cache during connection establishment. Must explicitly preserve and restore state across tenant switches to maintain performance.
+
+### Why Separate Connection Handler?
+
+`SeparateDbConnectionHandler` prevents admin operations (CREATE/DROP DATABASE) from polluting the main application connection pool. Multi-server setups especially need this isolation.
+
+## PostgreSQL Adapters - Three Strategies
+
+**Files**: `postgresql_adapter.rb` (3 classes in one file)
+
+### 1. PostgresqlAdapter (Database-per-tenant)
+
+Rarely used. Most deployments use schemas instead.
+
+### 2. PostgresqlSchemaAdapter (Schema-based - Primary)
+
+**Why schemas?**: Single database, multiple namespaces. Fast switching via `SET search_path`. Scales to hundreds of tenants without connection overhead.
+
+**Key design decisions**:
+- **Search path ordering**: Tenant schema first, then persistent schemas, then public. Tables resolve in order.
+- **Persistent schemas**: Shared extensions (PostGIS, uuid-ossp) remain accessible across all tenants.
+- **Excluded model handling**: Explicitly qualify table names with default schema to prevent tenant-based queries.
+
+**Trade-off**: Less isolation than separate databases, but massively better performance and scalability.
+
+### 3. PostgresqlSchemaFromSqlAdapter (pg_dump-based)
+
+**Why pg_dump instead of schema.rb?**:
+- Handles PostgreSQL-specific features (extensions, custom types, constraints) that Rails schema dumper misses
+- Required for PostGIS spatial types
+- Necessary for complex production schemas
+
+**Why patch search_path in dump?**: pg_dump outputs assume specific search_path. Must rewrite SQL to target new tenant schema instead of source schema.
+
+**Why environment variable handling?**: pg_dump shell command reads PGHOST/PGUSER/etc from ENV. Must temporarily set, execute, then restore to avoid polluting global state.
+
+**Alternative considered**: Use Rails schema.rb. Rejected because it loses PostgreSQL-specific features.
+
+## MySQL Adapters - Database Isolation
+
+**Files**: `mysql2_adapter.rb`, `trilogy_adapter.rb`
+
+### Why Separate Databases?
+
+MySQL doesn't have PostgreSQL's robust schema support. Database-level isolation is the natural fit.
+
+**Implications**:
+- Each switch establishes new connection to different database
+- Connection pool per tenant (memory overhead)
+- Practical limit of 10-50 concurrent tenants before connection exhaustion
+
+### Why Trilogy Adapter?
+
+Modern MySQL driver. Identical implementation to Mysql2Adapter, just different gem.
+
+### Multi-Server Support
+
+Hash-based tenant config allows different tenants on different MySQL servers. Enables horizontal scaling and geographic distribution.
+
+## SQLite Adapter - File-Based
+
+**File**: `sqlite3_adapter.rb`
+
+### Why File-Per-Tenant?
+
+SQLite is single-file database. Natural isolation is separate files.
+
+**Use case**: Testing, development, single-user apps. **Not** production multi-tenant.
+
+## Performance Characteristics
+
+**PostgreSQL schemas**:
+- Switch latency: <1ms (SQL command)
+- Scalability: 100+ tenants easily
+- Memory: Constant (~50MB)
+
+**MySQL databases**:
+- Switch latency: 10-50ms (connection establishment)
+- Scalability: 10-50 tenants
+- Memory: ~20MB per active tenant
+
+**SQLite files**:
+- Switch latency: 5-20ms (file I/O)
+- Scalability: Not recommended for concurrent users
+- Memory: ~5MB per database
+
+## Adapter Selection Matrix
+
+| Database   | Strategy     | Speed     | Scalability | Isolation | Best For              |
+|------------|--------------|-----------|-------------|-----------|-----------------------|
+| PostgreSQL | Schemas      | Very Fast | Excellent   | Good      | 100+ tenants          |
+| MySQL      | Databases    | Moderate  | Good        | Excellent | Complete isolation    |
+| SQLite     | Files        | Moderate  | Poor        | Excellent | Testing only          |
+
+## Extension Points
+
+### Creating Custom Adapters
+
+**Why you might need this**: Supporting databases not yet implemented (Oracle, SQL Server, CockroachDB).
+
+**What to implement**:
+1. Subclass `AbstractAdapter`
+2. Define required methods: `create_tenant`, `connect_to_new`, `drop_command`, `current`
+3. Register factory method in `lib/apartment/tenant.rb`
+
+**See**: Existing adapters for patterns. PostgreSQL is most complex, SQLite is simplest.
+
+## Common Pitfalls & Design Constraints
+
+### Why Transaction Handling in create_tenant?
+
+RSpec tests run in transactions. Must detect open transactions and avoid nested BEGIN/COMMIT to prevent errors.
+
+### Why Separate rescue_from per Adapter?
+
+Different databases raise different exceptions. PostgreSQL raises `PG::Error`, MySQL raises different errors. Each adapter specifies what to rescue.
+
+### Why environmentify()?
+
+Prevents tenant name collisions across Rails environments. `development_acme` vs `production_acme`. Optional but recommended for shared infrastructure.
+
+## Thread Safety
+
+**Critical**: Adapters stored in `Thread.current[:apartment_adapter]`. Each thread gets isolated adapter instance.
+
+**Implication**: Safe for multi-threaded servers (Puma), background jobs (Sidekiq).
+
+**Limitation**: Not fiber-safe. v4 refactor addresses this.
+
+## References
+
+- AbstractAdapter implementation: `lib/apartment/adapters/abstract_adapter.rb`
+- PostgreSQL variants: `lib/apartment/adapters/postgresql_adapter.rb`
+- MySQL variants: `lib/apartment/adapters/mysql2_adapter.rb`, `trilogy_adapter.rb`
+- SQLite: `lib/apartment/adapters/sqlite3_adapter.rb`
+- PostgreSQL documentation: https://www.postgresql.org/docs/current/ddl-schemas.html