Download the PHP package senza1dio/database-pool without Composer

🚀 Database Connection Manager for Long-Running PHP

Advanced connection management for Swoole, RoadRunner, and ReactPHP.

Not a magic performance multiplier for classic PHP-FPM. This is a connection manager with circuit breaker, auto-release, and query optimization designed for persistent runtime environments.

🔴 CRITICAL: Understand Pool Scope

⚠️ ONE POOL PER PROCESS - NOT GLOBAL COORDINATION

This library creates process-local pools, not a global shared pool:

• Swoole/RoadRunner: One pool per worker → TRUE pooling (workers are persistent)
• PHP-FPM: One pool per worker → NOT TRUE pooling (worker-isolated, pool dies after request)
• CLI scripts: One pool per execution → Pooling only useful if script runs >1 second

This is NOT a global connection manager like PgBouncer or ProxySQL. If you need global pooling, use a dedicated connection pooler at the database layer.

⚠️ READ THIS FIRST: When to Use This Package

✅ PRIMARY USE CASES (Where It Actually Works)

1. Long-Running PHP Processes (RECOMMENDED)

• ✅ Swoole - Full pooling, 10-100x performance
• ✅ RoadRunner - Persistent workers, connection reuse
• ✅ ReactPHP - Event loop optimization
• ✅ PHP CLI Daemons - Queue processors, long-running workers

Why: Process survives across requests, pool genuinely reuses connections.

2. PHP-FPM (LIMITED BENEFITS)

• ⚠️ NOT true pooling - Each worker has isolated pool
• ⚠️ Requires enablePersistentConnections(true) + singleton pattern
• ⚠️ Benefits limited to per-worker connection caching, not global pooling
• ⚠️ persistent connections ≠ connection pool

Reality Check: PHP-FPM worker isolation means:

• Worker A pool ≠ Worker B pool
• No cross-worker connection sharing
• Benefit comes from PDO persistent connections, not this library
• This library adds circuit breaker + auto-release, but NOT true pooling

Expected Benefits: Minimal (2-3% improvement from features, not pooling)

❌ WHEN NOT TO USE (CRITICAL)

Standard PHP-FPM/Apache

• ❌ NO TRUE POOLING - Worker isolation prevents connection sharing
• ❌ Pool destroyed at end of each request (__destruct() closes all)
• ❌ "Persistent connections" are PDO feature, not this library's benefit
• ❌ Adds complexity without meaningful gains

Reality: If you're using standard PHP-FPM, you're better off with:

• Native PDO persistent connections (if needed)
• Simple connection singleton
• Standard error handling

Single-Request CLI Scripts

• ❌ One execution = one connection, pooling unnecessary
• ✅ Circuit breaker + auto-release still useful

When in doubt: If your PHP process lives <1 second, you don't need this.

🎯 Expected Results (Realistic)

Swoole/RoadRunner (persistent workers):

• Environment: Long-running process with true pooling
• Results: 10-100x reduction in connection overhead
• Benefits:
  • ✅ Global connection pool (shared across ALL requests)
  • ✅ Connection reuse guaranteed (pool persists across requests)
  • ✅ Circuit breaker preventing cascade failures
  • ✅ Auto-release preventing connection leaks
  • ✅ Query optimization (prepared statements, type-aware binding)

PHP-FPM (per-worker pooling):

• Environment: Static singleton + persistent connections
• Results: 20-80ms saved per request (when connection reused within same worker)
• Reality:
  • ⚠️ Per-worker optimization (NOT global pooling)
  • ⚠️ 50 workers = 50 separate pools (50×N connections total)
  • ⚠️ Connection reuse depends on traffic pattern (worker must be "warm")
  • ✅ Circuit breaker, auto-release still useful (2-3% improvement)

Key Insight: True pooling requires persistent runtime (Swoole/RoadRunner). PHP-FPM benefits are limited to per-worker connection caching. For global pooling with PHP-FPM, use external pooler (PgBouncer, ProxySQL).

📊 Benchmarks: What You ACTUALLY Save

Per-Connection Overhead (measured, PostgreSQL 16):

Connection Reuse (with this package):

Savings: 20-80ms per request (when connection reused successfully).

⚠️ IMPORTANT: This saving is:

• ✅ Real - measured in production
• ⚠️ Per-worker - NOT global across all workers
• ⚠️ Conditional - requires singleton pattern + persistent connections
• ❌ Not guaranteed - depends on traffic pattern (worker must be "warm")

Real-World Scenario (50 workers, 500 req/sec, 90% pool hit rate):

REALITY CHECK: These are cumulative savings across all workers, not end-to-end request latency reduction. Your API won't go from "500ms → 50ms" unless connection overhead was your ONLY bottleneck (rare).

More realistic: "120ms → 60ms" if connection overhead was 50% of request time.

✨ Features

Core Features

• ✅ Connection Pooling - Reuse connections (effective in Swoole/RoadRunner)
• ✅ Auto-Scaling - Dynamically scales from 5 to 400+ connections (long-running processes)
• ✅ Circuit Breaker - Automatic failure detection and graceful degradation
• ✅ SSL/TLS Support - Enterprise security for PostgreSQL and MySQL
• ✅ Auto-Release - Connections automatically returned to pool (prevents leaks)
• ✅ Input Validation - Query size limits (1MB) and param count limits (1000) for memory protection
• ✅ Multi-Database - PostgreSQL, MySQL, SQLite support
• ✅ Framework Agnostic - Works with Laravel, Symfony, or pure PHP
• ✅ PSR-3 Logging - Integrates with Monolog, Laravel Log, Symfony Logger

Enterprise Features

