Show how `with_connection` and `lease_connection` interact.

connections.md

Permanent Connection Checkout

Rails 7.2 defaults:

Highscore.connection
# => #<ActiveRecord::ConnectionAdapters::SQLite3Adapter:0x000000000080e8 env_name="development" role=:writing>

With config.active_record.permanent_connection_checkout = :disallowed:

Highscore.connection
# Called deprecated `ActiveRecord::Base.connection` method. (ActiveRecord::ActiveRecordError)
# Either use `with_connection` or `lease_connection`.

Highscore.lease_connection
# => #<ActiveRecord::ConnectionAdapters::SQLite3Adapter:0x000000000103b0 env_name="development" role=:writing>

Highscore.connection_pool.active_connection?
# => #<ActiveRecord::ConnectionAdapters::SQLite3Adapter:0x000000000103b0 env_name="development" role=:writing>

Highscore.release_connection
# => true

Highscore.connection_pool.active_connection?
# => nil

With Connection

Highscore.connection_pool.active_connection?
# => nil

Highscore.first
# => #<Highscore:0x00007d3751d853c8 id: 1, name: "Anonymous", score: 1, created_at: "2024-04-24 06:12:16.208562000 +0000", updated_at: "2024-04-24 06:12:16.208562000 +0000">

Highscore.connection_pool.active_connection?
# => nil

Highscore.with_connection do
  Highscore.connection_pool.active_connection?
end
# => #<ActiveRecord::ConnectionAdapters::SQLite3Adapter:0x0000000002a7d8 env_name="development" role=:writing>

Highscore.connection_pool.active_connection?
# => nil

Leased Connection within With Connection

Highscore.with_connection do
  Highscore.lease_connection
end

Highscore.connection_pool.active_connection?
# => #<ActiveRecord::ConnectionAdapters::SQLite3Adapter:0x00000000038270 env_name="development" role=:writing>

In general, you should probably add

config.active_record.permanent_connection_checkout = :disallowed

to your environment configuration if you want to catch bad behaviour.

Note that with Rails 7.2+, a connection is not retained per request as it was previously:

> bin/rails console
Loading development environment (Rails 7.1.5.2)
irb(main):001> JobExecution.connection_pool.active_connection?
=> nil
irb(main):002> JobExecution.first
  JobExecution Load (0.1ms)  SELECT "job_executions".* FROM "job_executions" ORDER BY "job_executions"."id" ASC LIMIT ?  [["LIMIT", 1]]
=> 
#<JobExecution:0x0000000127323e58
 id: 8,
 name: "MyJob",
 data: {"arguments" => [], "queued_to" => "default", "delay" => 2},
 created_at: Sat, 27 Sep 2025 09:03:23.901494000 UTC +00:00,
 updated_at: Sat, 27 Sep 2025 09:03:23.901494000 UTC +00:00>
irb(main):003> JobExecution.connection_pool.active_connection?
=> 
#<ActiveRecord::ConnectionAdapters::SQLite3Adapter:0x0000000127a694d8 ...

Note that active_connection? returns non-nil.

Now, the connection is checked out for the query #first, and then returned afterwards.

> bin/rails console
Loading development environment (Rails 8.1.0.beta1)
example(dev):001> JobExecution.connection_pool.active_connection?
=> nil
example(dev):002> JobExecution.first
=> 
#<JobExecution:0x000000012c493388
 id: 8,
 name: "MyJob",
 data: {"arguments" => [], "queued_to" => "default", "delay" => 2},
 created_at: "2025-09-27 09:03:23.901494000 +0000",
 updated_at: "2025-09-27 09:03:23.901494000 +0000">
example(dev):003> JobExecution.connection_pool.active_connection?
=> nil