Unterstützung für LocalDB

PHP-Treiber herunterladen

SQL Server Express LocalDB ist ein leichter Benutzerinstanzmodus von SQL Server Express, der nur unter Windows verfügbar ist. Beide Treiber verbinden sich mit einer LocalDB-Instanz auf die gleiche Weise wie mit jeder benannten Instanz, indem sie das (localdb)\<instance-name> Servernamensformular verwenden.

Bemerkungen

LocalDB läuft unter einem Windows-Benutzerkonto. Die Programme verwenden integrierte Windows-Authentifizierung, nicht Microsoft Entra-Authentifizierung. Nutzen Sie es für lokale Windows-Entwicklung, wenn eine Datenbankinstanz pro Benutzer zu Ihrem Workflow passt. Es ist kein Container-Image oder ein Azure-Service.

Note

LocalDB ist weder unter Linux noch macOS verfügbar. Verbinden Sie sich stattdessen mit einer SQL Server-Instanz auf einem unterstützten Host. Für Container prüfen Sie den unterstützten SQL Server unter Linux-Plattformen; gehen Sie nicht davon aus, dass jede macOS- oder Linux-Architektur das SQL Server-Container-Image ausführen kann.

Verbinden Sie sich mit einer LocalDB-Instanz

Installiere eine unterstützte SQL Server Express LocalDB-Version sowie sowohl die ODBC-Voraussetzung als auch die von dir ausgewählte PHP-Erweiterung. Bei der LocalDB-Installation wird eine PHP-Erweiterung nicht geladen.

Führe sqllocaldb.exe i in deinem Windows-Terminal aus, um deine Instanzen aufzulisten.
Wenn MSSQLLocalDB nicht existiert, führen Sie sqllocaldb.exe create MSSQLLocalDB aus.
Führe sqllocaldb.exe start MSSQLLocalDB aus und dann sqllocaldb.exe info MSSQLLocalDB, um die Instanz zu inspizieren. Führen Sie diese Schritte als das Windows-Konto aus, das das PHP-Programm ausführt.
Speichere und führe eines der Programme mit Kommandozeilen-PHP aus. Alle verbinden sich standardmäßig mit master und überprüfen, ob das Ziel tatsächlich die LocalDB ist. Keine Beispieldatenbank und kein SQL-Passwort sind erforderlich.

Der Instanzname ist lokal für den Windows-Rechner und das zugehörige Konto. Es handelt sich weder um einen DNS-Hostnamen, einen TCP-Port noch um eine Verbindung zu einem anderen Computer.

SQLSRV

Speichere dieses Programm als connect-localdb-sqlsrv.php, und führe php connect-localdb-sqlsrv.php aus.

<?php
$instance = getenv('LOCALDB_INSTANCE') ?: 'MSSQLLocalDB';
$database = getenv('LOCALDB_DATABASE');
if ($database === false || $database === '') {
    $database = 'master';
}
$file = getenv('LOCALDB_MDF');
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$options = ['Database' => $databaseValue, 'LoginTimeout' => 30, 'CharacterSet' => 'UTF-8'];
if ($file !== false && $file !== '') {
    if ($database === 'master' || !is_file($file)) {
        throw new RuntimeException('Set a non-master database name and an accessible MDF path.');
    }
    $options['AttachDBFileName'] = '{' . str_replace('}', '}}', $file) . '}';
}
$conn = sqlsrv_connect('(localdb)\\' . $instance, $options);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$stmt = null;
try {
    $stmt = sqlsrv_query(
        $conn,
        "SELECT DB_NAME() AS DatabaseName, CAST(SERVERPROPERTY('IsLocalDB') AS int) AS IsLocalDB"
    );
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    if ($row !== ['DatabaseName' => $database, 'IsLocalDB' => 1]) {
        throw new RuntimeException('Expected the selected LocalDB database.');
    }
    echo 'LocalDB database: ', $row['DatabaseName'], PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

PDO_SQLSRV

Speichere dieses separate Programm als connect-localdb-pdo.php, und führe php connect-localdb-pdo.php aus.

<?php
$instance = getenv('LOCALDB_INSTANCE') ?: 'MSSQLLocalDB';
$database = getenv('LOCALDB_DATABASE');
if ($database === false || $database === '') {
    $database = 'master';
}
$file = getenv('LOCALDB_MDF');
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$dsn = "sqlsrv:Server=(localdb)\\$instance;Database=$databaseValue;LoginTimeout=30";
if ($file !== false && $file !== '') {
    if ($database === 'master' || !is_file($file)) {
        throw new RuntimeException('Set a non-master database name and an accessible MDF path.');
    }
    $dsn .= ';AttachDBFileName={' . str_replace('}', '}}', $file) . '}';
}
$pdo = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE => true,
    PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
]);
$stmt = null;
try {
    $stmt = $pdo->query(
        "SELECT DB_NAME() AS DatabaseName, CAST(SERVERPROPERTY('IsLocalDB') AS int) AS IsLocalDB"
    );
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['DatabaseName' => $database, 'IsLocalDB' => 1]) {
        throw new RuntimeException('Expected the selected LocalDB database.');
    }
    echo 'LocalDB database: ', $row['DatabaseName'], PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Erwartete Ausgabe mit der Standardkonfiguration:

