{
    "slug": "mysql_dsn",
    "term": "MySQL DSN (Data Source Name)",
    "category": "php",
    "difficulty": "beginner",
    "short": "The connection string passed to PDO specifying the database driver, host, port, database name, and charset.",
    "long": "A MySQL DSN follows the format: mysql:host=hostname;port=3306;dbname=database;charset=utf8mb4. The charset parameter ensures the connection uses the correct encoding from the first packet. Omitting charset and using SET NAMES afterwards can cause a brief window where the wrong charset is active. Unix socket connections use unix_socket=/path/to/mysql.sock instead of host. The DSN does not include credentials — those are passed as separate constructor arguments.",
    "aliases": [
        "PDO DSN",
        "database connection string PHP",
        "mysql DSN format"
    ],
    "tags": [
        "php",
        "mysql",
        "database",
        "pdo"
    ],
    "misconception": "SET NAMES 'utf8mb4' after connecting is equivalent to charset=utf8mb4 in the DSN. SET NAMES is a workaround — charset in the DSN sets encoding at the protocol level before any queries run.",
    "why_it_matters": "A malformed DSN causes a cryptic connection error. Missing charset causes encoding bugs. Using the wrong host/port in different environments causes environment-specific failures.",
    "common_mistakes": [
        "Omitting charset from the DSN and relying on SET NAMES — encoding mismatch before SET NAMES executes.",
        "Hardcoding host/port in the DSN instead of reading from environment variables.",
        "Including the password in the DSN string instead of the constructor's second and third arguments."
    ],
    "when_to_use": [
        "Build the DSN from environment variables — never hardcode host, port, or database name.",
        "Always include charset=utf8mb4 in the DSN string."
    ],
    "avoid_when": [
        "Never include credentials in the DSN string — pass them as the second and third PDO constructor arguments.",
        "Do not hardcode DSN values — use environment variables for all connection parameters."
    ],
    "related": [
        "pdo",
        "mysql_charset_utf8mb4",
        "pdo_error_handling"
    ],
    "prerequisites": [
        "pdo"
    ],
    "refs": [
        "https://www.php.net/manual/en/ref.pdo-mysql.connection.php"
    ],
    "bad_code": "// Hardcoded, no charset, credentials in DSN string\n$pdo = new PDO('mysql:host=localhost;dbname=mydb;user=root;password=secret');",
    "good_code": "// Build DSN from environment\n$dsn = sprintf(\n    'mysql:host=%s;port=%d;dbname=%s;charset=utf8mb4',\n    $_ENV['DB_HOST'],\n    (int) ($_ENV['DB_PORT'] ?? 3306),\n    $_ENV['DB_NAME']\n);\n$pdo = new PDO($dsn, $_ENV['DB_USER'], $_ENV['DB_PASS']);",
    "quick_fix": "Always include charset=utf8mb4 in the DSN — do not rely on SET NAMES after connection",
    "effort": "low",
    "created": "2026-03-31",
    "updated": "2026-03-31",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/mysql_dsn",
        "html_url": "https://codeclaritylab.com/glossary/mysql_dsn",
        "json_url": "https://codeclaritylab.com/glossary/mysql_dsn.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 DSN (Data Source Name)](https://codeclaritylab.com/glossary/mysql_dsn) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/mysql_dsn"
            }
        }
    }
}