Verbinding maken met Microsoft Azure SQL Database

PHP-stuurprogramma downloaden

De SQLSRV- en PDO_SQLSRV-drivers verbinden met de volgende Azure en Fabric SQL-doelen met een volledig gekwalificeerde servernaam en de verbindingsopties in Verbindingsopties. SQLSRV neemt een optiesray; PDO_SQLSRV neemt een databronnaam (DSN), aparte argumenten voor inloggegevens indien nodig, en PDO-attributen.

Beide PHP-extensies schakelen standaard Multiple Active Result Sets (MARS) in. Warehouse ondersteunt MARS niet, dus schakel het expliciet uit in de SQLSRV-optiesarray of PDO_SQLSRV DSN. SQL-database in Fabric en Warehouse zijn aparte producten; ga er niet van uit dat een functie die door de een wordt ondersteund, ook door de ander wordt ondersteund.

Bereid het eindpunt, de identiteit en de PHP-host voor

Je PHP-proces heeft netwerktoegang nodig tot het SQL-eindpunt, een ondersteunde manier om in te loggen, en toestemming om de geselecteerde database te openen. Controleer elke vereiste apart. Bijvoorbeeld, het openen van een firewallpoort geeft geen databasetoegang.

1. Installeer de PHP-extensie en de Microsoft ODBC-driver op de machine of container die PHP draait. Controleer de extensie in dat proces, niet alleen in een ontwikkelterminal. Voor meer informatie, zie Het laden van de stuurprogramma's.
2. Kopieer de server en database uit de verbindingsgegevens van het doel. Voeg geen HTTPS URL-schema toe. Gebruik de door de service geleverde hostnaam zodat certificaatvalidatie het beoogde eindpunt controleert. Een publiek eindpunt van Azure SQL Managed Instance kan een niet-standaard poort bevatten; behoud de meegeleverde poort.
3. Stel de netwerktoegang van de dienst voor je PHP-host in. Voor een privé-endpoint bevestig de resolutie van de private naam en een route vanuit het applicatienetwerk. Een openbare firewallregel biedt geen route naar een privéadres.
4. Kies de identiteit die door het PHP-proces wordt gebruikt. Voor een door Azure gehoste applicatie schakel je de beheerde identiteit in en bepaal je of deze systeem- of door de gebruiker is toegewezen. De Azure CLI-inlogfunctie van een ontwikkelaar is niet de beheerde identiteit van de applicatie.
5. Laat een databasebeheerder die identiteit toegang geven tot de geselecteerde database en de minimale rechten verlenen die de applicatie nodig heeft. Voor Warehouse controleer ook toegang tot Fabric items/werkruimtes. Azure resource-management rechten geven op zichzelf geen toestemming om applicatietabellen te bevragen.
6. Stel SQL_SERVER en SQL_DATABASE in de configuratie van de applicatie in. Sla geen wachtwoord op voor de voorbeelden voor beheerde identiteit.

De voorbeelden verifiëren een verbinding zonder tabellen aan te maken. Het doorstaan van deze controle bewijst niet dat deze identiteit je applicatieschema kan lezen of schrijven. Test de daadwerkelijke bewerkingen apart onder dezelfde identiteit.

Gebruik wachtwoordloze Microsoft Entra-authenticatie

Gebruik een beheerde identiteit wanneer je hostingomgeving een beheerde-identiteitsendpoint blootstelt en het SQL-doel die identiteit toegang verleent. De volgende volledige programma's gebruiken een door het systeem toegewezen beheerde identiteit. Het zijn geen voorbeelden van werkstations. Voer ze uit op de geconfigureerde Azure-host, met SQL_SERVER en SQL_DATABASE beschikbaar voor het PHP-proces.

Beide programma's schakelen MARS uit, dus de verbindingsinstelling is ook geschikt bij het selecteren van Warehouse. Ze gebruiken telkens één actieve statement. Voor identiteitsinstelling en andere authenticatiemodi, zie Verbinding maken met Microsoft Entra-authenticatie.

Stel SQL_DATABASE in op de daadwerkelijke databasenaam. Elk programma creëert een aparte ontsnapte waarde voor de verbinding door sluitende accolades te verdubbelen en de naam tussen accolades te omsluiten. Escaping voorkomt dat speciale tekens in de databasenaam van invloed zijn op hoe de driver de verbindingsinstellingen leest. De programma's behouden de oorspronkelijke naam om het resultaat van DB_NAME()te controleren.

SQLSRV

Sla dit programma op als connect-azure-sqlsrv.php, en voer php connect-azure-sqlsrv.php uit op de geconfigureerde host.

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

Sla dit aparte programma op als connect-azure-pdo.php, en voer php connect-azure-pdo.php uit op de geconfigureerde host. Het stelt PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE in zodat het int-resultaat PHP intis. Zonder dit geeft PDO_SQLSRV deze kolom standaard als string terug. PDO encoding is een attribuut, niet de SQLSRV-optie 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;
}

