familia 2.0.0.pre26 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e53524562d8d882f297dfff646ee905a2cba7fc887b00640ab80bed510de8c1c
-  data.tar.gz: 823ee307f5b4ce938a3970c4872b45351d87f7af8225d8bd98820f8f73eb4229
+  metadata.gz: e83013bddd8ff985ad1cd9ef73421146b5fea6c35cbb77aa0cf12656dd270f68
+  data.tar.gz: ba7ebef4af806d823317fd41e1875733b12971b3c6321e841c9ecbf0c9d727a0
 SHA512:
-  metadata.gz: 51bb9a24cb6d83caa6ca1574358a0c3a93bc6735f65294a45132e0d415c1494e97c092f9263457f49e2895dc56120ba0f384f1df7b29713784b2cd6fd1d4b8f5
-  data.tar.gz: 7fd5600d88b2ae5fd6971002d57f16094e59f4813b8a720cdc75fcdaac77e225384b0458c4a40b89bdc396e688ff677f86c75dfa19fc0e523fbd276369d2493f
+  metadata.gz: 126d79d60cad6c4ed4ed03a557f4435aec82d03ef2230ad64e4d2205f8c8856cc74b140c18fb5f1d567631f203f6b259e7d19d0bed8f36e09b5540fc004f4e6d
+  data.tar.gz: cb5a52b4622c9f193d3858b0f2766795f49000f56fccbffdc630dc5b05e68db0a8c200ad25137bf543d9fc64ee2f53cab891517a5d9f91c2dd8debeb2119b7e7

data/CHANGELOG.rst

@@ -7,6 +7,100 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.1.0:
+
+2.1.0 — 2026-02-01
+==================
+
+Added
+-----
+
+- Redis-native migration system with three patterns: Base (abstract foundation),
+  Model (record-by-record iteration via SCAN), and Pipeline (bulk updates with
+  Redis pipelining). Includes dependency resolution using topological sort,
+  dry-run mode, CLI support, and comprehensive Rake tasks.
+
+- Migration registry for tracking applied migrations in Redis with rollback
+  support and schema drift detection.
+
+- Lua script framework with atomic operations: rename_field, copy_field,
+  delete_field, rename_key_preserve_ttl, and backup_and_modify_field.
+
+- Optional JSON Schema validation for Horreum models via ``feature :schema_validation``
+  with centralized SchemaRegistry supporting convention-based and explicit schema
+  discovery using the json_schemer gem.
+
+- V1 to V2 serialization migration example at ``examples/migrations/v1_to_v2_serialization_migration.rb``
+  demonstrating how to upgrade Horreum objects from v1.x format (selective serialization
+  with type information loss) to v2.0 format (universal JSON encoding with type preservation).
+  Includes type detection heuristics, field type declarations, and batch processing.
+
+Documentation
+-------------
+
+- Added comprehensive migration writing guide at ``docs/guides/writing-migrations.md``
+  covering all three migration patterns, CLI usage, dependencies, and best practices.
+
+AI Assistance
+-------------
+
+- Claude Code assisted with test coverage analysis, identifying gaps in Model and
+  Pipeline test coverage. Implemented 67 new tests covering CLI entry points,
+  circular dependency detection, and comprehensive Model/Pipeline scenarios.
+
+- Claude Code identified and fixed a bug where schema validation hooks were never
+  triggered in Model migrations, and optimized N+1 query patterns in Registry and
+  Runner classes.
+
+.. _changelog-2.0.0:
+
+2.0.0 — 2026-01-19
+==================
+
+Familia 2.0.0 represents a complete rewrite of the library with 26 pre-release
+iterations incorporating community feedback and production testing.
+
+Added
+-----
+
+- **Modular Feature System**: Autoloading features with ancestry chain traversal
+  (``feature :expiration``, ``feature :relationships``, etc.)
+- **Unified Relationships API**: ``participates_in`` replaces ``tracked_in``/``member_of``
+  with bidirectional reverse lookups (``_instances`` suffix methods)
+- **Type-Safe Serialization**: JSON encoding preserves Integer, Boolean, Float,
+  Hash, Array types across Redis boundary
+- **Performance Optimizations**: Pipelined bulk loading (``load_multi``),
+  optional EXISTS check (``check_exists: false``), OJ JSON for 2-5× faster operations
+- **Security Features**: VerifiableIdentifier with HMAC signatures,
+  ExternalIdentifier with format flexibility, encrypted fields with key rotation
+- **Thread Safety**: Mutex initialization fixes, 56-test thread safety suite
+- **Instrumentation**: ``Familia.on_command``, ``Familia.on_pipeline``,
+  ``Familia.on_lifecycle`` hooks for monitoring
+
+Changed
+-------
+
+- **BREAKING**: DataType class renaming to avoid Ruby namespace conflicts
+  (``Familia::String`` → ``Familia::StringKey``, etc.)
+- **BREAKING**: Removed ``dump_method``/``load_method`` - JSON serialization is now standard
+- **BREAKING**: Indexing API renamed (``class_indexed_by`` → ``unique_index``,
+  ``indexed_by`` → ``multi_index``)
+
+Documentation
+-------------
+
+- Archived 11 pre-release migration guides to ``docs/.archive/``
+- Enhanced ``api-technical.md`` with bulk loading, EXISTS optimization,
+  per-class feature registration, and index rebuilding documentation
+- Updated version references and fixed broken anchor links throughout docs
+
+AI Assistance
+-------------
+
+- Claude Opus 4.5 coordinated 11 parallel code-explorer agents to evaluate
+  migration docs, identifying unique content to preserve before archiving.
+  Assisted with release statistics gathering and documentation consolidation.
+
 .. _changelog-2.0.0.pre26:
 
 2.0.0.pre26 — 2026-01-19

