Connexion à la base de données SQL Microsoft Azure

Télécharger le pilote PHP

Les pilotes SQLSRV et PDO_SQLSRV se connectent aux cibles SQL Azure et Fabric suivantes avec un nom de serveur entièrement qualifié et les options de connexion dans les options de connexion. SQLSRV prend un tableau d’options ; PDO_SQLSRV prend un nom de source de données (DSN), des arguments d’identifiants séparés lorsque nécessaire, et des attributs PDO.

Les deux extensions PHP activent par défaut les ensembles de résultats actifs multiples (MARS). Warehouse ne prend pas en charge MARS, donc désactivez-le explicitement dans le tableau d’options SQLSRV ou le DSN PDO_SQLSRV. Les bases de données SQL dans Fabric et Warehouse sont des produits distincts ; ne supposez pas qu'une fonctionnalité supportée par l'un est prise en charge par l'autre.

Préparez le point de terminaison, l’identité et l’hôte PHP

Votre processus PHP nécessite un accès réseau au point de terminaison SQL, un moyen de connexion pris en charge, et une autorisation pour ouvrir la base de données sélectionnée. Vérifiez chaque exigence séparément. Par exemple, ouvrir un port de pare-feu n’accorde pas l’accès à la base de données.

1. Installez l’extension PHP et le pilote Microsoft ODBC sur la machine ou le conteneur qui exécute PHP. Vérifiez l’extension dans ce processus, pas seulement dans un terminal de développement. Pour plus d’informations, voir Chargement des pilotes.
2. Copiez le serveur et la base de données à partir des détails de connexion de la cible. N’incluez pas le protocole HTTPS dans l’URL. Utilisez le nom d’hôte fourni par le service afin que la validation du certificat vérifie le point d’extrémité prévu. Un point de terminaison public Azure SQL Managed Instance peut inclure un port non par défaut ; conserver le port fourni.
3. Configurez l’accès réseau du service de votre hôte PHP. Pour un point de terminaison privé, confirmez la résolution privée des noms et un itinéraire depuis le réseau applicatif. Une règle de pare-feu public ne fournit pas de route vers une adresse privée.
4. Choisissez l’identité utilisée par le processus PHP. Pour une application hébergée sur Azure, activez son identité gérée et identifiez si elle est assignée au système ou à l’utilisateur. La connexion Azure CLI d'un développeur n'est pas l'identité gérée de l'application.
5. Faites en sorte qu’un administrateur de base de données accorde à cet identité, l’accès à la base de données sélectionnée ainsi que les autorisations minimales requises par l’application. Pour Warehouse, vérifiez aussi l’accès aux éléments/espaces de travail Fabric. Les permissions de gestion des ressources Azure ne délivrent pas à elles seules la permission de requête des tables d'application.
6. Définissez SQL_SERVER et SQL_DATABASE dans la configuration de l’application. Ne stockez pas de mot de passe pour les exemples d’identité gérée.

Les exemples vérifient une connexion sans créer de tables. Réussir ce contrôle ne prouve pas que l’identité peut lire ou écrire votre schéma d’application. Testez les opérations réelles séparément sous la même identité.

Utilisez l’authentification Microsoft Entra sans mot de passe

Utilisez une identité gérée lorsque votre environnement d’hébergement expose un point de terminaison à identité gérée et que la cible SQL accorde l’accès à cet identité. Les programmes complets suivants utilisent une identité managée assignée par le système. Ce ne sont pas des exemples de stations de travail. Exécutez-les sur l’hôte Azure configuré, avec SQL_SERVER et SQL_DATABASE disponible pour son processus PHP.

Les deux programmes désactivent MARS, donc le paramètre de connexion est également adapté lors de la sélection de Warehouse. Ils utilisent un énoncé actif à la fois. Pour la configuration de l’identité et autres modes d’authentification, voir Se connecter avec l’authentification Microsoft Entra.

Réglez SQL_DATABASE sur le nom exact de la base de données. Chaque programme crée une valeur échappée distincte pour la connexion en doublant les accolades fermantes et en mettant le nom entre accolades. Échapper empêche des caractères spéciaux dans le nom de la base de données de modifier la façon dont le pilote lit les paramètres de connexion. Les programmes conservent le nom original pour vérifier le résultat de DB_NAME().

SQLSRV

Enregistrez ce programme sous le nom de connect-azure-sqlsrv.php, et exécutez php connect-azure-sqlsrv.php sur l’hôte configuré.

