Drivers da Microsoft para PHP para SQL Server

Baixar driver PHP

Os drivers Microsoft para PHP para SQL Server são extensões PHP que permitem ler e gravar dados no Microsoft SQL Mecanismo de Banco de Dados a partir de scripts PHP. O pacote vem com dois drivers que envolvem o mesmo driver Microsoft ODBC para SQL Server e compartilham as mesmas opções de conexão, então você pode escolher a API que se encaixa no seu código:

• O SQLSRV expõe uma API procedural (sqlsrv_*funções) adaptada para recursos do SQL Server.
• PDO_SQLSRV implementa a interface PHP Data Objects (PDO), então o código que já usa PDO para outros bancos de dados pode direcionar SQL Server com mudanças mínimas.

Ambos os drivers se conectam ao Banco de Dados SQL do Azure, ao banco de dados SQL no Microsoft Fabric, ao Instância Gerenciada de SQL do Azure e a todas as versões e edições com suporte do SQL Server (incluindo as edições Express). Eles usam fluxos PHP para mover grandes valores binários e de caracteres sem carregá-los totalmente na memória.

Escolha o ponto de partida

• Para configurar um ambiente de desenvolvimento PHP e executar sua primeira consulta, comece pelo Passo 1: Configurar o ambiente de desenvolvimento, depois Passo 2: Criar um banco de dados SQL e Passo 3: Prova de conceito conectando a SQL usando PHP.
• Para instalar o driver no Linux ou macOS, comece pelo tutorial de Instalação para Linux e macOS e baixe os drivers da Microsoft para PHP para SQL Server.
• Para se conectar ao SQL do Azure com autenticação sem senha, comece com Conectar-se usando a autenticação do Microsoft Entra e Opções de conexão.
• Para tornar um app existente resiliente a falhas transitórias, vá para resiliência de conexão ociosa e Passo 4: Conecte resilientemente a SQL com PHP.
• Para decidir entre SQLSRV e PDO_SQLSRV, acesse Visão Geral dos Microsoft Drivers para PHP para SQL Server e Comparando funções de execução.
• Para diagnosticar um problema de instalação, conexão ou consulta, vá em Solução de Problemas, Gerenciamento de erros e avisos, e Atividade de log.
• Para tornar um app já existente mais rápido, vá para Performance Tuning.

Linha de base de produção para SQL do Azure

Use esse trecho como ponto de partida para uma conexão SQL do Azure voltada para produção com o driver PDO_SQLSRV. Ele lê o servidor e o banco de dados a partir de variáveis de ambiente (configurações do aplicativo do Serviço de Aplicativo do Azure, por exemplo), autentica com uma identidade gerenciada, habilita a Segurança da Camada de Transporte (TLS) com validação de certificado do servidor, define um tempo limite de login que cobre uma falha de inicialização a frio e define ConnectRetryCount e ConnectRetryInterval para resiliência de conexão ociosa do SQL Server. Os auxiliares connectWithRetry e queryWithRetry em nível de aplicativo envolvem a conexão inicial e cada instrução com uma retirada exponencial limitada e separam erros de conexão transitórios (que exigem uma nova conexão) de erros de consulta transitórios (que reutilizam a mesma conexão).

Requer PHP 8.0 e versões posteriores, a extensão PDO_SQLSRV e o Driver ODBC da Microsoft para SQL Server 17.3.1.1 e versões posteriores para Authentication=ActiveDirectoryMsi. Para a lista completa de valores suportadosAuthentication, veja Conectar usando autenticação Microsoft Entra.

<?php
declare(strict_types=1);

// Transient errors that require a fresh connection to recover. SQLSTATE values
// starting with '08' cover ODBC connection-established and connection-broken
// states (for example, 08001, 08S01).
const CONNECT_RETRY_SQLSTATE_PREFIX = '08';

// SQL Server error codes that are transient regardless of when they surface:
// 1205 (deadlock victim), 1222 (lock request timeout), and the Azure SQL
// throttling, mid-query failover, and "database not currently available"
// codes that arrive with SQLSTATE HY000.
const TRANSIENT_SERVER_ERROR_CODES = [1205, 1222, 40501, 40613, 40197, 10928, 10929, 49918];

/**
 * Open a connection, retrying transient failures with exponential backoff.
 */
