MySQL DSN (Data Source Name)

Also Known As

TL;DR

Explanation

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.

Watch Out

Common Misconception

Why It Matters

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.

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.

When To Use

• Build the DSN from environment variables — never hardcode host, port, or database name.
• Always include charset=utf8mb4 in the DSN string.

Code Examples

// Hardcoded, no charset, credentials in DSN string
$pdo = new PDO('mysql:host=localhost;dbname=mydb;user=root;password=secret');

// Build DSN from environment
$dsn = sprintf(
    'mysql:host=%s;port=%d;dbname=%s;charset=utf8mb4',
    $_ENV['DB_HOST'],
    (int) ($_ENV['DB_PORT'] ?? 3306),
    $_ENV['DB_NAME']
);
$pdo = new PDO($dsn, $_ENV['DB_USER'], $_ENV['DB_PASS']);

References

• ↗ https://www.php.net/manual/en/ref.pdo-mysql.connection.php

Tags

Related Terms