Obsługa bazy danych LocalDB

Pobieranie sterownika PHP

SQL Server Express LocalDB to lekki tryb instancji użytkownika SQL Server Express, dostępny wyłącznie w systemie Windows. Oba sterowniki łączą się z instancją LocalDB tak samo, jak z dowolną nazwaną instancją, używając formatu nazwy serwera (localdb)\<instance-name>.

Uwagi

LocalDB działa w ramach konta użytkownika systemu Windows. Programy wykorzystują uwierzytelnianie zintegrowane z systemem Windows, a nie uwierzytelnianie Microsoft Entra. Używaj go do lokalnego programowania w systemie Windows, gdy instancja bazy danych na użytkownika pasuje do Twojego workflow. To nie jest obraz kontenera ani usługa Azure.

Note

LocalDB nie jest dostępny w systemie Linux ani macOS. Połącz się zamiast tego z instancją SQL Server na obsługiwanym hoście. W przypadku kontenerów sprawdź obsługiwane platformy SQL Server w systemie Linux; nie zakładaj, że każda architektura macOS lub Linux może uruchomić obraz kontenera SQL Server.

Połącz się z instancją LocalDB

Zainstaluj obsługiwaną wersję SQL Server Express LocalDB oraz wymagany składnik ODBC i wybrane rozszerzenie PHP. Instalacja LocalDB nie działa, ponieważ rozszerzenie PHP nie jest załadowane.

Uruchom sqllocaldb.exe i w terminalu Windows, aby wyświetlić swoje instancje.
Jeśli MSSQLLocalDB nie istnieje, uruchom sqllocaldb.exe create MSSQLLocalDB.
Uruchom sqllocaldb.exe start MSSQLLocalDB, a następnie sqllocaldb.exe info MSSQLLocalDB, aby obejrzeć instancję. Wykonaj te kroki na koncie systemu Windows, które uruchamia program PHP.
Zapisz i uruchom jeden z programów za pomocą PHP z wiersza poleceń. Każdy domyślnie łączy się z master i weryfikuje, że obiektem docelowym jest faktycznie LocalDB. Nie są wymagane przykładowa baza danych ani hasło SQL.

Nazwa instancji jest lokalna dla maszyny Windows i konta właściciela. To nie jest nazwa hosta DNS, port TCP ani połączenie z innym komputerem.

SQLSRV

Zapisz ten program jako connect-localdb-sqlsrv.php, i uruchom php connect-localdb-sqlsrv.php.

<?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

Zapisz ten osobny program jako connect-localdb-pdo.php, i uruchom php connect-localdb-pdo.php.

<?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;
}

Oczekiwany wynik przy domyślnej konfiguracji:

LocalDB database: master

SQLSRV zwraca zasób połączenia i raportuje awarie połączenia jako false. PDO zwraca obiekt i rzuca PDOException w przypadku niepowodzenia konstrukcji. Program PDO wyraźnie umożliwia pobieranie numeryczne, więc wartość int to PHP int, co odpowiada wynikowi SQLSRV. Oba korzystają z UTF-8 do przechowywania danych znakowych oraz zwalniają uchwyty instrukcji i połączenia, nawet gdy zapytanie się nie powiedzie.

Wybierz istniejącą bazę danych lub dołącz plik

Programy akceptują następujące opcjonalne zmienne procesowe:

