https://github.com/mperham/connection_pool

Generic connection pooling for Ruby
https://github.com/mperham/connection_pool

Keywords from Contributors

rubygem activerecord mvc activejob rack sidekiq rspec crash-reporting background-jobs jobs

Last synced: about 20 hours ago
JSON representation

Repository metadata

Generic connection pooling for Ruby

Host: GitHub
URL: https://github.com/mperham/connection_pool
Owner: mperham
License: mit
Created: 2011-05-14T19:30:37.000Z (almost 15 years ago)
Default Branch: main
Last Pushed: 2026-01-12T16:35:23.000Z (about 2 months ago)
Last Synced: 2026-03-02T07:11:49.024Z (1 day ago)
Language: Ruby
Homepage:
Size: 227 KB
Stars: 1,679
Watchers: 25
Forks: 144
Open Issues: 0
Releases: 0
Metadata Files:
- Readme: README.md
- Changelog: Changes.md
- License: LICENSE

connection_pool

Generic connection pooling for Ruby.

MongoDB has its own connection pool.
ActiveRecord has its own connection pool.
This is a generic connection pool that can be used with anything, e.g. Redis, Dalli and other Ruby network clients.

Usage

Create a pool of objects to share amongst the fibers or threads in your Ruby application:

$memcached = ConnectionPool.new(size: 5, timeout: 5) { Dalli::Client.new }

Then use the pool in your application:

$memcached.with do |conn|
  conn.get('some-count')
end

If all the objects in the connection pool are in use, with will block
until one becomes available.
If no object is available within :timeout seconds,
with will raise a ConnectionPool::TimeoutError (a subclass of Timeout::Error).

You can also use ConnectionPool#then to support both a
connection pool and a raw client.

# Compatible with a raw Redis::Client, and ConnectionPool Redis
$redis.then { |r| r.set 'foo' 'bar' }

Optionally, you can specify a timeout override:

$memcached.with(timeout: 2.0) do |conn|
  conn.get('some-count')
end

This will only modify the timeout for this particular invocation.
This is useful if you want to fail-fast on certain non-critical
sections when a resource is not available, or conversely if you are comfortable blocking longer on a particular resource.

Migrating to a Connection Pool

You can use ConnectionPool::Wrapper to wrap a single global connection, making it easier to migrate existing connection code over time:

$redis = ConnectionPool::Wrapper.new(size: 5, timeout: 3) { Redis.new }
$redis.sadd('foo', 1)
$redis.smembers('foo')

The wrapper uses method_missing to checkout a connection, run the requested method and then immediately check the connection back into the pool.
It's not high-performance so you'll want to port your performance sensitive code to use with as soon as possible.

$redis.with do |conn|
  conn.sadd('foo', 1)
  conn.smembers('foo')
end

Once you've ported your entire system to use with, you can remove ::Wrapper and use ConnectionPool directly.

Shutdown

You can shut down a ConnectionPool instance once it should no longer be used.
Further checkout attempts will immediately raise an error but existing checkouts will work.

cp = ConnectionPool.new { Redis.new }
cp.shutdown { |c| c.close }

Shutting down a connection pool will block until all connections are checked in and closed.
Note that shutting down is completely optional; Ruby's garbage collector will reclaim unreferenced pools under normal circumstances.

Reload

You can reload a ConnectionPool instance if it is necessary to close all existing connections and continue to use the pool.
ConnectionPool will automatically reload if the process is forked.
Use auto_reload_after_fork: false if you don't want this behavior.

cp = ConnectionPool.new(auto_reload_after_fork: false) { Redis.new }
cp.reload { |conn| conn.quit } # reload manually
cp.with { |conn| conn.get('some-count') }

Like shutdown, reload will block until all connections are checked in and closed.

Reap

You can call reap periodically on the ConnectionPool instance to close connections that were created but have not been used for a certain amount of time. This can be useful in environments where connections are expensive.

You can specify how many seconds the connections have to be idle for them to be reaped, defaulting to 60 seconds.

cp = ConnectionPool.new { Redis.new }

