Supporto per LocalDB

Download del driver PHP

SQL Server Express LocalDB è una modalità leggera di istanza utente di SQL Server Express, disponibile solo su Windows. Entrambi i driver si collegano a un'istanza LocalDB nello stesso modo in cui si collegano a qualsiasi istanza denominata, utilizzando la forma del nome server (localdb)\<instance-name>.

Osservazioni:

LocalDB gira sotto un account utente Windows. I programmi utilizzano l'autenticazione integrata di Windows, non l'autenticazione Microsoft Entra. Usalo per lo sviluppo locale di Windows quando un'istanza di database per utente si adatta al tuo flusso di lavoro. Non è un'immagine container né un servizio Azure.

Connettiti a un'istanza LocalDB

Installa una versione supportata di SQL Server Express LocalDB e installa sia il prerequisito ODBC sia l'estensione PHP che scegli. L'installazione di LocalDB non carica un'estensione PHP.

1. Esegui sqllocaldb.exe i nel terminale Windows per elencare le tue istanze.
2. Se MSSQLLocalDB non esiste, esegui sqllocaldb.exe create MSSQLLocalDB.
3. Esegui sqllocaldb.exe start MSSQLLocalDB, poi sqllocaldb.exe info MSSQLLocalDB per ispezionare l'istanza. Esegui questi passaggi con l'account Windows che esegue il programma PHP.
4. Salva ed esegui uno dei programmi con PHP da riga di comando. Ognuno si connette a master per impostazione predefinita e verifica che il target sia effettivamente LocalDB. Non è richiesto alcun database di esempio né password SQL.

Il nome dell'istanza è locale per la macchina Windows e per l'account proprietario. Non è un nome host DNS, una porta TCP o una connessione a un altro computer.

SQLSRV

Salva questo programma come connect-localdb-sqlsrv.php, ed esegui 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

Salva questo programma separato come connect-localdb-pdo.php, e esegui 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;
}

Output atteso con la configurazione predefinita:

LocalDB database: master

SQLSRV restituisce una risorsa di connessione e riporta i fallimenti di connessione come false. PDO restituisce un oggetto e genera PDOException se la costruzione fallisce. Il programma PDO abilita esplicitamente il recupero numerico in modo che il valore int venga restituito come PHP int, corrispondente al risultato SQLSRV. Entrambi usano UTF-8 per i dati dei caratteri e rilasciano gli handle di statement e connessione anche quando una query fallisce.

Seleziona un database esistente o allega un file

I programmi accettano queste variabili opzionali di processo:

Per usare un database già registrato con l'istanza, imposta LOCALDB_DATABASE e lascia LOCALDB_MDF non impostato. Per allegare un file di database esistente, impostali entrambi. Ad esempio, in PowerShell:

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

Usa un file di database preparato a questo scopo, non un file ancora collegato a un'altra istanza in esecuzione. Concedere all'account Windows l'accesso ai file del database e alla loro directory. AttachDBFileName non crea un file MDF mancante, non migra un database né risolve una versione del file di database incompatibile. Una connessione registra il database con l'istanza; chiudere PHP non lo stacca né lo elimina. Testa il percorso di collegamento di ogni API da uno stato distaccato se devi verificare entrambi indipendentemente.

La barra inversa della stringa server viene sfuggita nelle stringhe a virgolette singole di PHP come \\. Le stringhe doppie virgolette PHP interpretano anche le barre diagonali e le variabili, quindi il programma PDO costruisce deliberatamente la stringa di istanza. Entrambi i programmi evitano il nome del database per la connessione mantenendo il nome originale per la validazione e i controlli dei risultati. Controllano anche il percorso effettivo del file system prima di uscire dal valore dell'allegato. Per ogni valore di connessione, raddoppiano le bricole di chiusura e racchiudono il valore in braccialetti. SQLSRV richiede l'escape anche per le opzioni stringa fornite nel suo array di connessione. Imposta LOCALDB_DATABASE e LOCALDB_MDF sul nome effettivo e sul percorso effettivo, senza aggiungere o raddoppiare le staffe tu stesso.

Queste connessioni utilizzano un'istanza locale, non un server remoto. Per SQL Server remoto, database SQL di Azure, Istanza gestita di SQL di Azure, Azure Synapse Analytics, database SQL in Fabric o Warehouse in Fabric, usa l'endpoint effettivo del servizio. Imposta esplicitamente autenticazione, crittografia e validazione dei certificati. Per maggiori informazioni, vedi Connessione al server.

Diagnostica i problemi di account e istanze

Puoi anche gestire i database di un'istanza LocalDB dalla riga di comando con sqlcmd, ad esempio sqlcmd -S "(localdb)\MSSQLLocalDB". Un'istanza LocalDB di proprietà del tuo account Windows interattivo non concede automaticamente l'accesso all'identità del pool applicativo di Internet Information Services (IIS). Controlla la proprietà dell'istanza e i permessi dei file quando cambi l'account che esegue PHP. Per maggiori informazioni, consulta SQL Server Express LocalDB.

L'avvio di LocalDB e la proprietà per utente appartengono a SQL Server LocalDB e Windows. Le estensioni PHP forniscono opzioni di connessione tramite ODBC. Non aggiungere credenziali SQL o opzioni Microsoft Entra per compensare un problema di proprietà delle istanza.

Contenuti correlati

• Connessione al server
• SQL Server Express LocalDB