function connectWithRetry(string $dsn, array $options, int $maxAttempts = 3): PDO
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $pdo = new PDO($dsn, null, null, $options);
            error_log(sprintf('connected on attempt %d/%d', $attempt, $maxAttempts));
            return $pdo;
        } catch (PDOException $e) {
            $sqlstate = (string) $e->getCode();
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = str_starts_with($sqlstate, CONNECT_RETRY_SQLSTATE_PREFIX)
                || in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('connect failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1); // 1, 2, 4 seconds
            error_log(sprintf('connect attempt %d hit transient %s/%d; retrying in %d seconds', $attempt, $sqlstate, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('connectWithRetry exhausted retries');
}

/**
 * Run a parameterized query, retrying transient statement failures on the same
 * connection. Deadlocks (1205) roll back the transaction before the driver sees
 * the error, so rerunning a single statement is safe. If the statement was part
 * of a multistatement transaction, wrap the whole transaction in your own retry
 * loop so earlier statements replay too.
 */
function queryWithRetry(PDO $pdo, string $sql, array $params = [], int $maxAttempts = 3): PDOStatement
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $stmt = $pdo->prepare($sql);
            $stmt->execute($params);
            return $stmt;
        } catch (PDOException $e) {
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('query failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1);
            error_log(sprintf('query attempt %d hit transient code %d; retrying in %d seconds', $attempt, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('queryWithRetry exhausted retries');
}

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;

if ($server === null || $database === null) {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE in your application configuration.');
}

$dsn = sprintf(
    'sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=%s;Database=%s;'
    . 'Encrypt=true;TrustServerCertificate=false;'
    . 'LoginTimeout=90;Authentication=ActiveDirectoryMsi;'
    . 'ConnectRetryCount=5;ConnectRetryInterval=15;'
    . 'MultiSubnetFailover=true;',
    $server,
    $database
);

$options = [
    PDO::ATTR_ERRMODE               => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE    => PDO::FETCH_ASSOC,
    PDO::ATTR_EMULATE_PREPARES      => false,
    PDO::SQLSRV_ATTR_QUERY_TIMEOUT  => 30,
];

$pdo = connectWithRetry($dsn, $options);
$stmt = queryWithRetry($pdo, 'SELECT TOP (?) name FROM sys.databases ORDER BY name', [5]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Este trecho de código foi ajustado para grupos de failover do Banco de Dados SQL do Azure e para o Instância Gerenciada de SQL do Azure.

• Driver={ODBC Driver 18 for SQL Server} fixa o driver ODBC 18. Se o host também tiver ODBC 17 instalado, PDO_SQLSRV pode vincular ao ODBC 17. Versões antigas 17.x rejeitam valores mais Authentication recentes; por exemplo, Authentication=ActiveDirectoryMsi requerem ODBC 17.3.1.1 ou uma versão posterior. Veja Valor inválido especificado para o atributo de cadeia de conexão 'Authentication'.

• ConnectRetryCounte ConnectRetryInterval são palavras-chave ODBC cadeia de conexão que possibilitam a resiliência da conexão ociosa no SQL Server: o driver reconecta de forma transparente uma conexão ociosa quebrada. Isso é diferente do queryWithRetry, em nível de aplicativo, que tenta novamente uma instrução que falha com um erro transitório, como um deadlock ou tempo limite de consulta. Os dois são complementares, então mantenha os dois. Certifique-se de que LoginTimeout seja pelo menos ConnectRetryCount * ConnectRetryInterval para que o caminho de reconexão ociosa receba seu orçamento total; O exemplo usa 90 segundos para cobrir 5 × 15 segundos de novas tentativas, além de uma margem para o login inicial em um failover a frio.

• Complemente as chamadas error_log() no nível do aplicativo com diagnósticos do lado do driver. Para PDO_SQLSRV, defina pdo_sqlsrv.log_severity em php.ini (configurável apenas durante a inicialização); para SQLSRV, chame sqlsrv_configure("LogSubsystems", ...) em tempo de execução. Para mais informações, veja Atividade de registro.

  ; php.ini - enable PDO_SQLSRV driver diagnostics alongside the application-level
  ; error_log() calls in the sample. Use 1 (errors) in production; -1 (all) is
  ; useful during triage but very chatty.
  [pdo_sqlsrv]
  pdo_sqlsrv.log_severity = 1
  

• Para uma identidade gerenciada atribuída pelo usuário, passe o ID da identidade como argumento $username do PDO (new PDO($dsn, $identityId, null, $options)). Use o ID do cliente da identidade no Serviço de Aplicativo do Azure ou Instância de Contêiner do Azure; caso contrário, use seu ID do objeto. Os drivers PHP herdam esse comportamento do driver Microsoft ODBC para SQL Server; para mais informações, veja Usando o Microsoft Entra ID com o driver ODBC. PDO_SQLSRV rejeita UID dentro do próprio DSN, portanto, use o slot do construtor. Passar null como o usuário (como o exemplo faz) seleciona a identidade gerenciada atribuída pelo sistema do host do Azure. Para SQLSRV (procedural), passe UID no array de opções de conexão.

• Defina MultiSubnetFailover=true ao se conectar a um listener de grupo de failover, listener de grupo de disponibilidade ou ponto de extremidade de instância de cluster de failover. Definir isso melhora o desempenho da conexão para listeners de grupo de disponibilidade de sub-rede única e de várias sub-redes. Para mais informações, veja Suporte para Alta Disponibilidade, recuperação de desastres.

• Para expansão de leitura ou réplica secundária para leitura, adicione ApplicationIntent=ReadOnly ao Nome da Fonte de Dados (DSN).

• Para nuvens soberanas onde o certificado Subject Alternative Name (SAN) não inclui o host ao qual você está se conectando, adicione HostNameInCertificate ao DSN (por exemplo, *.database.usgovcloudapi.net para Azure Governamental).

• O driver se baseia no Microsoft ODBC Driver for SQL Server subjacente para a obtenção de tokens. Os fluxos de identidade gerenciada, principal de serviço e token de acesso passam pelo ODBC. Para obter mais informações, consulte Usar o Microsoft Entra ID com o driver ODBC.

• Para maior segurança e portabilidade entre ambientes, mantenha as informações de conexão fora do seu código. Armazene informações de conexão no sistema de configuração do seu aplicativo e use o Azure Key Vault para valores sensíveis e configurações de conexão gerenciadas centralmente.

• A conexão SQLSRV equivalente usa sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) e retorna um recurso. O padrão de repetição é o mesmo: capturar um retorno false de sqlsrv_connect, inspecionar sqlsrv_errors() em busca de SQLSTATE e aguardar antes de tentar novamente. Para um exemplo resolvido, veja Passo 4: Conecte-se resilientemente ao SQL com PHP.

• Os auxiliares de repetição leem $e->errorInfo[1] protegido por isset(). PDOException::$errorInfo é declarado como ?array e tem como padrão null, portanto a verificação defensiva recorre a um código do driver 0 e deixa que o prefixo SQLSTATE 08 determine se deve tentar novamente.

Para obter mais informações sobre cada parte dessa configuração, consulte:

• Opções de conexão
• Conectar-se usando a autenticação do Microsoft Entra
• Resiliência da conexão ociosa
• Conectar-se ao Banco de Dados SQL do Microsoft Azure
• Suporte para Alta Disponibilidade, recuperação de desastres

Para o catálogo de erros transitórios do SQL do Azure, consulte Solucionar problemas de erros de conexão transitórios.

Características principais

• Duas APIs, um pacote de drivers: SQLSRV procedural para código SQL Server-first, ou PDO_SQLSRV para código PDO portátil.
• Suporte a plataforma ampla: Roda em Windows, Linux e macOS com versões PHP suportadas.
• Conexões criptografadas: Conexões criptografadas por TLS via Encrypt=true, com validação de certificado do servidor controlada por TrustServerCertificate.
• Autenticação do Microsoft Entra ID: conexões sem senha com fluxos de identidade gerenciada, principal de serviço e token de acesso por meio do driver ODBC da Microsoft para SQL Server subjacente.
• Always Encrypted: criptografia do lado do cliente para colunas sensíveis, com enclaves seguros opcionais para operações no local.
• Resiliência de conexão: repetições de conexão ociosa integradas com ConnectRetryCount e ConnectRetryInterval.
• Fluxos PHP: leia e grave grandes valores binários e de caracteres como fluxos em vez de carregá-los na memória.
• Amplo suporte a tipos de dados do SQL Server: datetimeoffset, parâmetros com valor de tabela, nvarchar, e Unicode com PDO::SQLSRV_ENCODING_UTF8.

Introdução

Configuração e conexão

Authenticate

Secure

Recuperar e atualizar dados

Tipos de dados

Erros e diagnóstico

Implantar e operar

Conteúdo de referência

Tarefas relacionadas

Conteúdo relacionado

• Microsoft Drivers para PHP para SQL Server no GitHub
• Driver ODBC da Microsoft para SQL Server
• módulos de conexão para o Banco de Dados SQL da Microsoft