# Start a reaper thread to reap connections that have been
# idle more than 300 seconds (5 minutes)
Thread.new do
  loop do
    cp.reap(idle_seconds: 300, &:close)
    sleep 30
  end
end

Discarding Connections

You can discard connections in the ConnectionPool instance to remove connections that are broken and can't be repaired.
It can only be done inside the block passed to with.
Takes an optional block that will be executed with the connection.

pool.with do |conn|
  begin
    conn.execute("SELECT 1")
  rescue SomeConnectionError
    pool.discard_current_connection(&:close)  # remove the connection from the pool
    raise
  end
end

Current State

There are several methods that return information about a pool.

cp = ConnectionPool.new(size: 10) { Redis.new }
cp.size # => 10
cp.available # => 10
cp.idle # => 0

cp.with do |conn|
  cp.size # => 10
  cp.available # => 9
  cp.idle # => 0
end

cp.idle # => 1

Upgrading from ConnectionPool 2

Support for Ruby <3.2 has been removed.
ConnectionPool's APIs now consistently use keyword arguments everywhere.
Positional arguments must be converted to keywords:

pool = ConnectionPool.new(size: 5, timeout: 5)
pool.checkout(1) # 2.x
pool.reap(30)    # 2.x
pool.checkout(timeout: 1) # 3.x
pool.reap(idle_seconds: 30) # 3.x

Notes

Connections are lazily created as needed.
WARNING: Avoid Timeout.timeout in your Ruby code or you can see
occasional silent corruption and mysterious errors. The Timeout API is unsafe
and dangerous to use. Use proper socket timeout options as exposed by
Net::HTTP, Redis, Dalli, etc.

Author

Mike Perham, @getajobmike, https://www.mikeperham.com

Owner metadata

Name: Mike Perham
Login: mperham
Email:
Kind: user
Description: Author and maintainer of Sidekiq, the background job framework for Ruby, and Faktory, background jobs for all languages.
Website: https://www.mikeperham.com
Location: Portland, OR
Twitter:
Company: Contributed Systems
Icon url: https://avatars.githubusercontent.com/u/2911?u=9e18eee0dc7fe4564dba7cdc7e22711a47171a8b&v=4
Repositories: 104
Last ynced at: 2023-04-09T03:55:19.450Z
Profile URL: https://github.com/mperham

GitHub Events

Total

Delete event: 1
Pull request event: 15
Fork event: 7
Issues event: 11
Watch event: 38
Issue comment event: 51
Push event: 17
Pull request review event: 5
Pull request review comment event: 6
Create event: 5

Last Year

Delete event: 1
Pull request event: 12
Fork event: 5
Issues event: 8
Watch event: 25
Issue comment event: 29
Push event: 14
Pull request review event: 5
Pull request review comment event: 6
Create event: 4

Committers metadata

Last synced: about 22 hours ago

Total Commits: 296
Total Committers: 62
Avg Commits per committer: 4.774
Development Distribution Score (DDS): 0.635

Commits in past year: 31
Committers in past year: 6
Avg Commits per committer in past year: 5.167
Development Distribution Score (DDS) in past year: 0.226

Name	Email	Commits
Mike Perham	m**m@g**m	108
Eric Hodel	d**n@s**t	45
Damian Janowski	d**i@g**m	33
Tamir Duberstein	t**d@s**m	14
Olle Jonsson	o**n@g**m	7
Jason King	jk@r****d	5
matt camuto	m**o@o**m	4
dependabot[bot]	4****]	4
Robert Schulze	r**t@d**e	4
David Rodríguez	d**z@r**t	4
Tristan Starck	t**k@i**m	3
Peter Goldstein	p**n@g**m	3
TJ Singleton	t**n@v**m	3
womblep	g**b@r**u	2
Pete Higgins	p**e@p**g	2
Nic Cavigliano	n**g@g**m	2
Kendall Gifford	z**e@g**m	2
Ian Ker-Seymer	i**r@g**m	2
David Genord II	d**d@c**m	2
Brian O'Rourke	b**n@o**o	2
Ben Lovell	b**l@g**m	2
Rob Holland	r**b@c**m	2
Tero Tasanen	t**n@g**m	2
Anthony Ross	a**s@v**m	1
Igor Kapkov	i**k@m**m	1
James Kyburz and Kim Burgestrand	d**d@e**e	1
Simão Mata	s**a@s**m	1
Thomas	ts@t****r	1
chatgris	j**r@a**m	1
Andrew Marshall	a**w@j**m	1
and 32 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 13 days ago