LocalDB database: master

SQLSRV gibt eine Verbindungsressource zurück und meldet Verbindungsausfälle als false. PDO gibt ein Objekt zurück und wirft, PDOException wenn die Konstruktion fehlschlägt. Das PDO-Programm aktiviert explizit numerisches Abrufen, sodass der int-Wert in PHP int ist, der mit dem SQLSRV-Ergebnis übereinstimmt. Beide verwenden UTF-8 für Zeichendaten und geben Statement-Handles sowie Verbindungs-Handles auch dann frei, wenn eine Abfrage fehlschlägt.

Wählen Sie eine bestehende Datenbank aus oder fügen Sie eine Datei an

Die Programme akzeptieren diese optionalen Prozessvariablen:

Variable	Bedeutung
`LOCALDB_INSTANCE`	Instanzname ohne das Präfix `(localdb)\`. Wird standardmäßig auf `MSSQLLocalDB` festgelegt.
`LOCALDB_DATABASE`	Ein bestehender Datenbankname oder der Name, der einer angehängten Datenbank zugewiesen werden soll. Wird standardmäßig auf `master` festgelegt.
`LOCALDB_MDF`	Absoluter Pfad zu einer vorhandenen, zugänglichen `.mdf`-Datei, die angehängt werden kann. Lassen Sie es weg, wenn Sie sich mit einer bereits registrierten Datenbank verbinden.

Um eine bereits bei der Instanz registrierte Datenbank zu verwenden, setzen Sie LOCALDB_DATABASE und lassen Sie LOCALDB_MDF ungesetzt. Um eine bestehende Datenbankdatei anzuhängen, legen Sie beide fest. Beispiel in PowerShell:

$env:LOCALDB_DATABASE = 'myData'
$env:LOCALDB_MDF = 'C:\Data\myData.mdf'

Verwenden Sie eine Datenbankdatei, die für diesen Zweck vorbereitet wurde, nicht eine Datei, die noch an eine andere laufende Instanz angehängt ist. Gewähren Sie dem Windows-Konto Zugriff auf die Datenbankdateien und deren Verzeichnis. AttachDBFileName erstellt keine fehlende MDF-Datei, migriert keine Datenbank und behebt keine Inkompatibilität der Datenbankdateiversion. Eine Verbindung registriert die Datenbank bei der Instanz; das Beenden des PHP-Skripts trennt oder löscht sie nicht. Teste den Pfad für das Anhängen jeder API im getrennten Zustand, wenn du beide unabhängig überprüfen musst.

Der Backslash des Server-Strings wird in einfach in Anführungszeichen gesetzten PHP-Strings mit einem Escape-Zeichen versehen als \\. Strings in doppelten Anführungszeichen in PHP interpretieren ebenfalls Backslashes und Variablen, sodass das PDO-Programm die Instanz-Zeichenkette bewusst konstruiert. Beide Programme escapen den Datenbanknamen für die Verbindung, behalten aber den ursprünglichen Namen für Validierungs- und Ergebnisprüfungen bei. Sie überprüfen auch den tatsächlichen Dateisystempfad, bevor sie den Anhangswert maskieren. Für jeden Verbindungswert verdoppeln sie die schließenden geschweiften Klammern und schließen den Wert in geschweifte Klammern ein. SQLSRV erfordert dieses Escape, selbst für String-Optionen, die in seinem Verbindungsarray übergeben werden. Setze LOCALDB_MDF den tatsächlichen Namen und Pfad LOCALDB_DATABASE ein, ohne selbst geschweifte Klammern hinzuzufügen oder zu verdoppeln.

Diese Verbindungen verwenden eine lokale Instanz, keinen entfernten Server. Für Remote SQL Server, Azure SQL-Datenbank, Azure SQL Managed Instance, Azure Synapse Analytics, SQL Database in Fabric oder Warehouse in Fabric verwenden Sie das eigentliche Service-Endpunkt. Legen Sie Authentifizierung, Verschlüsselung und Zertifikatsvalidierung explizit fest. Für weitere Informationen siehe Verbinden mit dem Server.

Konto- und Instanzprobleme diagnostizieren

Man kann auch die Datenbanken einer LocalDB-Instanz über die Kommandozeile mit sqlcmd verwalten, zum Beispiel sqlcmd -S "(localdb)\MSSQLLocalDB". Eine LocalDB-Instanz, die Ihrem interaktiven Windows-Konto gehört, gewährt nicht automatisch Zugriff auf die Identität eines Internetinformationsdienste (IIS)-Anwendungspools. Überprüfe den Eigentümer der Instanz und die Dateiberechtigungen, wenn du das Konto änderst, unter dem PHP ausgeführt wird. Weitere Informationen finden Sie unter SQL Server Express LocalDB.

Symptom	Prüfen
`sqllocaldb.exe` wurde nicht gefunden	Stellen Sie sicher, dass LocalDB installiert ist und ihr Dienstprogramm dem Terminal zur Verfügung steht. Die Installation der PHP-Treiber reicht nicht aus.
Die Instanz wurde nicht gefunden	Führen Sie Instanzen unter demselben Windows-Konto auf, unter dem PHP ausgeführt wird, und prüfen Sie `LOCALDB_INSTANCE`.
Die erste Verbindung dauert zu lange	Starte die Instanz explizit und versuche es erneut mit dem dokumentierten Login-Timeout. Untersuchen Sie einen Startfehler der Instanz, anstatt es endlos zu versuchen.
`master` funktioniert, aber eben `myData` nicht	Bestätigen Sie, dass die Datenbank in dieser Instanz existiert, oder konfigurieren Sie eine zugängliche Anhangsdatei und einen Datenbanknamen.
Dateianhang schlägt fehl	Überprüfen Sie den genauen Pfad, Dateibesitzer, Verzeichnisberechtigungen, ob die Datei bereits verwendet wird und die Kompatibilität der LocalDB-Version.
Terminal-PHP funktioniert, aber IIS nicht	Vergleiche das Konto, den Instanzbesitz, den Dateizugriff, die Laufzeitkonfiguration und das Laden der Erweiterungen. Gehen Sie nicht davon aus, dass ein interaktiver Test den Zugang zum Webhosting nachweist.

Der Start von LocalDB und die Eigentümerschaft pro Benutzer gehören zu SQL Server LocalDB und Windows. Die PHP-Erweiterungen bieten Verbindungsoptionen über ODBC. Füge keine SQL-Zugangsdaten oder Microsoft Entra-Optionen hinzu, um ein Problem mit Instanzbesitz auszugleichen.

Feedback

War diese Seite hilfreich?

Zuletzt aktualisiert um 2026-10-28