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, SQL Database no Microsoft Fabric, Instância Gerenciada de SQL do Azure e todas as versões e edições suportadas 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

Conexão rápida

O trecho a seguir é a conexão de ponta a ponta mais curta que uma instalação PHP funcional pode rodar contra SQL Server ou SQL do Azure. Use para confirmar que seu driver, dependências ODBC e caminho de rede estão conectados antes de passar para a linha de produção na próxima seção.

<?php
$server   = getenv('SQL_SERVER')   ?: 'localhost';
$database = getenv('SQL_DATABASE') ?: 'master';
$user     = getenv('SQL_USER');
$password = getenv('SQL_PASSWORD');

$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$database;Encrypt=true";
$pdo = new PDO($dsn, $user, $password, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

foreach ($pdo->query('SELECT @@VERSION AS version') as $row) {
    echo $row['version'], PHP_EOL;
}

Para uma conexão sem senha contra SQL do Azure, adicione Authentication=ActiveDirectoryMsi (identidade gerenciada) ou outro Authentication valor à DSN e elimine os $user/$password argumentos. A linha de produção que segue expande o mesmo padrão com tentativas, timeouts e diagnósticos.

Para um SQL Server local que usa um certificado autoassinado, Encrypt=true a validação falha. Adicione TrustServerCertificate=true apenas para desenvolvimento local. Veja erros de certificado TLS para as alternativas de produção.

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 do ambiente (como as configurações do app do Serviço de Aplicativo do Azure, por exemplo), autentica com uma identidade gerenciada, habilita o Transport Layer Security (TLS) com validação de certificados de servidor, define um timeout de login que cobre um failover de início a frio e define ConnectRetryCount resiliência ConnectRetryInterval de conexão ociosa do SQL Server. O nível connectWithRetry de aplicação e queryWithRetry os auxiliares envolvem tanto a conexão inicial quanto cada instrução com um backoff exponencial limitado, e separam erros de conexão transitória (que exigem uma conexão nova) dos erros de consulta transitória (que reutilizam a mesma conexão).

Requer PHP 8.0 e versões posteriores, a extensão PDO_SQLSRV e Microsoft driver ODBC 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} pina 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 'Autenticação'.

• 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 nível queryWithRetryde aplicação , que tenta novamente uma instrução que falha com um erro transitório, como um deadlock ou timeout de consulta. Os dois são complementares, então mantenha os dois. Certifique-se LoginTimeout de que pelo ConnectRetryCount * ConnectRetryInterval menos o caminho de reconexão ociosa receba seu orçamento completo; a amostra usa 90 segundos para cobrir 5 × 15 segundos de tentativas mais margem 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 ( php.ini configurável apenas na 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 do $username PDO (new PDO($dsn, $identityId, null, $options)). Use o ID do cliente da identidade no Serviço de Aplicativo do Azure ou no Azure Container Instance; caso contrário, use o ID do objeto dele. 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 o array de opções de conexão.

• Defina MultiSubnetFailover=true quando você se conecta a um ouvinte de grupo de failover, ouvinte de grupo de disponibilidade ou endpoint de 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 escala de leitura ou um secundário legível, 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 depende do driver Microsoft ODBC para SQL Server para aquisiçã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.

• Os ajudantes de retentar lêem $e->errorInfo[1] protegidos por isset(). PDOException::$errorInfo é declarado como ?array e tem por padrão , nullentão a verificação defensiva volta para um código de driver de 0 e deixa o prefixo SQLSTATE 08 decidir se tenta 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.
• Suporte a tipos de dados para Rich SQL Server: datetimeoffset, parâmetros de valores em tabelas, 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

Reference

Tarefas relacionadas

Conteúdo relacionado

• Microsoft Drivers para PHP para SQL Server no GitHub
• Driver ODBC da Microsoft para SQL Server
• Drivers do SQL Server