PDO_MYSQL DSN — Funktion · PHP-Referenz

Signatur

mysql:host=hostname;port=3306;dbname=database;unix_socket=path;charset=utf8mb4

Beschreibung

Der PDO_MYSQL DSN (Data Source Name) ist eine Zeichenkette, die dem PDO-MySQL-Treiber mitteilt, wie und wohin er sich verbinden soll. Er wird als erstes Argument dem PDO-Konstruktor übergeben und beginnt immer mit dem Präfix mysql:, gefolgt von Schlüssel-Wert-Paaren, die durch Semikolons getrennt werden.

Wichtige Parameter sind host (Hostname oder IP-Adresse des Servers), port (Standard: 3306), dbname (Name der Zieldatenbank), unix_socket (Pfad zum Unix-Socket, alternativ zu Host/Port) sowie charset (Zeichenkodierung der Verbindung, empfohlen: utf8mb4). Werden sowohl host als auch unix_socket angegeben, hat unix_socket Vorrang.

Das explizite Setzen des charset-Parameters im DSN ist der empfohlene Weg, um die Verbindungszeichenkodierung korrekt zu initialisieren – er ersetzt den früher verwendeten Aufruf von SET NAMES nach dem Verbindungsaufbau. Für vollständige Unicode-Unterstützung inklusive Emojis sollte utf8mb4 statt utf8 verwendet werden.

Der DSN selbst enthält keine Zugangsdaten (Benutzername und Passwort). Diese werden als zweites und drittes Argument an den PDO-Konstruktor übergeben, was die Trennung von Verbindungsstruktur und Authentifizierung sicherstellt.

Parameter

Name	Typ	Default	Beschreibung
$host	string	localhost	Hostname oder IP-Adresse des MySQL-Servers, z. B. `host=127.0.0.1`.
$port	int	3306	TCP-Port, auf dem der MySQL-Server lauscht, z. B. `port=3307`.
$dbname	string		Name der Zieldatenbank, z. B. `dbname=meineshop`. Kann auch nach dem Verbindungsaufbau per `USE`-Statement gewechselt werden.
$unix_socket	string		Pfad zum Unix-Domain-Socket, z. B. `unix_socket=/var/run/mysqld/mysqld.sock`. Ersetzt `host` und `port` bei lokalen Verbindungen.
$charset	string		Zeichenkodierung der Verbindung, z. B. `charset=utf8mb4`. Sollte immer explizit gesetzt werden, um Zeichensatzprobleme zu vermeiden.

Beispiele

Einfache TCP-Verbindung zu MySQL mit utf8mb4

<?php
$dsn = 'mysql:host=127.0.0.1;port=3306;dbname=shop;charset=utf8mb4';
$user = 'db_user';
$pass = 'geheimes_passwort';

try {
    $pdo = new PDO($dsn, $user, $pass, [
        PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        PDO::ATTR_EMULATE_PREPARES   => false,
    ]);
    echo "Verbindung erfolgreich!\n";

    $stmt = $pdo->query('SELECT VERSION() AS version');
    $row  = $stmt->fetch();
    echo 'MySQL-Version: ' . $row['version'] . "\n";
} catch (PDOException $e) {
    // Fehlermeldung nie im Produktionsbetrieb direkt ausgeben!
    error_log($e->getMessage());
    echo "Verbindungsfehler. Bitte später erneut versuchen.\n";
}

Verbindung erfolgreich! MySQL-Version: 8.0.35

Verbindung über Unix-Socket (typisch bei lokalen LAMP-Stacks)

<?php
$dsn = 'mysql:unix_socket=/var/run/mysqld/mysqld.sock;dbname=blog;charset=utf8mb4';

try {
    $pdo = new PDO($dsn, 'blog_user', 'secret', [
        PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ]);

    $stmt = $pdo->prepare('SELECT id, title FROM posts WHERE published = ? LIMIT 5');
    $stmt->execute([1]);

    foreach ($stmt->fetchAll() as $post) {
        echo $post['id'] . ': ' . $post['title'] . "\n";
    }
} catch (PDOException $e) {
    error_log($e->getMessage());
}

1: Willkommen im Blog 2: PHP 8.4 – Was ist neu? 3: PDO richtig nutzen

DSN aus Konfigurationsdatei zusammensetzen

<?php
// Konfiguration z. B. aus .env oder config.php
$config = [
    'host'    => 'db.example.com',
    'port'    => 3306,
    'dbname'  => 'crm',
    'charset' => 'utf8mb4',
];

$dsn = sprintf(
    'mysql:host=%s;port=%d;dbname=%s;charset=%s',
    $config['host'],
    $config['port'],
    $config['dbname'],
    $config['charset']
);

$pdo = new PDO($dsn, 'crm_user', 'crm_pass', [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

echo "Verbunden mit: " . $config['dbname'] . "\n";

Verbunden mit: crm

// Wichtig · Fallstricke

Sicherheit: Benutzername und Passwort gehören nie in den DSN-String, da dieser z. B. in Logs erscheinen kann. Immer als separate Parameter an den PDO-Konstruktor übergeben.

Zeichensatz: Ohne explizites charset im DSN verwendet MySQL unter Umständen latin1, was zu Datenverlust bei Sonderzeichen oder Emojis führt. Immer charset=utf8mb4 setzen – nicht nachträglich SET NAMES aufrufen, da dies nicht für vorbereitete Statements gilt.

SSL/TLS: Verschlüsselte Verbindungen werden nicht über den DSN, sondern über PDO-Treiber-Optionen wie PDO::MYSQL_ATTR_SSL_CA konfiguriert, die als viertes Argument an den PDO-Konstruktor übergeben werden.

Persistente Verbindungen: Mit der Option PDO::ATTR_PERSISTENT => true können Verbindungen wiederverwendet werden, was in PHP-FPM-Umgebungen jedoch selten nötig ist und zu schwer debuggbaren Fehlern führen kann.

Siehe auch

PDO PDO::__construct PDO::prepare PDO_PGSQL DSN PDO_SQLITE DSN