Prise en charge de la base de données locale

Télécharger le pilote PHP

SQL Server Express LocalDB est un mode léger à instance utilisateur de SQL Server Express, disponible uniquement sur Windows. Les deux pilotes se connectent à une instance LocalDB de la même manière qu’à n’importe quelle instance nommée, en utilisant le format de nom de serveur (localdb)\<instance-name>.

Remarques

La base de données locale s’exécute sous un compte utilisateur Windows. Les programmes utilisent l’authentification intégrée Windows, et non l’authentification Microsoft Entra. Utilisez-le pour le développement Windows en local lorsqu’une instance de base de données par utilisateur correspond à votre flux de travail. Ce n'est pas une image conteneur ni un service Azure.

Connectez-vous à une instance LocalDB

Installez une version prise en charge de SQL Server Express LocalDB ainsi que le prérequis ODBC ainsi que l’extension PHP que vous sélectionnez. L’installation de LocalDB ne charge pas d’extension PHP.

1. Exécutez sqllocaldb.exe i dans votre terminal Windows pour lister vos instances.
2. Si MSSQLLocalDB n’existe pas, exécutez sqllocaldb.exe create MSSQLLocalDB.
3. Exécutez sqllocaldb.exe start MSSQLLocalDB, puis sqllocaldb.exe info MSSQLLocalDB pour inspecter l’instance. Effectuez ces étapes avec le compte Windows qui exécute le programme PHP.
4. Sauvegardez et exécutez un des programmes avec PHP en ligne de commande. Chacun se connecte à master par défaut et vérifie que la cible est bien LocalDB. Aucun mot de passe de base de données d’exemple ou SQL n’est requis.

Le nom de l’instance est local pour la machine Windows et le compte propriétaire. Ce n’est pas un nom d’hôte DNS, un port TCP, ni une connexion à un autre ordinateur.

SQLSRV

Enregistrez ce programme sous le nom de connect-localdb-sqlsrv.php, et exécutez 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

Enregistrez ce programme séparé sous le nom de connect-localdb-pdo.php, et exécutez 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;
}

Sortie attendue avec la configuration par défaut :

LocalDB database: master

SQLSRV renvoie une ressource de connexion et rapporte les échecs de connexion sous la forme de false. PDO retourne un objet et lance PDOException si la construction échoue. Le programme PDO active explicitement la récupération numérique, de sorte que la valeur int soit de type PHP int, correspondant au résultat SQLSRV. Les deux utilisent UTF-8 pour les données de caractères et libèrent les handles de requête et de connexion, même en cas d’échec d’une requête.

Sélectionnez une base de données existante ou joignez un fichier

Les programmes acceptent ces variables de processus optionnelles :

Pour utiliser une base de données déjà enregistrée auprès de l’instance, définissez LOCALDB_DATABASE et laissez LOCALDB_MDF non défini. Pour joindre un fichier de base de données existant, définissez les deux. Par exemple, dans PowerShell :

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

Utilisez un fichier de base de données préparé à cet effet, et non un fichier encore attaché à une autre instance en cours. Accordez au compte Windows l’accès aux fichiers de base de données et à leur répertoire. AttachDBFileName ne recrée pas un fichier MDF manquant, ne migre pas une base de données et ne résout pas une incompatibilité de version du fichier de base de données. Un attachement enregistre la base de données auprès de l’instance ; fermer PHP ne le détache ni ne le supprime. Testez le chemin d’attachement de chaque API depuis un état détaché si vous devez vérifier les deux indépendamment.

La barre oblique inverse de la chaîne serveur est échappée dans les chaînes à guillemets simples PHP comme \\. Les chaînes entre guillemets doubles en PHP interprètent également les barres obliques inverses et les variables, donc le programme PDO construit délibérément la chaîne d’instance. Les deux programmes échappent le nom de la base de données pour la connexion tout en conservant le nom original pour la validation et les vérifications des résultats. Ils vérifient également le chemin réel du système de fichiers avant d’échapper la valeur de la pièce jointe. Pour chaque valeur de connexion, ils doublent les accolades fermantes et entourent la valeur d’accolades. SQLSRV requiert l’échappement, même pour les options de chaîne fournies dans son tableau de connexion. Définissez LOCALDB_DATABASE et LOCALDB_MDF avec le nom et le chemin réels, sans ajouter ni doubler vous-même les accolades.

Ces connexions utilisent une instance locale, pas un serveur distant. Pour les SQL Server distants, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, SQL database in Fabric ou Warehouse in Fabric, utilisez le véritable point de terminaison du service. Définissez explicitement l’authentification, le chiffrement et la validation des certificats. Pour plus d’informations, voir Connexion au serveur.

Diagnostiquer les problèmes de compte et d’instance

Vous pouvez aussi gérer les bases de données d’une instance LocalDB depuis la ligne de commande avec sqlcmd, sqlcmd -S "(localdb)\MSSQLLocalDB"par exemple. Une instance LocalDB que possède votre compte Windows interactif n'accorde pas automatiquement l'accès à une identité du pool d'applications Internet Information Services (IIS). Vérifiez la propriété de l’instance et les permissions du fichier lorsque vous changez le compte qui exécute PHP. Pour plus d’informations, voir SQL Server Express LocalDB.

Le démarrage de la base de données locale et la propriété par utilisateur appartiennent à SQL Server LocalDB et Windows. Les extensions PHP fournissent des options de connexion via ODBC. N'ajoutez pas d'identifiants SQL ou d'options Microsoft Entra pour compenser un problème de propriété d'instance.

Contenu connexe

• Connexion au serveur
• Base de données locale SQL Server Express