Total issues: 56
Total pull requests: 93
Average time to close issues: 4 months
Average time to close pull requests: 18 days
Total issue authors: 50
Total pull request authors: 56
Average comments per issue: 3.16
Average comments per pull request: 2.0
Merged pull request: 69
Bot issues: 1
Bot pull requests: 4

Past year issues: 11
Past year pull requests: 15
Past year average time to close issues: 1 day
Past year average time to close pull requests: 5 days
Past year issue authors: 9
Past year pull request authors: 8
Past year average comments per issue: 3.0
Past year average comments per pull request: 1.53
Past year merged pull request: 10
Past year bot issues: 0
Past year bot pull requests: 2

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/mperham/connection_pool

Top Issue Authors

mperham (4)
ioquatix (2)
jasonkingPNM (2)
rmosolgo (2)
voxik (1)
matt-domsch-sp (1)
Roguelazer (1)
amartinfraguas (1)
MITSUBOSHI (1)
Paxa (1)
epetre (1)
skunkworker (1)
pitosalas (1)
ClearlyClaire (1)
arjes (1)

Top Pull Request Authors

olleolleolle (6)
ttstarck (6)
albus522 (5)
fnordfish (4)
deivid-rodriguez (4)
jasonkingPNM (4)
dependabot[bot] (4)
womblep (3)
m-nakamura145 (3)
petergoldstein (3)
ruban-thilak (2)
bpo (2)
ianks (2)
ttasanen (2)
mobilutz (2)

Top Issue Labels

dependencies (1)

Top Pull Request Labels

dependencies (4)
github_actions (2)

Package metadata

Total packages: 14
Total downloads:
- rubygems: 1,229,156,606 total
Total docker downloads: 1,311,555,714
Total dependent packages: 296 (may contain duplicates)
Total dependent repositories: 41,556 (may contain duplicates)
Total versions: 104
Total maintainers: 2

gem.coop: connection_pool

Generic connection pool for Ruby

Homepage: https://github.com/mperham/connection_pool
Documentation: http://www.rubydoc.info/gems/connection_pool/
Licenses: MIT
Latest release: 3.0.2 (published 3 months ago)
Last Synced: 2026-03-02T09:01:15.329Z (1 day ago)
Versions: 34
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 614,624,972 Total
Docker Downloads: 655,777,857
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Downloads: 0.039%
- Average: 0.044%
- Docker downloads count: 0.137%
Maintainers (2)
- djanowski
- mperham

rubygems.org: connection_pool

Generic connection pool for Ruby

Homepage: https://github.com/mperham/connection_pool
Documentation: http://www.rubydoc.info/gems/connection_pool/
Licenses: MIT
Latest release: 3.0.2 (published 3 months ago)
Last Synced: 2026-03-02T05:02:41.814Z (1 day ago)
Versions: 34
Dependent Packages: 296
Dependent Repositories: 41,556
Downloads: 614,531,634 Total
Docker Downloads: 655,777,857
Rankings:
- Downloads: 0.056%
- Dependent packages count: 0.146%
- Dependent repos count: 0.163%
- Docker downloads count: 0.227%
- Average: 0.673%
- Stargazers count: 1.273%
- Forks count: 2.174%
Maintainers (2)
- djanowski
- mperham

proxy.golang.org: github.com/mperham/connection_pool

