Solucionar os drivers da Microsoft para PHP para SQL Server

Baixar o Driver PHP

Diagnostice e resolva problemas comuns ao usar os drivers Microsoft para PHP para SQL Server para conectar ao SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL em Microsoft Fabric.

Para padrões gerais de tratamento de erros e avisos, veja Manipulação de erros e avisos. Para captura de diagnóstico do lado do motorista, veja Atividade de registro.

Problemas de instalação

Extensão não carregada

Sintomas:

phpinfo()Não lista a seção A sqlsrv ou (A).pdo_sqlsrv
PDOException: could not find driver ao construir A PDO com a sqlsrv: DSN.
Fatal error: Uncaught Error: Call to undefined function sqlsrv_connect().

Possíveis causas e soluções:

Extensão não ativada em php.ini. Verifique se tanto extension=sqlsrv se quanto extension=pdo_sqlsrv não foram comentadas. No Windows, use o nome completo do arquivo (extension=php_sqlsrv_84_ts_x64.dll). Para detalhes, veja Carregando os drivers.
Configuração errada de segurança da rosca. O binário do driver deve corresponder à segurança de threads da sua build PHP (ts para thread-safe, nts para não-thread-safe). Execute php -i | grep "Thread Safety" para verificar. Baixe o binário correspondente na página de download.
Driver Microsoft ODBC faltando. Os drivers PHP envolvem o Microsoft ODBC Driver for SQL Server. No Linux e macOS, instale msodbcsql18 (ou msodbcsql17) com seu gerenciador de pacotes antes de carregar as extensões. No Windows, instale o driver ODBC na página de download.

Verifique se a instalação foi bem-sucedida:

php -m | grep -i sqlsrv

Você deve ver ambos pdo_sqlsrv e sqlsrv na saída.

Falha na instalação do PECL no Linux ou macOS

Sintomas:

error: ‘SQL_HANDLE_DBC’ undeclared (first use in this function)
fatal error: 'sql.h' file not found

Correção:

Instale os cabeçalhos de desenvolvimento ODBC antes de executar pecl install:

Ubuntu e Debian: sudo apt-get install unixodbc-dev
Red Hat, Fedora e CentOS:sudo dnf install unixODBC-devel
Alpino: apk add unixodbc-dev
macOS: brew install unixodbc

Então tente novamente:

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

Se pecl ainda falhar após a instalação dos coletores, a cadeia de ferramentas de construção pode estar incompleta. Instale phpize, re2c, e um compilador C++ (build-essential no Debian e Ubuntu, gcc-c++ make no Red Hat e Fedora, no build-base Alpine).

Para o caminho completo de instalação, veja o tutorial de instalação para Linux e macOS.

Múltiplas versões de PHP instaladas

Sintomas:

phpinfo() no seu servidor web aparece uma versão do PHP, mas php -v na linha de comando aparece outra, e o driver aparece carregado apenas em uma delas.

Correção:

Cada versão do PHP tem seu php.ini próprio diretório ext . Localize o arquivo php --ini de configuração correto dentro do ambiente que esteja sem o driver e adicione as extension= linhas ali. Reinicie o servidor web (Apache, Nginx + PHP-FPM ou IIS) após qualquer alteração php.ini.

Problemas de conexão

Não consigo conectar ao servidor

Sintomas:

SQLSTATE[08001]: [Microsoft][ODBC Driver 18 for SQL Server]TCP Provider: A connection attempt failed
SQLSTATE[HYT00]: [Microsoft][ODBC Driver 18 for SQL Server]Login timeout expired

Possíveis causas e soluções:

O servidor não está acessível. Verifique se o nome do servidor e a porta estão corretos. Do host PHP, teste a conectividade pura do TCP.

# Linux and macOS
nc -vz <server>.database.windows.net 1433

# Windows PowerShell
Test-NetConnection -ComputerName <server>.database.windows.net -Port 1433