• ✅ Type-Aware Parameter Binding - Automatic boolean/integer/null binding for PostgreSQL/MySQL
• ✅ Query Result Caching - Redis/Memcached integration for SELECT query caching
• ✅ Connection Warmup - Pre-create connections to avoid cold start latency
• ✅ Connection Retry Logic - Exponential backoff (3 retries) on transient failures
• ✅ Monitoring Hooks - New Relic, Datadog, custom metrics integration
• ✅ Transaction Safety - Auto-rollback uncommitted transactions on connection release
• ✅ Slow Query Detection - Automatic logging of queries >100ms (configurable)
• ✅ Prepared Statement Caching - Reuse prepared statements (PostgreSQL optimization)

📦 Installation

Requirements:

• PHP 8.0+
• ext-pdo

Recommended:

• ext-redis (for distributed locking at scale)
• ext-pgsql, ext-mysqli, or ext-sqlite3

🚀 Quick Start

Swoole/RoadRunner (Recommended)

Pure PHP (CLI Workers/Daemons)

Laravel

Symfony

PHP-FPM with Singleton (Built-in Helper)

For PHP-FPM deployments, use the built-in DatabasePoolSingleton:

Why this works: Static instance survives across requests within the same PHP-FPM worker.

⚠️ CRITICAL: Config Instance Reuse Required

When using DatabasePoolSingleton, you MUST reuse the same PoolConfig instance:

Why: Config identity is checked via spl_object_hash(). Two PoolConfig objects with identical values but different instances are considered different configurations and will throw LogicException.

Alternative: Use DatabasePoolSingleton::reset() to reconfigure, but this closes all connections.

⚠️ Known Limitations

Query Cache (Application-Level, Not Enterprise-Grade)

• Uses fetchAll() internally - not suitable for large datasets (>10k rows)
• No streaming support, breaks memory profile
• Only caches SELECT queries with FETCH_ASSOC
• Reality: This is application-level caching, not database-level optimization
• Best for: Small lookups (<100 rows), frequently-accessed reference data
• Not for: Large reports, streaming queries, cursor-based operations

Prepared Statement Cache (⚠️ Experimental)

• Reuses same PDOStatement object with default fetchMode
• Not safe for scrollable cursors or custom statement attributes
• Not invalidated on reconnect (fragile in edge cases)
• Status: Experimental - use with caution in production
• Best for: Simple repeated queries in stable connections

Locks (Process-Local, Often Unnecessary)

• Semaphore locks prevent race conditions within same PHP process
• Do NOT coordinate between different Swoole/RoadRunner workers
• When useful: Swoole coroutine environments with shared state
• When useless: PHP-FPM (no shared state), single-threaded RoadRunner
• For global coordination, use Redis-based locks (see RedisLock adapter)

Reality: In most deployments, locks add overhead without benefit. They're insurance against edge cases.

SQLite :memory:

• Each connection has separate in-memory database
• Connection pooling loses data between connections
• Use file-based SQLite for pooling benefits

Input Validation (Not True DoS Protection)

• Query size and param count limits protect memory, not pool availability
• Does NOT protect against:
  • Slow queries (use database-level timeouts)
  • Blocking queries (use transaction timeouts)
  • Direct PDO methods (quote(), exec())
  • Multi-statement queries
• Reality: Best-effort protection. Full enforcement only via DatabasePool::executeQuery() API.

📖 Configuration

Fluent Builder API

From Array (Laravel/Symfony style)

From DSN

🚀 Enterprise Features

Type-Aware Parameter Binding

Automatically detects and binds correct PDO types (boolean, integer, null, string). Essential for PostgreSQL/MySQL compatibility.

Query Result Caching

Cache SELECT query results in Redis/Memcached for massive performance gains.

Connection Warmup

Pre-create connections on application boot to eliminate cold start latency.

Monitoring Hooks (New Relic / Datadog)

Integrate with external monitoring systems for real-time metrics.

Connection Retry Logic

Automatic retry with exponential backoff on transient failures (network hiccups, temporary DB overload).

Transaction Safety

Automatically rolls back uncommitted transactions when connections are released. Prevents data corruption and state leakage.

🔒 Security Features

SSL/TLS Enforcement

DoS Protection

Circuit Breaker

Automatically opens after threshold failures, preventing cascade failures:

🎯 Performance

Connection Pooling Benefits

Without pooling:

• 10,000 requests = 10,000 new connections
• Connection time: 10-50ms each
• Total overhead: 100-500 seconds

With pooling:

• 10,000 requests = 50 pooled connections (reused)
• Connection time: 10-50ms × 50 = 0.5-2.5 seconds
• Total overhead: 0.5-2.5 seconds (100-200x faster!)

Auto-Scaling

Pool automatically scales based on demand:

Benchmarks

Hardware: 4-core CPU, 16GB RAM, PostgreSQL 17

🔧 Advanced Usage

Distributed Locking (Redis)

PSR-3 Logging

Metrics & Monitoring

🆚 Comparison

🧪 Test Results

All 32 tests passed - See TESTING_RESULTS.md for complete report.

Test Suite Overview

Performance Benchmarks

E-commerce Scenario Results

✅ Successful checkout - Inventory check → payment → order (all atomic) ✅ Failed checkout rollback - Payment fails → complete ROLLBACK (no data corruption) ✅ Concurrent checkout prevention - SELECT FOR UPDATE prevents overselling ✅ Multi-item cart - 3 products, $3999.96 total, all steps atomic

Read full report: TESTING_RESULTS.md

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Run composer check (PHPStan + Tests + CS-Fixer)
5. Submit a pull request

📄 License

MIT License. See LICENSE file.

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Built with AI-orchestrated development using Claude Code (Anthropic)