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 de variáveis de ambiente (por exemplo, das configurações do aplicativo no Serviço de Aplicativo do Azure), autentica com uma identidade gerenciada, habilita a Segurança da Camada de Transporte (TLS) com validação do certificado do servidor, define um tempo limite de login que cobre um failover após uma inicialização a frio e define ConnectRetryCount e ConnectRetryInterval para a resiliência de conexões ociosas do SQL Server. Os auxiliares connectWithRetry e queryWithRetry no nível da aplicação encapsulam tanto a conexão inicial quanto cada comando com um backoff exponencial limitado, e separam erros transitórios de conexão (que exigem uma nova conexão) de erros transitórios de consulta (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 de queryWithRetryno nível do aplicativo, que repete 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 de pelo menos ConnectRetryCount * ConnectRetryInterval para que o caminho de reconexão em inatividade receba todo o tempo previsto; o exemplo usa 90 segundos para cobrir 5 × 15 segundos de tentativas, mais uma margem adicional para o login inicial em um failover frio.

• Complemente as chamadas em nível error_log() de aplicação com diagnósticos do lado do motorista. 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 na Azure Container Instance; caso contrário, use o ID do objeto dela. 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 da própria DSN, então use o slot do construtor. Passar null como usuário (como a amostra) seleciona a identidade gerenciada atribuída pelo sistema ao 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 endpoint da instância de cluster de failover. Configurá-lo melhora o desempenho da conexão tanto para ouvintes de grupos de disponibilidade de sub-rede única quanto de múltiplas subredes. Para mais informações, veja Suporte para Alta Disponibilidade, recuperação de desastres.

• Para expansão de leitura ou uma réplica secundária legível, adicione ApplicationIntent=ReadOnly ao Nome da Origem 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. Identidade gerenciada, principal de serviço e fluxos de tokens de acesso passam todos 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 retentativa é o mesmo: pega um false retorno de sqlsrv_connect, inspeciona sqlsrv_errors() SQLSTATE e recua antes de tentar novamente. Para um exemplo resolvido, veja Passo 4: Conecte-se resilientemente ao SQL com PHP.

• As funções auxiliares de nova tentativa 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 Microsoft Entra ID: Conexões sem senha com identidade gerenciada, principal de serviço e token de acesso fluem pelo driver Microsoft ODBC 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: Conexão ociosa embutida tenta novamente com ConnectRetryCount e ConnectRetryInterval.
• Fluxos PHP: Leiam e escrevam valores binários e de caracteres grandes 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