<?php
$server = getenv('SQL_SERVER');
$database = getenv('SQL_DATABASE');
if ($server === false || $server === '' || $database === false || $database === '') {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

$conn = sqlsrv_connect($server, [
    'Database' => $databaseValue,
    'Authentication' => 'ActiveDirectoryMsi',
    'Encrypt' => true,
    'TrustServerCertificate' => false,
    'LoginTimeout' => 30,
    'MultipleActiveResultSets' => false,
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}

$stmt = null;
try {
    $stmt = sqlsrv_query(
        $conn,
        'SELECT DB_NAME() AS DatabaseName, CAST(1 AS int) AS Connected',
        [],
        ['QueryTimeout' => 30]
    );
    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, 'Connected' => 1]) {
        throw new RuntimeException('Unexpected database or connection result.');
    }
    echo 'Connected to ', $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-azure-pdo.php, et exécutez php connect-azure-pdo.php sur l’hôte configuré. Il définit PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE pour que le résultat int soit PHP int. Sans cela, PDO_SQLSRV renvoie cette colonne par défaut comme une chaîne. L’encodage PDO est un attribut, pas l’option SQLSRV CharacterSet .

<?php
$server = getenv('SQL_SERVER');
$database = getenv('SQL_DATABASE');
if ($server === false || $server === '' || $database === false || $database === '') {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$pdo = new PDO(
    "sqlsrv:Server=$server;Database=$databaseValue;Authentication=ActiveDirectoryMsi;"
    . "Encrypt=true;TrustServerCertificate=false;LoginTimeout=30;"
    . "MultipleActiveResultSets=false",
    null,
    null,
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
        PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE => true,
    ]
);

$stmt = null;
try {
    $stmt = $pdo->prepare(
        'SELECT DB_NAME() AS DatabaseName, CAST(1 AS int) AS Connected',
        [PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30]
    );
    $stmt->execute();
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['DatabaseName' => $database, 'Connected' => 1]) {
        throw new RuntimeException('Unexpected database or connection result.');
    }
    echo 'Connected to ', $row['DatabaseName'], '.', PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Si SQL_DATABASE est appdb, chaque programme imprime :

Connected to appdb.

ActiveDirectoryMsin'utilise pas votre connexion locale avec Azure CLI. Pour le développement local ou l’intégration continue (CI), choisissez une méthode d’authentification prise en charge par l’extension PHP et le pilote ODBC. Vous pouvez obtenir un jeton d’accès Microsoft Entra via une bibliothèque d’identité et le fournir via AccessToken. Lorsque vous utilisez un jeton, omettez le nom d’utilisateur, le mot de passe et le paramètre Authentication. Réglez AccessToken dans le tableau des options de connexion SQLSRV ou dans le DSN PDO_SQLSRV. Ne laissez pas de jetons dans le code source ni dans les journaux. Pour plus d’informations, consultez Connect à l’aide de l’authentification Microsoft Entra.

ActiveDirectoryServicePrincipal utilise un identifiant client et un secret client ; ce n’est pas une authentification sans mot de passe. Si vous l’utilisez, lisez le secret de la configuration protégée de l’application. L’authentification SQL est une alternative uniquement pour les cibles qui la prennent en charge ; ni la base de données SQL dans Fabric ni l’Entrepôt ne prennent en charge l’authentification SQL.

Adaptez l’authentification à votre environnement

Utilisez un seul mécanisme d’authentification pour chaque connexion. Ne laissez pas un ancien nom d’utilisateur, un ancien mot de passe ou un ancien paramètre Authentication en place lors du passage à AccessToken.

Demandez un jeton pour le service SQL, pas pour la gestion des ressources Azure. L’audience du jeton identifie le service qui l’accepte. Pour le cloud public Azure, demandez le scope https://database.windows.net/.default à votre bibliothèque d’identité. Confirmez la ressource appropriée pour un autre cloud. Passer le jeton à l’extension PHP sous forme de chaîne ; ne pas le convertir manuellement en une structure de jeton d’accès ODBC.

Un jeton peut expirer tant qu’un worker continue de fonctionner. Obtenir un jeton valide avant d’ouvrir une autre connexion, et rafraîchir les jetons si nécessaire dans les travailleurs de longue durée. Ne jamais enregistrer un DSN contenant un jeton d’accès. Pour plus d’informations sur l’authentification ODBC, voir Utilisation de Microsoft Entra ID avec le pilote ODBC.

Séparez le chiffrement et la vérification d’identité

Encrypt=true demande une connexion chiffrée. TrustServerCertificate=false nécessite la validation du certificat serveur, y compris son identité. L'authentification Microsoft Entra établit qui est votre application ; elle ne remplace pas la validation des certificats serveur.

Utilisez le point de terminaison fourni par le service SQL et maintenez le magasin de confiance des certificats du système d’exploitation client. Ne remplacez pas le nom d’hôte par une adresse IP pour contourner un problème de résolution de nom. Pour un point de terminaison privé, corrigez la résolution de noms et le routage tout en conservant le nom de connexion attendu du service.

LoginTimeout limite l’établissement de la connexion. QueryTimeout pour SQLSRV et PDO::SQLSRV_ATTR_QUERY_TIMEOUT pour PDO_SQLSRV s’appliquent à l’exécution des instructions. Augmenter le délai d’expiration de la requête ne corrigera pas un point de terminaison d’identité gérée manquant ni un utilisateur incorrect de la base de données.

Dépannage par étape de panne

SQLSRV retourne false et expose une collection d’erreurs via sqlsrv_errors(). Le constructeur PDO lève PDOException ; les exemples activent également les exceptions pour les échecs d’instruction. Capturez immédiatement les diagnostics dans les journaux restreints et gardez les avertissements SQLSRV distincts des erreurs. Ne retournez pas les diagnostics bruts, les jetons ou les détails de connexion à un navigateur.

Prévoyez les interruptions de connexion

Un service peut déconnecter une session inactive ou interrompre une opération lors de la maintenance ou du basculement. La résilience des connexions ODBC idle et les tentatives d’application résolvent différents problèmes. Pour les mots-clés de réessai et un test de déconnexion contrôlé, voir Idle connection resiliency.

Ne rejouez pas une opération d’écriture simplement parce que le client a perdu sa connexion. Le serveur a peut-être validé avant que la réponse ne soit perdue. Utilisez une politique de réessai spécifique à l’application et un moyen de détecter le travail en double. Libérez les instructions et les handles de connexion lorsque la requête ou le travail se termine, y compris les chemins d’erreur. Pour le comportement du cycle de vie et du pooling, voir Connexion au serveur.

Contenu connexe

• Se connecter à l’aide de l’authentification Microsoft Entra
• Options de connexion
• Comment accéder à Azure SQL Database depuis PHP