rails/rails — Issue #4670: Documentation: ConnectionPool, contract/close
Author: jrochkind
Created: 2012-01-25 16:38:56+00:00
State: open

Rails 3.2 makes some changes to expected contract with ActiveRecord connections. "Automatic closure of connections in threads is deprecated" As the notes say (and I believe it's true), this generally only effects 'people who spawn threads in their application code."

In particular, certain actions will output this deprecation warning (sometimes a false positive I think, but such is life):

DEPRECATION WARNING: Database connections will not be closed automatically, please close your database connection at the end of the thread by calling `close` on your connection. For example: ActiveRecord::Base.connection.close

However, the documentation (rdoc generated from source comments) on how to interact with ActiveRecord connections, especially when you spawn threads in application code, has not been updated:

http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/ConnectionPool.html

This documentation doens't even **mention** ever calling "close" on a connection, which the deprecation warning suggests is actually *recommended* behavior.

I would try to submit a pull request with updated documentation... but I'm confused as to what the contract/recommended behavior is at the moment. Request feedback from someone who understands these details, perhaps whoever committed the new deprecation warning. The documentation mentions calling `ActiveRecord::Base.clear_active_connections!.` instead, in what I *think* is the same situation that the deprecation warning is recommending calling `close` instead -- I'm not entirely sure what the difference is, or what's recommended where.

The docs need to be clear on this, to explain to someone who is spawning their own threads in app code, the proper way to interact with ActiveRecord (and avoid deprecation warnings).