ros-apartment 3.1.0 → 3.3.0

data/lib/apartment/CLAUDE.md

@@ -0,0 +1,300 @@
+# lib/apartment/ - Core Implementation Directory
+
+This directory contains the core implementation of Apartment v3's multi-tenancy system.
+
+## Directory Structure
+
+```
+lib/apartment/
+├── adapters/              # Database-specific tenant isolation strategies
+├── active_record/         # ActiveRecord patches and extensions
+├── elevators/             # Rack middleware for automatic tenant switching
+├── patches/               # Ruby/Rails core patches
+├── tasks/                 # Rake task utilities
+├── console.rb             # Rails console tenant switching utilities
+├── custom_console.rb      # Enhanced console with tenant prompts
+├── deprecation.rb         # Deprecation warnings configuration
+├── log_subscriber.rb      # ActiveSupport instrumentation for logging
+├── migrator.rb            # Tenant-specific migration runner
+├── model.rb               # ActiveRecord model extensions for excluded models
+├── railtie.rb             # Rails initialization and integration
+├── tenant.rb              # Public API facade for tenant operations
+└── version.rb             # Gem version constant
+```
+
+## Core Files
+
+### tenant.rb - Public API Facade
+
+**Purpose**: Main entry point for all tenant operations. Delegates to appropriate adapter.
+
+**Key methods**:
+- `create(tenant)` - Create new tenant
+- `drop(tenant)` - Delete tenant
+- `switch(tenant)` - Switch to tenant (block-based)
+- `switch!(tenant)` - Immediate switch (no block)
+- `current` - Get current tenant name
+- `reset` - Return to default tenant
+- `each` - Iterate over all tenants
+
+**Adapter delegation pattern**: Uses `Forwardable` to delegate all operations to thread-local adapter instance. See delegation setup in `tenant.rb`.
+
+**Thread-local storage**: Each thread maintains its own adapter via `Thread.current[:apartment_adapter]`. See `Apartment::Tenant.adapter` method for auto-detection logic.
+
+### railtie.rb - Rails Integration
+
+**Purpose**: Integrate Apartment with Rails initialization lifecycle.
+
+**Responsibilities**:
+1. **Configuration loading**: Load `config/initializers/apartment.rb`
+2. **Adapter initialization**: Call `Apartment::Tenant.init` after Rails boot
+3. **Console enhancement**: Add tenant switching helpers to Rails console
+4. **Rake task loading**: Load Apartment rake tasks
+5. **ActiveRecord instrumentation**: Set up logging subscriber
+
+**Key integration points**: See Rails integration hooks in `railtie.rb` (`after_initialize`, `rake_tasks`, `console`).
+
+**Excluded models initialization**: The railtie ensures excluded models establish separate connections after Rails boots but before the application serves requests. See excluded model setup in `railtie.rb`.
+
+### console.rb / custom_console.rb - Interactive Debugging
+
+**console.rb**: Basic console helpers
+**custom_console.rb**: Enhanced prompt showing current tenant
+
+**Features**:
+- Display current tenant in prompt
+- Quick switching helpers
+- Tenant listing commands
+
+**Implementation**: See `console.rb` and `custom_console.rb` for prompt customization and helper methods.
+
+### migrator.rb - Tenant Migration Runner
+
+**Purpose**: Run migrations across all tenants.
+
+**Key functionality**:
+- Detect pending migrations per tenant
+- Run migrations in tenant context
+- Handle migration failures gracefully
+- Support parallel migration execution
+
+**Integration**: Used by `rake apartment:migrate` task. See migration coordination logic in `migrator.rb` and task definitions in `tasks/enhancements.rake`.
+
+**Parallel execution**: If `config.parallel_migration_threads > 0`, spawns threads to migrate multiple tenants concurrently. See parallel execution logic in `migrator.rb`.
+
+### model.rb - Excluded Model Behavior
+
+**Purpose**: Provide base module/behavior for excluded models.
+
+**Functionality**:
+- Establish separate connection to default database
+- Bypass tenant switching
+- Maintain global data across tenants
+
+**Behavior**: When a model is in `Apartment.excluded_models`, it automatically establishes connection to default database and bypasses tenant switching. See connection handling in `model.rb` and `AbstractAdapter#process_excluded_models`.
+
+### log_subscriber.rb - Instrumentation
+
+**Purpose**: Subscribe to ActiveSupport notifications for logging tenant operations.
+
+**Events logged**:
+- Tenant creation
+- Tenant switching
+- Tenant deletion
+- Migration execution
+
+**Configuration**: Set `config.active_record_log = true` to enable. See event subscriptions in `log_subscriber.rb` and configuration options in `lib/apartment.rb`.
+
+### version.rb - Version Management
+
+**Purpose**: Define gem version constant. Used by gemspec and for version checking. See `version.rb`.
+
+### deprecation.rb - Deprecation Warnings
+
+**Purpose**: Configure ActiveSupport::Deprecation for Apartment.
+
+**Implementation**: Sets up deprecation warnings targeting v4.0. See `deprecation.rb` for DEPRECATOR constant.
+
+## Subdirectories
+
+### adapters/
+
+Database-specific implementations of tenant operations. See `lib/apartment/adapters/CLAUDE.md`.
+
+**Key files**:
+- `abstract_adapter.rb` - Base adapter with common logic
+- `postgresql_adapter.rb` - PostgreSQL schema-based isolation
+- `mysql2_adapter.rb` - MySQL database-based isolation
+- `sqlite3_adapter.rb` - SQLite file-based isolation
+
+### active_record/
+
+ActiveRecord patches and extensions for tenant-aware behavior. See `lib/apartment/active_record/CLAUDE.md`.
+
+**Key files**:
+- `connection_handling.rb` - Patches to AR connection management
+- `schema_migration.rb` - Tenant-aware schema_migrations table
+- `postgresql_adapter.rb` - PostgreSQL-specific AR extensions
+- `postgres/schema_dumper.rb` - Custom schema dumping (Rails 7.1+)
+
+### elevators/
+
+Rack middleware for automatic tenant detection. See `lib/apartment/elevators/CLAUDE.md`.
+
+**Key files**:
+- `generic.rb` - Base elevator with customizable logic
+- `subdomain.rb` - Switch based on subdomain
+- `domain.rb` - Switch based on domain
+- `host.rb` - Switch based on full hostname
+- `host_hash.rb` - Switch based on hostname→tenant mapping
+
+### tasks/
+
+Rake task utilities and enhancements.
+
+**Key files**:
+- `enhancements.rb` - Rake task definitions (migrate, seed, create, drop)
+- `task_helper.rb` - Shared task utilities
+
+## Data Flow
+
+### Tenant Creation Flow
+
+1. User calls `Apartment::Tenant.create('acme')`
+2. Delegates to adapter which executes callbacks, creates schema/database, imports schema, optionally runs seeds
+3. Returns to user code
+
+**See**: `Apartment::Tenant.create` and `AbstractAdapter#create` for orchestration.
+
+### Tenant Switching Flow
+
+1. User calls `Apartment::Tenant.switch('acme') { ... }`
+2. Adapter stores current tenant, switches connection, yields to block, ensures rollback in ensure clause
+3. Returns to user code with tenant automatically restored
+
+**See**: `AbstractAdapter#switch` method for implementation.
+
+### Request Processing Flow (with Elevator)
+
+1. HTTP Request arrives
+2. Elevator extracts tenant, calls `Apartment::Tenant.switch`
+3. Application processes in tenant context
+4. Elevator ensures tenant reset
+
+**See**: `elevators/generic.rb` for middleware pattern.
+
+## Thread Safety
+
+### Current Implementation (v3)
+
+**Thread-local adapter storage**: Uses `Thread.current[:apartment_adapter]` for isolation.
+
+**Implications**:
+- ✅ Each thread has isolated tenant context
+- ✅ Safe for multi-threaded servers (Puma)
+- ✅ Safe for background jobs (Sidekiq)
+- ❌ NOT fiber-safe (fibers share thread storage)
+- ❌ Global mutable state within thread
+
+**See**: `Apartment::Tenant.adapter` method for thread-local implementation.
+
+## Configuration Integration
+
+### Loading Process
+
+1. Rails boots
+2. `config/initializers/apartment.rb` loads
+3. `Apartment.configure` executes
+4. Configuration stored in module instance variables
+5. `Railtie.after_initialize` fires
+6. `Apartment::Tenant.init` called
+7. Excluded models processed
+8. Adapter initialized (lazy, on first use)
+
+**See**: Configuration methods in `lib/apartment.rb` and initialization hooks in `railtie.rb`.
+
+### Configuration Access
+
+Available configuration methods: `Apartment.tenant_names`, `Apartment.excluded_models`, `Apartment.connection_class`, `Apartment.db_migrate_tenants`. See `lib/apartment.rb` for all configuration options.
+
+## Error Handling
+
+### Exception Hierarchy
+
+- `Apartment::ApartmentError` - Base exception for all Apartment errors
+- `Apartment::TenantNotFound` - Raised when switching to nonexistent tenant
+- `Apartment::TenantExists` - Raised when creating duplicate tenant
+
+**See**: Adapter `connect_to_new` methods raise `TenantNotFound`. See `AbstractAdapter#switch` for error handling.
+
+### Automatic Cleanup
+
+The `switch` method guarantees cleanup via ensure block, falling back to default tenant if rollback fails. See `AbstractAdapter#switch` for implementation.
+
+## Extending Apartment
+
+### Adding Custom Adapter
+
+1. Create file: `lib/apartment/adapters/custom_adapter.rb`
+2. Subclass `AbstractAdapter`
+3. Implement required methods
+4. Add factory method to `tenant.rb`
+
+See `docs/adapters.md` for details.
+
+### Adding Custom Elevator
+
+1. Create file: `app/middleware/custom_elevator.rb`
+2. Subclass `Apartment::Elevators::Generic`
+3. Override `parse_tenant_name(request)`
+4. Add to middleware stack in `config/application.rb`
+
+See `docs/elevators.md` for details.
+
+### Adding Custom Callbacks
+
+Use ActiveSupport::Callbacks to hook into `:create` and `:switch` events. See callback definitions in `AbstractAdapter` and README.md for configuration examples.
+
+## Testing Considerations
+
+### RSpec Integration
+
+Always reset tenant context in before/after hooks to prevent test isolation issues. See `spec/support/` for helper modules and `spec/spec_helper.rb` for configuration patterns.
+
+### Creating Test Tenants
+
+Create helpers for tenant lifecycle management to avoid duplication. See `spec/support/apartment_helper.rb` for patterns.
+
+## Debugging Tips
+
+### Enable Verbose Logging
+
+Set `config.active_record_log = true` in initializer. See logging configuration in `lib/apartment.rb`.
+
+### Check Current Tenant
+
+Use `Apartment::Tenant.current` to inspect current tenant context.
+
+### Inspect Adapter
+
+Access `Apartment::Tenant.adapter` to inspect adapter class and configuration.
+
+### Verify Excluded Models
+
+Iterate `Apartment.excluded_models` and check each model's connection configuration.
+
+## Common Pitfalls
+
+1. **Not using block-based switching**: Always use `switch` with block, not `switch!`
+2. **Elevator positioning**: Must be before session/auth middleware
+3. **Excluded model relationships**: Use `has_many :through`, not `has_and_belongs_to_many`
+4. **Thread safety assumptions**: Remember adapters are thread-local, not global
+5. **Forgetting to reset**: In tests, always reset tenant in teardown
+
+## References
+
+- Main README: `/README.md`
+- Architecture docs: `/docs/architecture.md`
+- Adapter docs: `/docs/adapters.md`
+- Elevator docs: `/docs/elevators.md`
+- ActiveRecord connection handling: Rails guides