Firewall bloqueia a saída do 1433. Firewalls corporativos e NSGs em nuvem frequentemente bloqueiam a porta de saída 1433. Adicione uma exceção ou permita os intervalos de IP do Banco de Dados SQL do Azure para sua região.
SQL do Azure server firewall. Adicione o IP público do seu cliente às regras de firewall em nível de servidor no portal do Azure.
Instância nomeada. Para uma instância nomeada, verifique se o serviço SQL Server Browser está rodando no servidor e se o UDP 1434 está aberto. Ou, conecte-se por porta em vez do nome da instância.

Sintomas:

SQLSTATE[28000]: [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<user_id>'.

Possíveis causas e soluções:

Modo de autenticação SQL desativado. As instâncias locais do SQL Server têm por padrão apenas a Autenticação do Windows. Ative a autenticação em modo misto no SQL Server Management Studio em propriedades> doservidor Segurança e então reinicie o serviço SQL Server.
SQL do Azure credentials format. O SQL do Azure exige o nome de usuário totalmente qualificado (user@servername) ao se conectar a partir de ferramentas que não o adicionam automaticamente.
Usuário não mapeado para o banco de dados. Verifique se o login possui um mapeamento de usuário no banco de dados de destino e se o usuário possui as permissões necessárias.
Prefiro o Microsoft Entra ID. Para SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL no Fabric, use autenticação Microsoft Entra (Authentication=ActiveDirectoryMsi, Authentication=ActiveDirectoryServicePrincipal, ou um token de acesso) em vez de logins SQL. Consulte Conectar usando a autenticação do Microsoft Entra.

Valor inválido especificado para o atributo de cadeia de conexão 'Autenticação'

Sintomas:

SQLSTATE[08001]: [Microsoft][ODBC Driver 17 for SQL Server]Invalid value specified for connection string attribute 'Authentication'

Causa:

O driver ODBC reporta o erro, mas o verdadeiro problema é qual driver PDO_SQLSRV vinculado. Se a DSN não incluir uma Driver= palavra-chave e o host tiver ODBC 17 e ODBC 18 instalados, PDO_SQLSRV pode vincular à versão antiga. Versões antigas ODBC 17.x não conhecem valores mais recentes Authentication como ActiveDirectoryServicePrincipal ou ActiveDirectoryDefault, e até ActiveDirectoryMsi requerem ODBC 17.3.1.1 ou uma versão posterior.

Correção:

Fixe o driver no DSN:

<?php
$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$db;" .
       "Encrypt=true;Authentication=ActiveDirectoryMsi";
$conn = new PDO($dsn, null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);

A forma colcheada ({ODBC Driver 18 for SQL Server}) escapa dos espaços no nome do driver. A mensagem de erro em si sempre nomeia o driver que a reportou, então o prefixo [Microsoft][ODBC Driver 17 for SQL Server] no erro é a forma mais rápida de confirmar o driver incorreto.

A palavra-chave inválida 'UID' foi especificada na cadeia DSN

Sintomas:

SQLSTATE[IMSSP]: An invalid keyword 'UID' was specified in the DSN string.

Causa:

PDO_SQLSRV impõe uma lista de permitir palavras-chave DSN e não aceita UID nem PWD está na DSN. O PDO reserva os segundo e terceiro argumentos do construtor para esses casos, e PDO_SQLSRV os traduz internamente para ODBC UID/PWD .

Correção:

Mova o nome de usuário (e a senha, para autenticação SQL) para o construtor PDO:

<?php
// SQL authentication.
$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$db;Encrypt=true";
$conn = new PDO($dsn, $user, $password);

// User-assigned managed identity. Pass the identity's client ID as $username.
$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$db;" .
       "Encrypt=true;Authentication=ActiveDirectoryMsi";
$conn = new PDO($dsn, $clientId, null);

O driver procedural SQLSRV, por outro lado, aceita UID e PWD no array de opções de conexão passa para sqlsrv_connect().

PDO_SQLSRV ignora silenciosamente o AccessToken no array de opções

Sintoma:

Você tem um token de acesso Microsoft Entra (por exemplo, de az account get-access-token --resource https://database.windows.net/, , ou ClientSecretCredential), e o passa para PDO_SQLSRV como ['AccessToken' => $token] no quarto argumento ManagedIdentityCredentialdo construtor. A tentativa de conexão falha com um erro confuso como Windows logins are not supported in this version of SQL Server ou Login failed for user '', como se nenhuma credencial tivesse sido fornecida.

Causa:

O quarto argumento construtor do PDO é reservado para constantes de atributo específicas do driver (chaves inteiras como PDO::ATTR_ERRMODE). O PDO silenciosamente elimina entradas com string-key, como AccessToken, de modo que PDO_SQLSRV nunca veja o token. A conexão então retorna à autenticação integrada do Windows, que o servidor rejeita.

Correção:

Mude AccessToken para a sequência DSN. Reserve o array de opções para PDO::ATTR_* constantes.

<?php
$server = '<server>.database.windows.net';
$token  = getenv('SQL_ACCESS_TOKEN');   // raw JWT, no "Bearer " prefix

$dsn = "sqlsrv:Server=$server;Database=<database>;Encrypt=true;AccessToken=$token";
$conn = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Para exemplos adicionais de autenticação Microsoft Entra, incluindo o formulário DSN para PDO_SQLSRV, veja Conectar usando autenticação Microsoft Entra.

Para procedimento SQLSRV, AccessToken pertence ao array de conexão e informação passado para sqlsrv_connect(), que realmente envolve o JWT bruto em SQL_COPT_SS_ACCESS_TOKEN para você:

<?php
$server = '<server>.database.windows.net';
$token  = getenv('SQL_ACCESS_TOKEN');   // raw JWT, no "Bearer " prefix

$connectionInfo = [
    'Database'               => '<database>',
    'AccessToken'            => $token,
    'Encrypt'                => true,
    'TrustServerCertificate' => false,
    'Driver'                 => '{ODBC Driver 18 for SQL Server}',
];

$conn = sqlsrv_connect($server, $connectionInfo);
if ($conn === false) {
    print_r(sqlsrv_errors());
    exit(1);
}

Erros no certificado TLS

Sintomas:

SQLSTATE[08001]: SSL Provider: The certificate chain was issued by an authority that is not trusted
SQLSTATE[08001]: SSL Provider: The target principal name is incorrect

Soluções:

Prefira um certificado confiável. Use TrustServerCertificate=true apenas para desenvolvimento local em um servidor que você controla.

Para desenvolvimento com um certificado autoassinado:

<?php
$server   = 'localhost';
$database = '<database>';
$user     = '<user_id>';
$password = '<password>';

$dsn = "sqlsrv:Server=$server;Database=$database;Encrypt=true;TrustServerCertificate=true";
$conn = new PDO($dsn, $user, $password, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Caution

TrustServerCertificate=true Desativa a validação do certificado do servidor. Nunca leve esse cenário para produção, encenação ou ambientes compartilhados.

Para um nome de host de produção que não corresponde ao Nome Comum do certificado (por exemplo, ao conectar por um ouvinte), especifique o assunto real do certificado:

<?php
$dsn = "sqlsrv:Server=<listener>;Database=<database>;Encrypt=true;HostNameInCertificate=*.database.windows.net;Authentication=ActiveDirectoryMsi";
$conn = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Tempo de espera da conexão esgotado

Sintomas:

SQLSTATE[HYT00]: Login timeout expired

Possíveis causas e soluções:

LoginTimeout Não está configurado ou configurado muito baixo para o failover a frio. Defina um explicit LoginTimeout (em segundos) no DSN ao conectar ao SQL do Azure. Failovers em grupos de failover e bancos de dados de início a frio podem levar mais tempo do que um curto timeout do lado do cliente permite. Veja Opções de Conexão para a referência de opções.
Reconexão ociosa do orçamento truncado. Se você definir ConnectRetryCount e ConnectRetryInterval, certifique-se LoginTimeout >= ConnectRetryCount * ConnectRetryIntervalde . Caso contrário, o tempo de login encerra o loop de reconexão mais cedo. Veja resiliência da conexão ociosa.

<?php
$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=<server>.database.windows.net;Database=<database>;" .
       "Encrypt=true;LoginTimeout=90;ConnectRetryCount=5;ConnectRetryInterval=15;" .
       "Authentication=ActiveDirectoryMsi";
$conn = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Problemas de execução de consultas

Falhas silenciosas com PDO

Sintoma:

A PDO::exec() chamada de OR PDOStatement::execute() retorna false , mas não abre exceção.

Correção:

Com o PHP 8.0 e versões posteriores, o modo padrão de erro do PDO é PDO::ERRMODE_EXCEPTION. Se uma chamada retorna false sem ser lançada, a aplicação muda o modo para PDO::ERRMODE_SILENT ou PDO::ERRMODE_WARNING. Coloque de volta para o modo exceção para que falhas gerem exceções:

<?php
$conn = new PDO($dsn, $user, $password, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Se não puder mudar o modo globalmente, verifique $conn->errorInfo() (ou $stmt->errorInfo()) após cada chamada. O array contém [SQLSTATE, driver code, driver message].

Nome de objeto inválido

Sintomas:

SQLSTATE[42S02]: [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Invalid object name 'Products'.

Possíveis causas e soluções:

Contexto errado do banco de dados. Verifique com uma consulta rápida:

<?php
$stmt = $conn->query("SELECT DB_NAME()");
echo $stmt->fetchColumn();

Falta o qualificador de esquema. Use nomes totalmente qualificados para evitar depender do esquema padrão do chamador:
```
SELECT * FROM dbo.Products;
```
Diferenciação de maiúsculas e minúsculas. Bancos de dados criados com uma colação sensível a maiúsculas e minúsculas tratam products e Products como objetos diferentes. Corresponda exatamente ao caso na definição da tabela.

Número errado de parâmetros

Sintomas:

SQLSTATE[HY093]: Invalid parameter number
SQLSTATE[07002]: COUNT field incorrect or syntax error

Correção:

Para PDO_SQLSRV, o número de ? marcadores deve coincidir com o número de valores que você passa para execute(), e cada um ? vincula um único escalar (não um array). Para parâmetros nomeados, cada :name um no SQL deve aparecer no array e vice-versa.

<?php
$stmt = $conn->prepare(
    "SELECT * FROM dbo.Products WHERE CategoryID = ? AND ListPrice > ?"
);
$stmt->execute([1, 50.0]);
foreach ($stmt as $row) {
    // ...
}

Para SQLSRV, passe o array de parâmetros para sqlsrv_query() ou sqlsrv_prepare():

<?php
$stmt = sqlsrv_query(
    $conn,
    "SELECT * FROM dbo.Products WHERE CategoryID = ? AND ListPrice > ?",
    [1, 50.0]
);
if ($stmt === false) {
    die(print_r(sqlsrv_errors(), true));
}

Para uma introdução mais ampla à vinculação de parâmetros, veja Realizar consultas parametrizadas.

PDO emulado prepara erros de máscara

Sintomas:

Uma instrução executa com sucesso em uma conexão, mas gera um erro de sintaxe em outra conexão que usa o mesmo texto de consulta.

Causa:

PDO_SQLSRV suporta tanto declarações preparadas emuladas quanto nativas. Emulados preparam (PDO::ATTR_EMULATE_PREPARES = true) interpolam parâmetros do lado do cliente. Prepares nativos (false) enviam a consulta e os parâmetros separadamente para o servidor. O comportamento difere para TOP (?), parâmetros de tabela e alguns casos extremos na coerção do tipo.

Correção:

Prefiro preparados nativos em produção. Defina PDO::ATTR_EMULATE_PREPARES => false no momento da conexão para que o comportamento seja consistente entre os ambientes:

<?php
$conn = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE          => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_EMULATE_PREPARES => false,
]);

Para detalhes sobre quando usar cada modo, veja PDO::p repare.

Problemas com tipos de dados

Caracteres Unicode aparecem como `?` ou distorcidos

Sintomas:

As linhas que o PHP escreve contêm pontos de interrogação ou caracteres de substituição em vez dos caracteres originais não ASCII. As leituras retornam texto distorcido.

Possíveis causas e soluções:

O tipo de coluna é VARCHAR, não NVARCHAR. as colunas varchar usam uma página de códigos, não Unicode. Use nvarchar para texto internacionalizado.

Falta uma dica de codificação UTF-8 no PDO_SQLSRV. Quando sua coluna do SQL Server for nvarchar e seus dados PHP forem UTF-8, diga ao driver para converter entre UTF-8 (cliente) e UTF-16 (servidor):

<?php
$conn = new PDO(
    "sqlsrv:Server=<server>;Database=<database>;Encrypt=true",
    $user,
    $password,
    [
        PDO::ATTR_ERRMODE                    => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING            => PDO::SQLSRV_ENCODING_UTF8,
    ]
);

Driver SQLSRV: solicite UTF-8 explicitamente. SQLSRV_ENC_CHAR é a página padrão de código do sistema de 8 bits, não UTF-8. Para UTF-8 com SQLSRV, defina "CharacterSet" => "UTF-8" na conexão e passe o literal 'UTF-8' para SQLSRV_PHPTYPE_STRING no fetch ou bind. Veja Enviar e recuperar dados UTF-8.

Erros de conversão de data e hora

Sintomas:

SQLSTATE[22007]: Invalid character value for cast specification

Correção:

Em PDO_SQLSRV, não encaderne um objeto bruto DateTime . O PDO stringifica valores limitados antes de vincular, e o DateTime PHP não __toString() tem método, então execute([new DateTime(...)]) aumenta Object of class DateTime could not be converted to string. Formate o valor primeiro, ou passe uma string ISO 8601 (YYYY-MM-DD HH:MM:SS[.fff]), não uma string formatada localmente.

<?php
$stmt = $conn->prepare("INSERT INTO dbo.Events (EventDate) VALUES (?)");
$stmt->execute([(new DateTime("2026-03-15 10:00:00"))->format("Y-m-d H:i:s.u")]);

Para buscar colunas de data-hora como DateTime objetos em vez de strings em PDO_SQLSRV, defina o atributo da instrução:

<?php
$stmt = $conn->prepare("SELECT EventDate FROM dbo.Events");
$stmt->setAttribute(PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE, true);
$stmt->execute();

Para detalhes, veja Recuperar objetos de data-hora (PDO_SQLSRV).

Problemas de formatação decimal

Sintomas:

Valores entre -1 e 1 estão faltando um zero à frente, ou valores de dinheiro e dinheiro pequeno mostram um número inesperado de casas decimais.

Correção:

PDO_SQLSRV sempre busca valores decimais e numéricos como cadeias com sua precisão e escala exatas. Defina PDO::SQLSRV_ATTR_FORMAT_DECIMALS para adicionar um zero à esquerda aos valores entre -1 e 1:

<?php
$conn->setAttribute(PDO::SQLSRV_ATTR_FORMAT_DECIMALS, true);

PDO::SQLSRV_ATTR_DECIMAL_PLACES Aplica-se apenas a valores de dinheiro e de dinheiro pequeno . Ela define a escala exibida de 0 a 4 e pode arredondar o valor exibido. Isso não afeta valores decimais ou numéricos .

Para detalhes, veja Formatar decimais e dinheiro (PDO_SQLSRV) ou Formatar decimais e dinheiro (SQLSRV).

Problemas de transação

As mudanças nos dados não persistem

Sintomas:

Linhas que você insere ou atualiza no PHP não aparecem quando você consulta de outra sessão.

Causa:

PDO::beginTransaction()abre uma transação explícita que requer um .commit() Se o script PHP terminar sem chamar commit(), o PDO reverte a transação durante a limpeza da conexão.

Correção:

Sempre pareie beginTransaction() com commit(), e use try/catch para reverter em caso de erro:

<?php
try {
    $conn->beginTransaction();
    $conn->exec("INSERT INTO dbo.Orders (CustomerID, Total) VALUES (1, 100)");
    $conn->exec("UPDATE dbo.Inventory SET Stock = Stock - 1 WHERE ProductID = 5");
    $conn->commit();
} catch (PDOException $e) {
    $conn->rollBack();
    throw $e;
}

Para SQLSRV, use sqlsrv_begin_transaction, sqlsrv_commit, e sqlsrv_rollback.

Erros de deadlock

Sintomas:

SQLSTATE[40001]: [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Transaction (Process ID 62) was deadlocked

Correção:

Lidar com erros de deadlock transitórios com lógica de retentativa. Embrulhe toda a transação (não apenas a extração que falhou) para que extratos anteriores sejam reproduzidos na transação nova. Para um padrão de retentativa orientado para produção, veja o exemplo na página inicial do driver PHP.

Bloqueios recorrentes indicam um problema de projeto. Capture o gráfico de deadlock e analise quais instruções e tipos de bloqueio estão envolvidos. Correções comuns incluem reordenar operações para que transações concorrentes adquiram bloqueios na mesma sequência, redução do escopo das transações e adição de índices para diminuir a duração do bloqueio. Para um guia completo, veja o guia Deadlocks.

Problemas de resiliência de conexão

Reconexão não acontece

Sintomas:

Uma conexão ociosa permanece quebrada após um failover do Banco de Dados SQL do Azure, mesmo que você defina ConnectRetryCount e ConnectRetryInterval.

Possíveis causas e soluções:

Cursor ativo do lado do servidor. A resiliência da conexão ociosa só reconecta conexões ociosas . Um cursor aberto do lado do servidor ou uma transação pendente mantém a conexão ativa. Libere cursores do lado do servidor usando sqlsrv_free_stmt() ou $stmt = null; (PDO) antes da janela de failover, ou mude para um cursor bufferizado do lado do cliente. Veja resiliência da conexão ociosa.
Estado de sessão não recuperável. Alguns estados de sessão não podem ser restabelecidos, incluindo tabelas temporárias, cursores globais e locais, contexto de transação, bloqueios de aplicação, EXECUTE AS/REVERThandles de automação OLE, handles XML preparados e flags de traço. Qualquer um desses estados de sessão impede a reconexão automática.
LoginTimeout Muito pequeno. Se ConnectRetryCount * ConnectRetryInterval > LoginTimeout, o driver para de tentar novamente quando LoginTimeout é alcançado. Aumento LoginTimeout para cobrir o orçamento total de retentativas.

Problemas de desempenho

Para diagnóstico e remediação de consultas lentas, partidas a frio, conjuntos de resultados grandes e inserções em massa, veja Performance Tuning.

Habilitar diagnósticos de driver

Quando as chamadas em nível error_log() de aplicação não fornecerem informações suficientes, ative o registro do lado do motorista. Ele reporta todas as chamadas ODBC feitas pelo motorista.

PDO_SQLSRV

Configure pdo_sqlsrv.log_severityphp.ini e reinicie o servidor web. Essa configuração só é legível na inicialização:

[pdo_sqlsrv]
pdo_sqlsrv.log_severity = 1

Os valores são 0 (desligado, o padrão), -1 (erros, avisos e avisos), 1 (erros), 2 (avisos) e 4 (avisos).

SQLSRV

Ative o registro em tempo de execução com sqlsrv_configure():

<?php
sqlsrv_configure("LogSubsystems", SQLSRV_LOG_SYSTEM_CONN | SQLSRV_LOG_SYSTEM_STMT);
sqlsrv_configure("LogSeverity", SQLSRV_LOG_SEVERITY_ERROR | SQLSRV_LOG_SEVERITY_WARNING);

As entradas de log vão para o arquivo configurado por error_log em php.ini. Para a lista completa de subsistemas e severidades, veja Atividade de registro.

Problemas de contêiner e CI

Bibliotecas de sistema ausentes no Linux

Sintomas:

error while loading shared libraries: libodbc.so.2: cannot open shared object file
error while loading shared libraries: libssl.so.1.1: cannot open shared object file

Correção:

Instale as dependências de runtime antes de instalar o driver PHP:

Distribution	Comando de Instalação
Ubuntu e Debian	`sudo apt-get install unixodbc libgssapi-krb5-2`
Chapéu Vermelho e Fedora	`sudo dnf install unixODBC krb5-libs`
Alpine	`apk add unixodbc gcompat`

Depois, instale msodbcsql18 a partir do repositório de pacotes da Microsoft. Para repositórios e versões de pacotes específicos de distribuição, consulte o guia de instalação de drivers ODBC.

Builds de imagem Docker têm sucesso, mas conexões falham em tempo de execução

Sintomas:

A imagem se constrói e o PHP inicia, mas PDO::__construct() gera um erro ODBC de driver não encontrado.

Correção:

Verifique se o driver ODBC está instalado na imagem de runtime, não apenas na etapa de compilação. Instalar msodbcsql18 e unixodbc-dev estar na mesma fase em que é enviado para produção. Em uma construção em múltiplas etapas, instale-as na fase final. Uma instalação baseada em Debian de estágio único é a seguinte:

# Pin to a specific PHP minor version in production, for example php:8.4.11-cli.
FROM php:8.4-cli
RUN apt-get update && apt-get install -y --no-install-recommends \
        curl gnupg2 apt-transport-https ca-certificates \
    && curl -sSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > /usr/share/keyrings/microsoft.gpg \
    && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update \
    && ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 unixodbc-dev \
    # $PHPIZE_DEPS ships in the official php image and includes gcc, make, autoconf, and re2c.
    && apt-get install -y --no-install-recommends $PHPIZE_DEPS \
    && pecl install sqlsrv pdo_sqlsrv \
    && docker-php-ext-enable sqlsrv pdo_sqlsrv \
    && apt-get purge -y --auto-remove $PHPIZE_DEPS \
    && rm -rf /var/lib/apt/lists/*

Comentários

Esta página foi útil?

Last updated on 2026-08-13

Solucionar os drivers da Microsoft para PHP para SQL Server

Problemas de instalação

Extensão não carregada

Falha na instalação do PECL no Linux ou macOS

Múltiplas versões de PHP instaladas

Problemas de conexão

Não consigo conectar ao servidor

Falha no logon

Valor inválido especificado para o atributo de cadeia de conexão 'Autenticação'

A palavra-chave inválida 'UID' foi especificada na cadeia DSN

PDO_SQLSRV ignora silenciosamente o AccessToken no array de opções

Erros no certificado TLS

Tempo de espera da conexão esgotado

Problemas de execução de consultas

Falhas silenciosas com PDO

Nome de objeto inválido

Número errado de parâmetros

PDO emulado prepara erros de máscara

Problemas com tipos de dados

Caracteres Unicode aparecem como ? ou distorcidos

Erros de conversão de data e hora

Problemas de formatação decimal

Problemas de transação

As mudanças nos dados não persistem

Erros de deadlock

Problemas de resiliência de conexão

Reconexão não acontece

Problemas de desempenho

Habilitar diagnósticos de driver

PDO_SQLSRV

SQLSRV

Problemas de contêiner e CI

Bibliotecas de sistema ausentes no Linux

Builds de imagem Docker têm sucesso, mas conexões falham em tempo de execução

Conteúdo relacionado

Comentários

Recursos adicionais

Caracteres Unicode aparecem como `?` ou distorcidos