{
    "slug": "mysql_connection_pooling",
    "term": "MySQL Connection Pooling",
    "category": "php",
    "difficulty": "intermediate",
    "short": "Reusing database connections across requests instead of opening and closing a new connection on every request.",
    "long": "Opening a MySQL connection involves TCP handshake, authentication, and session setup — typically 5–20ms. In high-traffic PHP-FPM applications, creating a new connection per request wastes significant time. PDO does not have a built-in connection pool, but PDO::ATTR_PERSISTENT enables persistent connections reused across requests within the same PHP-FPM worker process. External poolers like ProxySQL or PgBouncer are preferred for production — they provide proper connection limits, health checks, and load balancing.",
    "aliases": [
        "PDO persistent connection",
        "PHP MySQL connection pool",
        "ProxySQL PHP"
    ],
    "tags": [
        "php",
        "mysql",
        "database",
        "performance"
    ],
    "misconception": "PDO::ATTR_PERSISTENT is safe to use everywhere. Persistent connections can leak transaction state between requests — always ensure no open transaction exists before returning a persistent connection to the pool.",
    "why_it_matters": "Under load, hundreds of simultaneous short-lived connections overwhelm MySQL's max_connections limit, causing 'Too many connections' errors. Pooling keeps the connection count stable regardless of request volume.",
    "common_mistakes": [
        "Using persistent connections with transactions — a crashed request leaves an open transaction on a reused connection.",
        "Setting max_connections too low in MySQL without a connection pooler — causing connection queue timeouts.",
        "Opening multiple PDO instances in the same script — use a singleton or DI container to share one connection."
    ],
    "when_to_use": [
        "Use PDO::ATTR_PERSISTENT for simple single-server apps where max_connections is a concern.",
        "Use ProxySQL or PgBouncer for multi-server production environments needing health checks and load balancing."
    ],
    "avoid_when": [
        "Avoid PDO::ATTR_PERSISTENT when using transactions — a crashed request can leave an open transaction on a reused connection.",
        "Do not use persistent connections with different database users in the same pool — connections are reused regardless of credentials."
    ],
    "related": [
        "pdo",
        "database_connection_pool",
        "pdo_error_handling"
    ],
    "prerequisites": [
        "pdo",
        "mysql_dsn"
    ],
    "refs": [
        "https://www.php.net/manual/en/pdo.connections.php"
    ],
    "bad_code": "// New connection on every request — 10ms × 1000 req/s = 10s wasted per second\nfunction getUser(int $id): array {\n    $pdo = new PDO($dsn, $user, $pass); // new connection every call\n    return $pdo->query(\"SELECT * FROM users WHERE id = $id\")->fetch();\n}",
    "good_code": "// ProxySQL handles pooling externally — PHP connects to ProxySQL port\n$pdo = new PDO('mysql:host=127.0.0.1;port=6033;dbname=app', $user, $pass, [\n    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,\n]);\n\n// OR: PDO persistent for single-server low-traffic apps\n$pdo = new PDO($dsn, $user, $pass, [\n    PDO::ATTR_PERSISTENT => true,\n    PDO::ATTR_ERRMODE    => PDO::ERRMODE_EXCEPTION,\n]);",
    "quick_fix": "Use PDO::ATTR_PERSISTENT => true for simple cases, or deploy ProxySQL in front of MySQL for production connection management",
    "effort": "medium",
    "created": "2026-03-31",
    "updated": "2026-03-31",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/mysql_connection_pooling",
        "html_url": "https://codeclaritylab.com/glossary/mysql_connection_pooling",
        "json_url": "https://codeclaritylab.com/glossary/mysql_connection_pooling.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[MySQL Connection Pooling](https://codeclaritylab.com/glossary/mysql_connection_pooling) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/mysql_connection_pooling"
            }
        }
    }
}