data/lib/apartment/active_record/connection_handling.rb

@@ -15,10 +15,10 @@ module ActiveRecord # :nodoc:
         end
       end
     else
-      def connected_to_with_tenant(role: nil, prevent_writes: false, &blk)
+      def connected_to_with_tenant(role: nil, shard: nil, prevent_writes: false, &blk)
         current_tenant = Apartment::Tenant.current
 
-        connected_to_without_tenant(role: role, prevent_writes: prevent_writes) do
+        connected_to_without_tenant(role: role, shard: shard, prevent_writes: prevent_writes) do
           Apartment::Tenant.switch!(current_tenant)
           yield(blk)
         end

data/lib/apartment/active_record/postgres/schema_dumper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# This patch prevents `create_schema` from being added to db/schema.rb as schemas are managed by Apartment
+# not ActiveRecord like they would be in a vanilla Rails setup.
+
+require 'active_record/connection_adapters/abstract/schema_dumper'
+require 'active_record/connection_adapters/postgresql/schema_dumper'
+
+module ActiveRecord
+  module ConnectionAdapters
+    module PostgreSQL
+      class SchemaDumper
+        alias _original_schemas schemas
+        def schemas(stream)
+          _original_schemas(stream) unless Apartment.use_schemas
+        end
+      end
+    end
+  end
+end

