Consider docs recommendation for Rails isolation_level = :fiber

[trevorturk]

I wanted to share an issue we encountered and a potential documentation improvement that might help other Rails developers using RubyLLM. Note that this is fresh off a long debugging session, and I haven't been able to fully verify if the fix I'm suggesting completely solves the issue, but I wanted to document while it's fresh...

Background

We're building a Rails app using SwarmSDK (which depends on RubyLLM), and we ran into intermittent database errors after ~30 minutes of workflow execution:

undefined method 'cmd_tuples' for nil:NilClass
activerecord-8.1.1/lib/active_record/connection_adapters/postgresql/database_statements.rb:174

Probable Root Cause

We believe the issue occurs because:

1. SwarmSDK uses the async gem (which uses Fibers for concurrency)
2. Rails defaults to thread-based connection pools (config.active_support.isolation_level = :thread)
3. Database operations in workflow hooks were executing in Fiber context
4. Connection state corruption: When Fibers switch, ActiveRecord connections become corrupted because they're keyed per-Thread, not per-Fiber

After ~240 rapid database operations across many Fiber switches, PG gem methods would return nil instead of PG::Result objects, causing the error.

Potential Solution

Setting Rails to use fiber-safe connection pools seems to have fixed the issue:

# config/application.rb
config.active_support.isolation_level = :fiber

This tells ActiveRecord to track connections per-Fiber instead of per-Thread, preventing connection state corruption during Fiber context switches.

Documentation Suggestion

I searched the ruby_llm repository for "isolation_level" and didn't find any mentions. Since RubyLLM (and by extension SwarmSDK) uses the async gem under the hood, it might be worth adding a note in the Rails integration documentation about this configuration.

Something like:

Rails Integration Note: If you're using RubyLLM with Rails and encountering database connection errors, consider enabling fiber-safe connection pools:

# config/application.rb  
config.active_support.isolation_level = :fiber

This is necessary because RubyLLM uses the async gem which creates Fibers for concurrency. Rails defaults to thread-based connection pools, which can cause connection state corruption when database operations occur in Fiber context.

See: Rails Fiber-Safe Connection Pools

Environment

• Rails 8.1.1
• RubyLLM (via SwarmSDK 2.2.0)
• Puma (thread-based server)
• Async gem 2.34.0

Questions

1. Is this a known issue that other Rails users have encountered?
2. Are there any downsides to using :fiber isolation that Rails+RubyLLM users should be aware of?

Thanks for the excellent library! This was a tricky issue to debug, so hopefully this helps others avoid the same rabbit hole.

References

• Rails Fiber-Safe Connection Pools Blog Post
• Rails Issue #52617 - Memory leak with fiber isolation (fixed in Rails 7.2.1+)
• Rails Issue #42271 - Original fiber-safe connection pool implementation