# Connection Pool
A flexible, high-performance, generic async connection pool for Rust with background cleanup and comprehensive logging.
[](https://crates.io/crates/connection-pool)
[](https://docs.rs/connection-pool)
[](LICENSE)
## ✨ Features
- 🚀 **High Performance**: Background cleanup eliminates connection acquisition latency
- 🔧 **Fully Generic**: Support for any connection type (TCP, Database, HTTP, etc.)
- ⚡ **Async/Await Native**: Built on tokio with modern async Rust patterns
- 🛡️ **Thread Safe**: Concurrent connection sharing with proper synchronization
- 🧹 **Smart Cleanup**: Configurable background task for expired connection removal
- 📊 **Rich Logging**: Comprehensive observability with configurable log levels
- 🔄 **Auto-Return**: RAII-based automatic connection return to pool
- ⏱️ **Timeout Control**: Configurable timeouts for connection creation
- 🎯 **Type Safe**: Compile-time guarantees with zero-cost abstractions
- 🧩 **Extensible**: Custom connection types and validation logic via the `ConnectionManager` trait
- 🌐 **Versatile**: Suitable for TCP, database, and any custom connection pooling
## Quick Start
Add `connection-pool` to your `Cargo.toml`:
```toml
[dependencies]
connection-pool = "0.2"
tokio = { version = "1.47", features = ["full"] }
```
Then you can use the connection pool in your application:
```rust,no_run
// 1. Define your ConnectionManager
use connection_pool::{ConnectionManager, ConnectionPool};
use std::future::Future;
use std::pin::Pin;
use tokio::net::TcpStream;
#[derive(Clone)]
pub struct TcpConnectionManager {
pub address: std::net::SocketAddr,
}
impl ConnectionManager for TcpConnectionManager {
type Connection = TcpStream;
type Error = std::io::Error;
type CreateFut = Pin<Box<dyn Future<Output = Result<TcpStream, Self::Error>> + Send>>;
type ValidFut<'a> = Pin<Box<dyn Future<Output = bool> + Send + 'a>>;
fn create_connection(&self) -> Self::CreateFut {
let addr = self.address;
Box::pin(async move { TcpStream::connect(addr).await })
}
fn is_valid<'a>(&'a self, conn: &'a mut Self::Connection) -> Self::ValidFut<'a> {
Box::pin(async move {
// Lightweight socket check only; for real liveness use a protocol heartbeat.
conn.peer_addr().is_ok()
})
}
}
#[tokio::main]
async fn main() -> std::io::Result<()> {
// 2. Create a connection pool
let manager = TcpConnectionManager { address: "127.0.0.1:8080".parse().unwrap() };
let pool = ConnectionPool::new(
Some(10), // max pool size
None, // default idle timeout
None, // default connection timeout
None, // default cleanup config
manager,
);
// 3. Acquire and use a connection
let mut conn = pool.clone().get_connection().await.unwrap();
use tokio::io::AsyncWriteExt;
conn.write_all(b"hello").await.unwrap();
Ok(())
}
```
`peer_addr()` is only a cheap socket-level check. It can tell you whether the
stream still exists locally, but it does not prove that the remote service is
actually healthy or ready to speak your protocol.
If you need stronger validation, add an application-level heartbeat such as
`ping`/`pong`, and make `is_valid` send and verify that message instead of
touching the data stream with a read.
## Advanced Usage
- You can pool any connection type (e.g. database, API client) by implementing the `ConnectionManager` trait.
- For TCP, prefer a protocol-level health check when you need to prove the peer is responsive.
- See `examples/db_example.rs` for a custom type example.
## Testing
```bash
cargo test
```
## 🎛️ Configuration Options
| `max_size` | Maximum number of connections | 10 |
| `max_idle_time` | Connection idle timeout | 5 minutes |
| `connection_timeout` | Connection creation timeout | 10 seconds |
| `cleanup_interval` | Background cleanup interval | 30 seconds |
## 🏗️ Architecture
The connection pool is now based on a single `ConnectionManager` abstraction:
```text
┌──────────────────────────────────────────────┐
│ ConnectionPool<M: Manager> │
├──────────────────────────────────────────────┤
│ • Holds a user-defined ConnectionManager │
│ • Manages a queue of pooled connections │
│ • Semaphore for max concurrent connections │
│ • Background cleanup for idle connections │
└──────────────────────────────────────────────┘
│
┌─────────┴─────────┐
│ │
┌─────▼─────┐ ┌─────────▼────────┐
│ Semaphore │ │ Background Task │
│ (Limits │ │ (Cleans up idle │
│ max conn)│ │ connections) │
└───────────┘ └──────────────────┘
│
┌─────▼────────────┐
│ Connection Queue │
│ (VecDeque) │
└──────────────────┘
│
┌─────▼────────────┐
│ PooledStream │
│ (RAII wrapper │
│ auto-returns) │
└──────────────────┘
```
### Key Components
- **Semaphore**: Controls maximum concurrent connections
- **Background Cleanup**: Async task for removing expired connections
- **Connection Queue**: FIFO queue of available connections
- **RAII Wrapper**: `PooledStream` for automatic connection return
## 🧪 Testing
Run the examples to see the pool in action:
```bash
# Basic TCP example
cargo run --example echo_example
# Database connection example
cargo run --example db_example
# Background cleanup demonstration
cargo run --example background_cleanup_example
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- [Documentation](https://docs.rs/connection-pool)
- [Crates.io](https://crates.io/crates/connection-pool)
- [Repository](https://github.com/ssrlive/connection-pool)