data/lib/apartment/active_record/postgresql_adapter.rb

@@ -12,23 +12,38 @@ module Apartment::PostgreSqlAdapterPatch
     # for JDBC driver, if rescued in super_method, trim leading and trailing quotes
     res.delete!('"') if defined?(JRUBY_VERSION)
 
-    schema_prefix = "#{Apartment::Tenant.current}."
-    default_tenant_prefix = "#{Apartment::Tenant.default_tenant}."
+    schema_prefix = "#{sequence_schema(res)}."
 
     # NOTE: Excluded models should always access the sequence from the default
     # tenant schema
     if excluded_model?(table)
-      res.sub!(schema_prefix, default_tenant_prefix) if schema_prefix != default_tenant_prefix
+      default_tenant_prefix = "#{Apartment::Tenant.default_tenant}."
+
+      # Unless the res is already prefixed with the default_tenant_prefix
+      # we should delete the schema_prefix and add the default_tenant_prefix
+      unless res&.starts_with?(default_tenant_prefix)
+        res&.delete_prefix!(schema_prefix)
+        res = default_tenant_prefix + res
+      end
+
       return res
     end
 
-    res.delete_prefix!(schema_prefix) if res&.starts_with?(schema_prefix)
+    # Delete the schema_prefix from the res if it is present
+    res&.delete_prefix!(schema_prefix)
 
     res
   end
 
   private
 