Variable	Meaning
`LOCALDB_INSTANCE`	Nazwa instancji bez przedrostka `(localdb)\`. Wartość domyślna to `MSSQLLocalDB`.
`LOCALDB_DATABASE`	Istniejąca nazwa bazy danych lub nazwa do przypisanej bazy danych. Wartość domyślna to `master`.
`LOCALDB_MDF`	Absolutna ścieżka do istniejącego, dostępnego `.mdf` pliku do dołączenia. Pomiń go przy łączeniu z już zarejestrowaną bazą danych.

Aby użyć bazy danych już zarejestrowanej w instancji, ustaw LOCALDB_DATABASE i pozostaw LOCALDB_MDF nieustawione. Aby dołączyć istniejący plik bazy danych, ustaw obie wartości. Na przykład w programie PowerShell:

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

Użyj pliku bazy danych przygotowanego do tego celu, a nie pliku nadal przypisanego do innej działającej instancji. Udziel kontu Windows dostępu do plików bazy danych i ich katalogu. AttachDBFileName nie tworzy brakującego pliku MDF, nie migruje bazy danych ani nie rozwiązuje niekompatybilnej wersji pliku bazy danych. Załącznik rejestruje bazę danych w instancji; zamknięcie PHP nie odłącza ani nie usuwa jej. Przetestuj ścieżkę przyłączenia każdego API ze stanu odłączonego, jeśli musisz zweryfikować oba niezależnie.

Ukośnik wzwrotny ciągu serwera jest uciekany w stringach PHP z pojedynczym cudzysłowem jako .\\ Ciągi ciągów w PHP z podwójnymi cudzysłowami interpretują także ukośniki i zmienne, więc program PDO celowo konstruuje ciąg instancji. Oba programy stosują sekwencję ucieczki dla nazwy bazy danych w połączeniu, zachowując oryginalną nazwę do weryfikacji i sprawdzania wyników. Sprawdzają też faktyczną ścieżkę systemu plików przed ucieczką od wartości załącznika. Dla każdej wartości połączenia podwójnie zamykają się klapsy i umieszczają wartość w nawiasach. SQLSRV wymaga escapingu nawet dla opcji ciągów znaków podanych w jego tablicy połączeń. Ustaw LOCALDB_DATABASE i LOCALDB_MDF na rzeczywistą nazwę i ścieżkę, bez samodzielnego dodawania ani podwajania nawiasów klamrowych.

Te połączenia korzystają z lokalnej instancji, a nie zdalnego serwera. W przypadku zdalnego programu SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, Baza danych SQL w usłudze Fabric lub Magazyn w usłudze Fabric użyj faktycznego punktu końcowego usługi. Ustaw jawnie uwierzytelnianie, szyfrowanie i weryfikację certyfikatów. Więcej informacji można znaleźć w artykule Łączenie z serwerem.

Diagnozuj problemy z kontem i instancją

Możesz też zarządzać bazami danych instancji LocalDB z linii poleceń za pomocą sqlcmd, na przykład sqlcmd -S "(localdb)\MSSQLLocalDB". Instancja LocalDB należąca do Twojego interaktywnego konta Windows nie przyznaje automatycznie dostępu tożsamości puli aplikacji Internet Information Services (IIS). Sprawdź własność instancji i uprawnienia plików podczas zmiany konta używanego do uruchamiania PHP. Więcej informacji można znaleźć w SQL Server Express LocalDB.

Objaw	Sprawdzanie
nie znaleziono `sqllocaldb.exe`	Potwierdź, że LocalDB jest zainstalowana i że jego narzędzie jest dostępne z poziomu terminala. Instalacja sterowników PHP nie wystarczy.
Nie znaleziono wystąpienia	Wyświetl instancje przy użyciu tego samego konta Windows, które uruchamia PHP, i sprawdź `LOCALDB_INSTANCE`.
Początkowe połączenie trwa zbyt długo	Uruchom instancję ręcznie i spróbuj ponownie z udokumentowanym limitem czasu logowania. Zbadaj błąd przy uruchamianiu instancji zamiast próbować w nieskończoność.
`master` Działa, ale `myData` nie działa	Potwierdź, że baza danych istnieje w tamtej instancji, albo skonfiguruj dostępny plik przyłączenia i nazwę bazy danych.
Dołączanie pliku nie powiodło się	Sprawdź dokładną ścieżkę, własność pliku, uprawnienia do katalogów, czy plik jest już używany oraz kompatybilność wersji LocalDB.
PHP w terminalu działa, ale IIS nie działa	Porównaj własność konta, własność instancji, dostęp do plików, konfigurację w czasie działania oraz ładowanie rozszerzenia. Nie zakładaj, że test interaktywny dowodzi dostępu do hostingu webowego.

Uruchamianie LocalDB oraz własność dla poszczególnych użytkowników należą do SQL Server LocalDB oraz systemu Windows. Rozszerzenia PHP oferują opcje połączenia przez ODBC. Nie dodawaj poświadczeń SQL ani opcji Microsoft Entra, aby zrekompensować problem z własnością instancji.

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-10-28