Als SQL_DATABASEappdb is, drukt elk programma het volgende af:

Connected to appdb.

ActiveDirectoryMsigebruikt je lokale Azure CLI-aanmelding niet. Voor lokale ontwikkeling of continue integratie (CI) kiest u een authenticatiemethode die wordt ondersteund door de PHP-extensie en ODBC-driver. Je kunt een Microsoft Entra toegangstoken verkrijgen via een identiteitsbibliotheek en deze leveren via AccessToken. Laat bij het gebruik van een token de gebruikersnaam, het wachtwoord en de instelling Authentication weg. Stel AccessToken in de SQLSRV-verbindingsoptiesarray of in de PDO_SQLSRV-DSN in. Houd tokens uit broncode en logboeken. Zie Connect using Microsoft Entra authentication voor meer informatie.

ActiveDirectoryServicePrincipal gebruikt een client-ID en client secret; het is geen wachtwoordloze authenticatie. Als je het gebruikt, lees dan het geheim uit de beschermde applicatieconfiguratie. SQL-authenticatie is alleen een alternatief voor doelomgevingen die dit ondersteunen; noch SQL-databases in Fabric noch Warehouse ondersteunen SQL-authenticatie.

Pas authenticatie aan je omgeving aan

Gebruik één authenticatiemechanisme voor elke verbinding. Laat geen oude gebruikersnaam, wachtwoord of Authentication instelling staan bij het overschakelen naar AccessToken.

Vraag een token aan voor de SQL-service, niet voor Azure resource management. De audience van de token identificeert de dienst die het accepteert. Voor Azure public cloud vraag je de scope https://database.windows.net/.default aan via je identiteitsbibliotheek. Bevestig de juiste bron voor een andere cloud. Geef het token door aan de PHP-extensie als een string; zet het niet handmatig om in een ODBC access-token structuur.

Een token kan verlopen terwijl een worker blijft draaien. Verkrijg een geldig token voordat je een andere verbinding opent, en vernieuw tokens indien nodig bij langlopende werkers. Log nooit een DSN met een toegangstoken. Voor meer informatie over ODBC-authenticatie, zie Gebruik van Microsoft Entra ID met de ODBC-driver.

Houd encryptie en identiteitscontroles gescheiden

Encrypt=true vraagt om een versleutelde verbinding. TrustServerCertificate=false vereist validatie van het servercertificaat, inclusief de identiteit ervan. Microsoft Entra-authenticatie stelt vast wie je applicatie is; het vervangt geen servercertificaatvalidatie.

Gebruik het endpoint dat door de SQL-service wordt geleverd en behoud de certificaatvertrouwensopslag van het clientbesturingssysteem. Vervang de hostnaam niet door een IP-adres om een naamresolutieprobleem te omzeilen. Voor een privé-endpoint moet je naamresolutie en routering corrigeren, terwijl je de verwachte verbindingsnaam van de service behoudt.

LoginTimeout begrenst het tot stand brengen van verbindingen. QueryTimeout voor SQLSRV en PDO::SQLSRV_ATTR_QUERY_TIMEOUT voor PDO_SQLSRV zijn van toepassing op de uitvoering van instructies. Het verhogen van een query-timeout zal geen ontbrekend managed-identity endpoint of een onjuiste databasegebruiker repareren.

Probleemoplossing per faalfase

SQLSRV retourneert false en stelt een foutverzameling bloot via sqlsrv_errors(). De PDO-constructie genereert PDOException; de voorbeelden maken ook uitzonderingen mogelijk voor fouten bij statements. Leg diagnostische gegevens direct vast in beperkte logs en houd SQLSRV-waarschuwingen onderscheiden van fouten. Stuur geen ruwe diagnostiek, tokens of verbindingsgegevens terug naar een browser.

Plan voor onderbroken verbindingen

Een dienst kan een inactieve sessie loskoppelen of een operatie onderbreken tijdens onderhoud of failover. ODBC-veerkracht van inactieve verbindingen en nieuwe pogingen van de applicatie lossen verschillende problemen op. Zie Idle connection resiliency voor trefwoorden voor opnieuw proberen en een gecontroleerde disconnectietest.

Voer een schrijfactie niet opnieuw uit alleen omdat de client de verbinding is kwijtgeraakt. De server heeft mogelijk al een commit uitgevoerd voordat de respons verloren ging. Gebruik een applicatie-specifiek herkansingsbeleid en een manier om dubbel werk te detecteren. Geef statements en verbindingshandles vrij wanneer het verzoek of de taak is afgerond, inclusief foutpaden. Voor levenscyclus en poolgedrag, zie Verbinden met de server.

Verwante onderwerpen

• Verbinding maken door gebruik te maken van Microsoft Entra-verificatie
• Verbindingsopties
• Hoe toegang te krijgen tot Azure SQL Database vanuit PHP