+  def sequence_schema(sequence_name)
+    current = Apartment::Tenant.current
+    return current unless current.is_a?(Array)
+
+    current.find { |schema| sequence_name.starts_with?("#{schema}.") }
+  end
+
   def excluded_model?(table)
     Apartment.excluded_models.any? { |m| m.constantize.table_name == table }
   end

data/lib/apartment/adapters/CLAUDE.md

@@ -0,0 +1,314 @@
+# lib/apartment/adapters/ - Database Adapter Implementations
+
+This directory contains database-specific implementations of tenant isolation strategies.
+
+## Purpose
+
+Adapters translate abstract tenant operations (create, switch, drop) into database-specific SQL commands and connection management.
+
+## File Structure
+
+```
+adapters/
+├── abstract_adapter.rb          # Base class with shared logic
+├── postgresql_adapter.rb         # PostgreSQL schema-based isolation
+├── postgis_adapter.rb           # PostgreSQL with PostGIS extensions
+├── mysql2_adapter.rb            # MySQL database-based isolation (mysql2 gem)
+├── trilogy_adapter.rb           # MySQL database-based isolation (trilogy gem)
+├── sqlite3_adapter.rb           # SQLite file-based isolation
+├── abstract_jdbc_adapter.rb     # Base for JDBC adapters (JRuby)
+├── jdbc_postgresql_adapter.rb   # JDBC PostgreSQL adapter
+└── jdbc_mysql_adapter.rb        # JDBC MySQL adapter
+```
+
+## Adapter Hierarchy
+
+```
+AbstractAdapter
+├── PostgresqlAdapter
+│   ├── PostgisAdapter (PostgreSQL + spatial extensions)
+│   └── JdbcPostgresqlAdapter (JDBC for JRuby)
+├── Mysql2Adapter
+│   ├── TrilogyAdapter (alternative MySQL driver)
+│   └── JdbcMysqlAdapter (JDBC for JRuby)
+└── Sqlite3Adapter
+```
+
+## AbstractAdapter - Base Implementation
+
+**Location**: `abstract_adapter.rb`
+
+### Responsibilities
+
+1. **Common tenant lifecycle logic**:
+   - Callback execution (`:create`, `:switch`)
+   - Schema import coordination
+   - Seed data execution
+   - Exception handling
+
+2. **Excluded model management**:
+   - Establish separate connections for excluded models
+   - Ensure they bypass tenant switching
+
+3. **Helper methods**:
+   - `environmentify(tenant)` - Add Rails env to tenant name
+   - `seed_data` - Load seeds.rb in tenant context
+   - `each(tenants)` - Iterate over tenants
+
+### Abstract Methods (Subclasses Must Implement)
+
+- `create_tenant(tenant)` - Create the tenant (schema/database/file)
+- `connect_to_new(tenant)` - Switch to tenant (change connection or search_path)
+- `drop_command(conn, tenant)` - Drop the tenant
+- `current` - Get current tenant name
+
+**See**: Abstract method definitions in `abstract_adapter.rb`.
+
+### Common Logic Provided
+
+**Tenant creation**: Runs callbacks, creates tenant via subclass, switches context, imports schema, optionally seeds data. See `AbstractAdapter#create` method.
+
+**Tenant switching**: Stores previous tenant, switches, yields to block, ensures rollback in ensure clause with fallback to default. See `AbstractAdapter#switch` method.
+
+**Schema import**: Loads `db/schema.rb` or custom schema file. See schema import logic in `abstract_adapter.rb`.
+
+### Helper Methods
+
+**Environmentify**: Adds Rails environment prefix/suffix to tenant name based on configuration. See `AbstractAdapter#environmentify` method.
+
+**Excluded model processing**: Establishes separate connections for excluded models. See `AbstractAdapter#process_excluded_models` method.
+
+## PostgreSQL Adapter
+
+**Location**: `postgresql_adapter.rb`
+
+### Strategy
+
+Uses **PostgreSQL schemas** (namespaces) for tenant isolation.
+
+### Key Implementation Details
+
+**Create tenant**: Executes `CREATE SCHEMA` SQL command. See `PostgresqlAdapter#create_tenant` method.
+
+**Switch tenant**: Changes `search_path` to target schema. See `PostgresqlAdapter#connect_to_new` method.
+
+**Drop tenant**: Executes `DROP SCHEMA CASCADE`. See `PostgresqlAdapter#drop_command` method.
+
+**Get current tenant**: Returns instance variable tracking current schema. See `PostgresqlAdapter#current` method.
+
+### Search Path Mechanics
+
+PostgreSQL searches schemas in order defined by `search_path`. Queries resolve to first matching table. Search path includes tenant schema, persistent schemas, then public. See search path construction in `PostgresqlAdapter#connect_to_new`.
+
+### Persistent Schemas
+
+Configured via `config.persistent_schemas` to specify schemas that remain in search path across all tenants.
+
+**Use cases**:
+- Shared PostgreSQL extensions (uuid-ossp, hstore, postgis)
+- Utility functions/views shared across tenants
+- Reference data tables
+
+**See**: README.md for configuration examples.
+
+### Excluded Names (pg_excluded_names)
+
+Configured via `config.pg_excluded_names` to exclude tables/schemas from tenant cloning.
+
+**Use cases**:
+- Temporary tables
+- Backup tables
+- Staging/import tables
+
+**See**: README.md for configuration patterns.
+
+### Performance Characteristics
+
+- **Switching**: <1ms (SQL command)
+- **Memory**: ~50MB total (shared connection pool)
+- **Scalability**: 100+ tenants easily
+- **Isolation**: Schema-level (good, not absolute)
+
+## PostGIS Adapter
+
+**Location**: `postgis_adapter.rb`
+
+### Strategy
+
+Extends `PostgresqlAdapter` with PostGIS spatial extension support.
+
+### Key Differences
+
+**Tenant creation**: Extends base PostgresqlAdapter to automatically enable PostGIS extensions in new schemas. See `PostgisAdapter#create_tenant` method.
+
+**Schema dumping**: Custom logic to handle spatial types and indexes correctly. See `active_record/postgres/schema_dumper.rb`.
+
+### Configuration
+
+Typically includes PostGIS-related schemas in `persistent_schemas`. See README.md for configuration.
+
+## MySQL Adapters
+
+**Locations**: `mysql2_adapter.rb`, `trilogy_adapter.rb`
+
+### Strategy
+
+Uses **separate databases** for each tenant.
+
+### Key Implementation Details
+
+**Create tenant**: Executes `CREATE DATABASE` SQL command. See `Mysql2Adapter#create_tenant` method.
+
+**Switch tenant**: Establishes new connection with different database name. See `Mysql2Adapter#connect_to_new` method.
+
+**Drop tenant**: Executes `DROP DATABASE`. See `Mysql2Adapter#drop_command` method.
+
+**Get current database**: Queries current database name from connection. See `Mysql2Adapter#current` method.
+
+### Connection Management
+
+Each tenant switch establishes new connection to different database. This creates connection pool overhead compared to PostgreSQL schemas. See `Mysql2Adapter#connect_to_new` for connection establishment.
+
+### Multi-Server Support
+
+MySQL adapters support hash-based configuration mapping tenant names to full connection configs, enabling different tenants on different servers. See README.md for configuration examples.
+
+### Performance Characteristics
+
+- **Switching**: 10-50ms (connection establishment)
+- **Memory**: ~20MB per active tenant (connection pool)
+- **Scalability**: 10-50 concurrent tenants
+- **Isolation**: Database-level (excellent)
+
+### Trilogy Adapter
+
+**Location**: `trilogy_adapter.rb`
+
+Identical to `Mysql2Adapter` but uses the `trilogy` gem (modern MySQL client).
+
+**Usage**: Auto-selected if `adapter: trilogy` in `database.yml`.
+
+## SQLite Adapter
+
+**Location**: `sqlite3_adapter.rb`
+
+### Strategy
+
+Uses **separate database files** for each tenant.
+
+### Key Implementation Details
+
+**Create tenant**: Creates new SQLite file and establishes connection. See `Sqlite3Adapter#create_tenant` method.
+
+**Switch tenant**: Establishes connection to different database file. See `Sqlite3Adapter#connect_to_new` method.
+
+**Drop tenant**: Deletes database file. See `Sqlite3Adapter#drop_command` method.
+
+**Database file path**: Constructs file path in db/ directory. See file path construction in `Sqlite3Adapter`.
+
+### Use Cases
+
+- ✅ **Testing**: Each test tenant is isolated file
+- ✅ **Development**: Easy to inspect individual tenant data
+- ✅ **Single-user apps**: Desktop or embedded applications
+- ❌ **Production**: Not suitable for concurrent multi-user access
+
+### Performance Characteristics
+
+- **Switching**: 5-20ms (file I/O + connection)
+- **Memory**: ~5MB per database file
+- **Scalability**: Not recommended for production multi-tenant
+- **Isolation**: Complete (separate files)
+
+## JDBC Adapters (JRuby)
+
+**Locations**: `abstract_jdbc_adapter.rb`, `jdbc_postgresql_adapter.rb`, `jdbc_mysql_adapter.rb`
+
+### Purpose
+
+Support JRuby deployments using JDBC drivers.
+
+### Implementation
+
+Inherit from standard adapters but use JDBC-specific connection handling. See `jdbc_postgresql_adapter.rb` and `jdbc_mysql_adapter.rb`.
+
+### Auto-Detection
+
+JRuby detection happens in `tenant.rb` - automatically selects JDBC adapters when running on JRuby. See adapter factory logic in `Apartment::Tenant.adapter_method`.
+
+## Adapter Selection Matrix
+
+| Adapter                | Database Type | Strategy     | Speed        | Scalability | Isolation | Best For                |
+|------------------------|---------------|--------------|--------------|-------------|-----------|-------------------------|
+| PostgresqlAdapter      | PostgreSQL    | Schemas      | Very Fast    | Excellent   | Good      | 100+ tenants            |
+| PostgisAdapter         | PostGIS       | Schemas      | Very Fast    | Excellent   | Good      | Spatial data apps       |
+| Mysql2Adapter          | MySQL         | Databases    | Moderate     | Good        | Excellent | Complete isolation      |
+| TrilogyAdapter         | MySQL         | Databases    | Moderate     | Good        | Excellent | Modern MySQL client     |
+| Sqlite3Adapter         | SQLite        | Files        | Moderate     | Poor        | Excellent | Testing, development    |
+| JdbcPostgresqlAdapter  | PostgreSQL    | Schemas      | Very Fast    | Excellent   | Good      | JRuby deployments       |
+| JdbcMysqlAdapter       | MySQL         | Databases    | Moderate     | Good        | Excellent | JRuby deployments       |
+
+## Creating Custom Adapters
+
+To support new databases: subclass `AbstractAdapter`, implement required methods (`create_tenant`, `connect_to_new`, `drop_command`, `current`), register factory method in `tenant.rb`, and configure in `database.yml`.
+
+**See**: Existing adapters for patterns (`postgresql_adapter.rb` is most complex, `sqlite3_adapter.rb` is simplest), and `docs/adapters.md` for design rationale.
+
+## Testing Adapters
+
+### Adapter-Specific Tests
+
+Each adapter has comprehensive specs covering tenant creation, switching, deletion, error handling, and callbacks. See `spec/adapters/` for test patterns.
+
+## Debugging Adapters
+
+### Check Current Adapter
+
+Use `Apartment::Tenant.adapter.class.name` to inspect adapter type.
+
+### Inspect Configuration
+
+Access `adapter.instance_variable_get(:@config)` for configuration and `adapter.default_tenant` for default.
+
+### Database-Specific Debugging
+
+**PostgreSQL**: Execute `SHOW search_path` to verify current schema search path.
+
+**MySQL**: Execute `SELECT DATABASE()` to verify current database name.
+
+## Common Issues
+
+### Issue: Schema/Database Not Created
+
+**Cause**: Permissions, invalid names, or database errors
+
+**Debug**: Wrap `Apartment::Tenant.create` in rescue block and inspect exception class and message.
+
+### Issue: Switching Fails
+
+**Cause**: Tenant doesn't exist or connection issues
+
+**Debug**: Verify tenant in `Apartment.tenant_names` and check `adapter.current` state.
+
+### Issue: Wrong Data After Switch
+
+**Cause**: Improper cleanup or middleware ordering
+
+**Solution**: Always use block-based switching, verify middleware order.
+
+## Performance Optimization
+
+### PostgreSQL: Connection Pooling
+
+PostgreSQL adapters use shared connection pool across all tenants. Configure pool size in `database.yml`. See Rails connection pooling guides.
+
+### MySQL: Connection Pool Caching
+
+Consider implementing LRU cache for connection pools to limit memory usage with many tenants. Not implemented in v3 but possible via custom adapter.
+
+## References
+
+- PostgreSQL schemas: https://www.postgresql.org/docs/current/ddl-schemas.html
+- MySQL databases: https://dev.mysql.com/doc/refman/8.0/en/creating-database.html
+- ActiveRecord adapters: Rails source code
+- AbstractAdapter source: `abstract_adapter.rb`