data/Gemfile

@@ -13,7 +13,10 @@ group :test do
 end
 
 group :development, :test do
+  gem 'benchmark', '~> 0.4', require: false
   gem 'debug', require: false
+  gem 'json_schemer', '~> 2.0', require: false
+  gem 'rake', '~> 13.0', require: false
   gem 'irb', '~> 1.15.2', require: false
   gem 'redcarpet', require: false
   gem 'reek', require: false

data/Gemfile.lock

@@ -1,8 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre26)
-      benchmark (~> 0.4)
+    familia (2.1.0)
       concurrent-ruby (~> 1.3)
       connection_pool (~> 2.5)
       csv (~> 3.3)
@@ -59,12 +58,18 @@ GEM
     erb (5.1.3)
     ffi (1.17.2)
     ffi (1.17.2-arm64-darwin)
+    hana (1.3.7)
     io-console (0.8.1)
     irb (1.15.3)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
     json (2.15.1)
+    json_schemer (2.5.0)
+      bigdecimal
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      simpleidn (~> 0.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -88,6 +93,7 @@ GEM
       stringio
     racc (1.8.1)
     rainbow (3.1.1)
+    rake (13.3.1)
     rbnacl (7.1.2)
       ffi (~> 1)
     rbs (3.9.5)
@@ -153,6 +159,7 @@ GEM
     ruby-prof (1.7.2)
       base64
     ruby-progressbar (1.13.0)
+    simpleidn (0.2.3)
     stackprof (0.2.27)
     stringio (3.1.9)
     timecop (0.9.10)
@@ -181,10 +188,13 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  benchmark (~> 0.4)
   concurrent-ruby (~> 1.3.5)
   debug
   familia!
   irb (~> 1.15.2)
+  json_schemer (~> 2.0)
+  rake (~> 13.0)
   rbnacl (~> 7.1, >= 7.1.1)
   redcarpet
   reek

data/README.md

@@ -4,8 +4,6 @@
 
 Familia provides object-oriented access to Valkey/Redis using their database types. Unlike traditional ORMs that map objects to relational tables, Familia maps Ruby objects directly to Valkey's native data structures (strings, lists, sets, sorted sets, hashes) as instance variables.
 
-> [!CAUTION]
-> Familia 2 is in pre-release and not ready for production use. (October 2025)
 ## Traditional ORM vs Familia
 
 **Traditional ORMs** convert your objects to SQL tables. A product with categories becomes two tables with a join table. Checking if a tag exists requires a query with joins.
@@ -140,7 +138,7 @@ user.tags?                       # Check if it's a Set type
 
 ## Prerequisites
 
-- **Ruby**: 3.4+ (3.4+ recommended)
+- **Ruby**: 3.2+
 - **Valkey/Redis**: 6.0+
 - **Gems**: `redis` (automatically installed)
 

data/docs/guides/feature-encrypted-fields.md

@@ -895,7 +895,7 @@ Familia::Encryption.validate_configuration!
 ## See Also
 
 - **[Overview](../overview.md#encrypted-fields)** - Conceptual introduction to encrypted fields
-- **[Technical Reference](../reference/api-technical.md#encrypted-fields-feature-v200-pre5)** - Implementation details and advanced patterns
+- **[Technical Reference](../reference/api-technical.md#feature-system)** - Implementation details and advanced patterns
 - **[Security Model Guide](security-model.md)** - Cryptographic design and threat model considerations
 - **[Feature System Guide](feature-system.md)** - Understanding Familia's feature architecture
 - **[Implementation Guide](implementation.md)** - Production deployment and configuration patterns

data/docs/guides/feature-expiration.md

@@ -641,7 +641,7 @@ Get/set class-level default expiration.
 
 ## See Also
 
-- **[Technical Reference](../reference/api-technical.md#expiration-feature-v200-pre5)** - Implementation details and advanced patterns
+- **[Technical Reference](../reference/api-technical.md#feature-system)** - Implementation details and advanced patterns
 - **[Overview](../overview.md#automatic-expiration)** - Conceptual introduction to expiration
 - **[Feature System Guide](feature-system.md)** - Understanding Familia's feature architecture
 - **[Implementation Guide](implementation.md)** - Production deployment and configuration patterns

data/docs/guides/feature-quantization.md

@@ -891,7 +891,7 @@ BasicModel.qstamp()  # Uses 10.minutes fallback (600 seconds)
 
 ## See Also
 
-- **[Technical Reference](../reference/api-technical.md#quantization-feature-v200-pre7)** - Implementation details and advanced patterns
+- **[Technical Reference](../reference/api-technical.md#feature-system)** - Implementation details and advanced patterns
 - **[Overview](../overview.md#time-based-quantization)** - Conceptual introduction to quantization
 - **[Time Utilities Guide](time-utilities.md)** - Time manipulation and formatting utilities
 - **[Feature System Guide](feature-system.md)** - Understanding Familia's feature architecture

data/docs/guides/writing-migrations.md

@@ -0,0 +1,345 @@
+# Writing Migrations
+
+## Quick Start
+
+Minimal working migration:
+
+```ruby
+class NormalizeEmails < Familia::Migration::Base
+  self.migration_id = '20260131_120000_normalize_emails'
+  self.description = 'Lowercase all email addresses'
+
+  def migration_needed?
+    redis.exists('needs:normalization') > 0
+  end
+
+  def migrate
+    redis.scan_each(match: 'user:*:object') do |key|
+      for_realsies_this_time? do
+        # perform changes
+      end
+      track_stat(:processed)
+    end
+  end
+end
+```
+
+Run it:
+
+```bash
+bundle exec rake familia:migrate:dry_run    # Preview
+bundle exec rake familia:migrate            # Apply
+```
+
+## Migration Types
+
+| Type | Use When | Key Method |
+|------|----------|------------|
+| `Base` | Raw Redis operations, key patterns, config changes | `migrate` |
+| `Model` | Iterating over Horreum objects with per-record logic | `process_record(obj, key)` |
+| `Pipeline` | Bulk updates with Redis pipelining (1000+ records) | `should_process?(obj)`, `build_update_fields(obj)` |
+
+### Base
+
+Direct Redis access. Use for key renames, TTL changes, config migrations:
+
+```ruby
+class AddTTLToSessions < Familia::Migration::Base
+  self.migration_id = '20260131_add_ttl'
+
+  def migration_needed?
+    redis.exists('legacy:session:*') > 0
+  end
+
+  def migrate
+    cursor = '0'
+    loop do
+      cursor, keys = redis.scan(cursor, match: 'legacy:session:*', count: 1000)
+      keys.each do |key|
+        for_realsies_this_time? { redis.expire(key, 3600) }
+        track_stat(:keys_expired)
+      end
+      break if cursor == '0'
+    end
+  end
+end
+```
+
+### Model
+
+SCAN-based iteration over Horreum objects. Use for per-record transformations with error handling:
+
+```ruby
+class CustomerEmailMigration < Familia::Migration::Model
+  self.migration_id = '20260131_customer_emails'
+
+  def prepare
+    @model_class = Customer
+    @batch_size = 500  # optional, default: 1000
+  end
+
+  def process_record(customer, key)
+    return unless customer.email =~ /[A-Z]/
+
+    for_realsies_this_time? do
+      customer.email = customer.email.downcase
+      customer.save
+    end
+    track_stat(:records_updated)
+  end
+end
+```
+
+### Pipeline
+
+Batched updates using Redis pipelining. Use for high-volume simple field updates:
+
+```ruby
+class AddDefaultSettings < Familia::Migration::Pipeline
+  self.migration_id = '20260131_default_settings'
+
+  def prepare
+    @model_class = User
+    @batch_size = 100  # smaller batches for pipelines
+  end
+
+  def should_process?(user)
+    user.settings.nil?
+  end
+
+  def build_update_fields(user)
+    { 'settings' => '{}' }
+  end
+end
+```
+
+Override `execute_update` for custom pipeline operations:
+
+```ruby
+def execute_update(pipe, obj, fields, original_key)
+  dbkey = original_key || obj.dbkey
+  pipe.hmset(dbkey, *fields.flatten)
+  pipe.expire(dbkey, 86400)  # also set TTL
+end
+```
+
+## Class Attributes
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `migration_id` | Yes | Unique identifier. Format: `YYYYMMDD_HHMMSS_snake_case_name` |
+| `description` | No | Human-readable summary for status output |
+| `dependencies` | No | Array of migration IDs that must run first |
+
+```ruby
+class BuildEmailIndex < Familia::Migration::Base
+  self.migration_id = '20260131_150000_build_index'
+  self.description = 'Create secondary index for email lookups'
+  self.dependencies = ['20260131_120000_normalize_emails']
+  # ...
+end
+```
+
+## Lifecycle Methods
+
+| Method | Purpose | Required |
+|--------|---------|----------|
+| `prepare` | Initialize config, set `@model_class` | Model/Pipeline only |
+| `migration_needed?` | Idempotency check. Return `false` to skip. | Yes |
+| `migrate` | Core migration logic | Base only |
+| `process_record(obj, key)` | Per-record logic | Model only |
+| `should_process?(obj)` | Filter predicate | Pipeline only |
+| `build_update_fields(obj)` | Return Hash of field updates | Pipeline only |
+| `down` | Rollback logic | No (enables rollback) |
+
+## Dry Run vs Live
+
+Wrap destructive operations with `for_realsies_this_time?`:
+
+```ruby
+def migrate
+  redis.scan_each(match: 'session:*') do |key|
+    for_realsies_this_time? do
+      redis.del(key)  # only executes with --run
+    end
+    track_stat(:deleted)
+  end
+end
+```
+
+| Mode | `for_realsies_this_time?` | Registry Updated |
+|------|---------------------------|------------------|
+| Dry run (`:dry_run` task) | Block skipped | No |
+| Live (`:run` task) | Block executes | Yes |
+
+## Dependencies
+
+Dependencies ensure execution order. The runner uses topological sort (Kahn's algorithm).
+
+```ruby
+class MigrationA < Familia::Migration::Base
+  self.migration_id = 'step_a'
+  self.dependencies = []
+end
+
+class MigrationB < Familia::Migration::Base
+  self.migration_id = 'step_b'
+  self.dependencies = ['step_a']  # runs after step_a
+end
+```
+
+Rollback is blocked if dependents are still applied:
+
+```ruby
+runner.rollback('step_a')
+# => Errors::HasDependents if step_b is applied
+```
+
+## Rollback
+
+Implement `down` to enable rollback:
+
+```ruby
+class AddFeatureFlag < Familia::Migration::Base
+  self.migration_id = '20260131_feature_flag'
+
+  def migration_needed?
+    !redis.exists?('config:feature:enabled')
+  end
+
+  def migrate
+    for_realsies_this_time? do
+      redis.set('config:feature:enabled', 'true')
+    end
+  end
+
+  def down
+    redis.del('config:feature:enabled')
+  end
+end
+```
+
+Check reversibility:
+
+```ruby
+instance = AddFeatureFlag.new
+instance.reversible?  # => true
+```
+
+## Lua Scripts
+
+Use `Familia::Migration::Script` for atomic operations:
+
+```ruby
+# Rename hash field atomically
+Familia::Migration::Script.execute(
+  redis,
+  :rename_field,
+  keys: ['user:123:object'],
+  argv: ['old_name', 'new_name']
+)
+```
+
+Built-in scripts:
+
+| Script | Purpose | KEYS | ARGV |
+|--------|---------|------|------|
+| `:rename_field` | Rename hash field | `[hash_key]` | `[old, new]` |
+| `:copy_field` | Copy field within hash | `[hash_key]` | `[src, dst]` |
+| `:delete_field` | Delete hash field | `[hash_key]` | `[field]` |
+| `:rename_key_preserve_ttl` | Rename key, keep TTL | `[src, dst]` | `[]` |
+| `:backup_and_modify_field` | Backup old value, set new | `[hash, backup]` | `[field, value, ttl]` |
+
+Register custom scripts:
+
+```ruby
+Familia::Migration::Script.register(:my_script, <<~LUA)
+  local key = KEYS[1]
+  return redis.call('GET', key)
+LUA
+```
+
+## CLI Reference
+
+```bash
+# Status
+bundle exec rake familia:migrate:status       # Show applied/pending
+bundle exec rake familia:migrate:validate     # Check dependency issues
+bundle exec rake familia:migrate:schema_drift # Models with changed schemas
+
+# Execution
+bundle exec rake familia:migrate:dry_run      # Preview (no changes)
+bundle exec rake familia:migrate              # Apply all pending
+bundle exec rake familia:migrate:run          # Same as above
+
+# Rollback
+bundle exec rake "familia:migrate:rollback[20260131_120000_migration_id]"
+```
+
+## Statistics
+
+Track operations with `track_stat`:
+
+```ruby
+def process_record(obj, key)
+  if obj.email.blank?
+    track_stat(:skipped_blank)
+    return
+  end
+
+  for_realsies_this_time? do
+    obj.email = obj.email.downcase
+    obj.save
+  end
+  track_stat(:records_updated)
+end
+```
+
+Access stats:
+
+```ruby
+instance.stats[:records_updated]  # => 42
+instance.stats[:skipped_blank]    # => 7
+```
+
+## Configuration
+
+```ruby
+Familia::Migration.configure do |config|
+  config.migrations_key = 'familia:migrations'  # Registry key prefix
+  config.backup_ttl = 86_400                    # Backup expiration (24h)
+  config.batch_size = 1000                      # Default SCAN batch
+end
+```
+
+## Best Practices
+
+1. **Test locally first.** Run dry run, verify stats, then run live on staging before production.
+
+2. **Deploy schema changes separately.** Avoid updating model definitions and running migrations in the same deploy. New model logic can break migration code.
+
+3. **Keep migrations idempotent.** `migration_needed?` should return `false` after successful execution.
+
+4. **Use descriptive IDs.** `20260131_120000_normalize_customer_emails` beats `20260131_fix_stuff`.
+
+5. **Backup critical data.** Use `:backup_and_modify_field` or `registry.backup_field` before destructive changes.
+
+## Error Reference
+
+| Error | Cause |
+|-------|-------|
+| `NotReversible` | `down` not implemented |
+| `NotApplied` | Rollback of unapplied migration |
+| `DependencyNotMet` | Dependency not yet applied |
+| `HasDependents` | Rollback blocked by dependents |
+| `CircularDependency` | Dependency cycle detected |
+| `PreconditionFailed` | `@model_class` not set in `prepare` |
+
+## Source Files
+
+- [`lib/familia/migration/base.rb`](../../lib/familia/migration/base.rb)
+- [`lib/familia/migration/model.rb`](../../lib/familia/migration/model.rb)
+- [`lib/familia/migration/pipeline.rb`](../../lib/familia/migration/pipeline.rb)
+- [`lib/familia/migration/registry.rb`](../../lib/familia/migration/registry.rb)
+- [`lib/familia/migration/runner.rb`](../../lib/familia/migration/runner.rb)
+- [`lib/familia/migration/script.rb`](../../lib/familia/migration/script.rb)

data/docs/overview.md

@@ -242,7 +242,7 @@ This automatically groups metrics into 10-minute intervals formatted as "HH:MM",
 - **Reduced Storage**: Aggregate similar data points to optimize memory usage
 - **Analytics Ready**: Perfect for dashboards and time-series data visualization
 
-> For advanced quantization strategies, value bucketing, geographic quantization, and performance patterns, see the [Technical Reference](reference/api-technical.md#quantization-feature-v200-pre7).
+> For advanced quantization strategies, value bucketing, geographic quantization, and performance patterns, see the [Technical Reference](reference/api-technical.md#feature-system).
 
 ### Object Identifiers
 
@@ -273,7 +273,7 @@ session.objid  # => "a1b2c3d4e5f6" (hex)
 - `:uuid_v4` - Standard UUID format for global uniqueness
 - `:hex` - Compact hexadecimal identifiers for internal use
 
-> For custom generators, collision detection, and advanced identifier patterns, see the [Technical Reference](reference/api-technical.md#object-identifier-feature-v200-pre7).
+> For custom generators, collision detection, and advanced identifier patterns, see the [Technical Reference](reference/api-technical.md#feature-system).
 
 ### Specialized Field Types
 
@@ -354,7 +354,7 @@ user = ExternalUser.create(external_id: "ext_12345", name: "Alice")
 
 This feature helps maintain consistency when integrating with external APIs or legacy systems.
 
-> For advanced external identifier patterns, batch operations, and sync status management, see the [Technical Reference](reference/api-technical.md#external-identifier-feature-v200-pre7).
+> For advanced external identifier patterns, batch operations, and sync status management, see the [Technical Reference](reference/api-technical.md#feature-system).
 
 ### Relationships
 
@@ -435,7 +435,7 @@ Team.email_index_for("alice@example.com")      # Direct index access
 - **Automatic Indexing**: Efficient O(1) lookups with automatic index maintenance
 - **Performance Optimized**: Bulk operations and efficient sorted set operations
 
-> For advanced relationship patterns, permission-encoded relationships, time-series tracking, and performance optimization, see the [Technical Reference](reference/api-technical.md#relationships-feature-v200-pre7).
+> For advanced relationship patterns, permission-encoded relationships, time-series tracking, and performance optimization, see the [Technical Reference](reference/api-technical.md#feature-system).
 
 ### Transient Fields
 
@@ -472,7 +472,7 @@ attempt.security_token.reveal   # => "sensitive_data"
 - **Transient Fields**: Exist only in memory, never persisted
 - **Redacted Fields**: Return `[REDACTED]` when converted to strings for logging safety
 
-> For RedactedString implementation details, single-use patterns, and security considerations, see the [Technical Reference](reference/api-technical.md#transient-fields-feature-v200-pre5).
+> For RedactedString implementation details, single-use patterns, and security considerations, see the [Technical Reference](reference/api-technical.md#feature-system).
 
 ### Permission Management
 
@@ -638,7 +638,7 @@ user.encrypted_fields_status  # Check encryption status
 - **Key Rotation**: Seamless updates with backward compatibility
 - **Multiple Algorithms**: XChaCha20-Poly1305 (preferred) with AES-256-GCM fallback
 
-> For advanced encryption configuration, multiple providers, request caching, and key rotation procedures, see the [Technical Reference](reference/api-technical.md#encrypted-fields-feature-v200-pre5).
+> For advanced encryption configuration, multiple providers, request caching, and key rotation procedures, see the [Technical Reference](reference/api-technical.md#feature-system).
 
 ### Open-ended Serialization
 
@@ -772,7 +772,7 @@ Familia.configure do |config|
 end
 ```
 
-> For production configuration patterns, advanced connection pooling, multi-database setup, and environment-based configuration, see the [Technical Reference](reference/api-technical.md#connection-management-v200-pre).
+> For production configuration patterns, advanced connection pooling, multi-database setup, and environment-based configuration, see the [Technical Reference](reference/api-technical.md#connection-management).
 
 ## Common Patterns