Homepage:
Documentation: https://pkg.go.dev/github.com/mperham/connection_pool#section-documentation
Licenses: mit
Latest release: v3.0.2+incompatible (published 3 months ago)
Last Synced: 2026-03-02T09:01:16.790Z (1 day ago)
Versions: 25
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Stargazers count: 1.699%
- Forks count: 2.284%
- Average: 6.09%
- Dependent packages count: 9.576%
- Dependent repos count: 10.802%

ubuntu-20.04: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Licenses:
Latest release: 2.2.2-1 (published 18 days ago)
Last Synced: 2026-02-13T07:11:57.066Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-23.04: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Licenses:
Latest release: 2.2.5-1 (published 20 days ago)
Last Synced: 2026-02-11T06:37:14.556Z (20 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

debian-11: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Documentation: https://packages.debian.org/bullseye/ruby-connection-pool
Licenses:
Latest release: 2.2.2-1 (published 21 days ago)
Last Synced: 2026-02-13T08:19:12.926Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-23.10: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Licenses:
Latest release: 2.2.5-1 (published 18 days ago)
Last Synced: 2026-02-13T18:17:00.603Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-24.10: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Licenses:
Latest release: 2.4.1-1 (published 22 days ago)
Last Synced: 2026-02-09T16:22:43.295Z (22 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

debian-10: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Documentation: https://packages.debian.org/buster/ruby-connection-pool
Licenses:
Latest release: 2.2.2-1 (published 20 days ago)
Last Synced: 2026-02-13T04:20:01.354Z (19 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

guix: ruby-connection-pool

Generic connection pool for Ruby

Homepage: https://github.com/mperham/connection_pool
Documentation: https://git.savannah.gnu.org/cgit/guix.git/tree/gnu/packages/ruby-xyz.scm#n4147
Licenses: expat
Latest release: 2.4.1 (published about 23 hours ago)
Last Synced: 2026-03-02T18:57:57.949Z (about 23 hours ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-22.04: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Licenses:
Latest release: 2.2.5-1 (published 18 days ago)
Last Synced: 2026-02-13T13:14:47.025Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-24.04: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Licenses: mit
Latest release: 2.4.1-1 (published 19 days ago)
Last Synced: 2026-02-13T01:01:55.023Z (19 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

debian-13: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Documentation: https://packages.debian.org/trixie/ruby-connection-pool
Licenses:
Latest release: 2.4.1-1 (published 19 days ago)
Last Synced: 2026-02-13T13:14:24.598Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

debian-12: ruby-connection-pool

Homepage: https://github.com/mperham/connection_pool
Documentation: https://packages.debian.org/bookworm/ruby-connection-pool
Licenses:
Latest release: 2.2.5-1 (published 19 days ago)
Last Synced: 2026-02-12T23:27:28.644Z (19 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

Dependencies

connection_pool.gemspec rubygems

bundler >= 0 development
minitest >= 5.0.0 development
rake >= 0 development

.github/workflows/ci.yml actions

actions/checkout v3 composite
ruby/setup-ruby v1 composite

Gemfile rubygems

standard >= 0 development

Score: 33.208815422939644

https://github.com/mperham/connection_pool

Keywords from Contributors

Repository metadata

README.md

connection_pool

Usage

Migrating to a Connection Pool

Shutdown

Reload

Reap

Discarding Connections

Current State

Upgrading from ConnectionPool 2

Notes

Author

Owner metadata

GitHub Events

Total

Last Year

Committers metadata

Committer domains:

Issue and Pull Request metadata

Top Issue Authors

Top Pull Request Authors

Top Issue Labels

Top Pull Request Labels

Package metadata

gem.coop: connection_pool

rubygems.org: connection_pool

proxy.golang.org: github.com/mperham/connection_pool

ubuntu-20.04: ruby-connection-pool

ubuntu-23.04: ruby-connection-pool

debian-11: ruby-connection-pool

ubuntu-23.10: ruby-connection-pool

ubuntu-24.10: ruby-connection-pool

debian-10: ruby-connection-pool

guix: ruby-connection-pool

ubuntu-22.04: ruby-connection-pool

ubuntu-24.04: ruby-connection-pool

debian-13: ruby-connection-pool

debian-12: ruby-connection-pool

Dependencies