Solucionar problemas do Microsoft Driver do OLE DB para SQL Server

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsBanco de Dados SQL no Microsoft Fabric

Use este artigo para identificar a fase de falha de uma operação OLE DB, escolher a próxima verificação e encontrar instruções detalhadas de solução de problemas. A orientação utiliza o provedor atual, MSOLEDBSQL19. Para defeitos específicos de lançamento e mudanças de atualização, veja Problemas conhecidos e Diferenças principais de versão.

Identifique o sintoma

Capture a descrição completa do erro e todos os registros de erro disponíveis antes de alterar as configurações. Um nível HRESULTsuperior , como DB_E_ERRORSOCCURRED, não identifica a causa sozinha. Registre se a falha ocorre ao carregar o provedor, abrir uma conexão, executar um comando, buscar dados ou comprometer uma transação.

Sintoma Comece por aqui
O provedor não pode ser encontrado, ou a classe não está registrada. Registro de provedores e arquitetura
O login falha, o acesso é negado ou a autenticação integrada falha. Falhas de login e autenticação
A cadeia de certificados não é confiável ou o nome do certificado não corresponde. Falhas no certificado TLS
Servidor ou instância não podem ser encontrados, ou a conexão é recusada. Falhas de descoberta de rede e instâncias
Parâmetros falham, valores são truncados ou dados não podem ser convertidos. Erros de parâmetros e conversão de dados
A conexão cai, a recuperação falha ou ocorre um timeout. Perda de conexão e tempos de espera
Os detalhes do erro não estão disponíveis, ou você precisa de um rastreamento para o suporte. Diagnóstico e rastreamento

Para falhas de conexão, compare a aplicação com um teste de conexão Universal Data Link (UDL). Use o mesmo computador, provedor, arquitetura de processo, identidade de autenticação, servidor, banco de dados e configurações de criptografia. Um teste bem-sucedido com outro provedor ou identidade não comprova que a configuração da aplicação funciona.

Registro de provedores e arquitetura

Erros como Provider não pode ser encontrado ou REGDB_E_CLASSNOTREG (0x80040154, Classe não registrada) indicam o carregamento do provedor antes da autenticação do SQL Server.

  1. Verifique o provedor que a solicitação solicita. MSOLEDBSQL19 e MSOLEDBSQL identificam diferentes versões principais. Instalar o driver atual não altera a escolha do provedor do aplicativo. Siga as etapas de migração caso a aplicação ainda solicite outro provedor.
  2. Verifique a arquitetura do processo que hospeda a aplicação. Um aplicativo de 32 bits precisa do provedor de 32 bits, mesmo no Windows de 64 bits. Para um serviço ou tarefa agendada, verifique o executável e a conta que esse host usa, não apenas o seu ambiente de desenvolvimento.
  3. Instale ou repare o driver com o instalador suportado no computador que roda o aplicativo. O instalador x64 inclui binários de driver de 64 e 32 bits. Verifique as dependências necessárias em Instalar o Driver OLE DB e Requisitos do sistema. Não copie bibliotecas de drivers de outro computador como substituto da instalação.
  4. Repita o teste UDL com a arquitetura e o provedor correspondentes. Se funcionar, mas o aplicativo ainda não conseguir carregar o provedor, compare a seleção efetiva do provedor e a arquitetura do host do aplicativo com as do teste.

Se o erro mencionar especificamente adal.dll, verifique o problema conhecido da biblioteca de autenticação em vez de tratá-lo como um provedor do SQL Server ausente.

Falhas de login e autenticação

Distinga-se uma rejeição de login de servidor de uma falha em obter credenciais ou estabelecer uma conexão criptografada. Leia o texto completo do erro, incluindo qualquer erro do provedor aninhado.

  1. Para o erro 18456 do SQL Server, peça ao administrador do banco de dados que inspecione a entrada e o estado correspondentes do registro de erro do servidor. Verifique o modo de autenticação, status de login, banco de dados solicitado e acesso ao banco de dados usando MSSQLSERVER_18456. Não presuma que toda rejeição de login significa uma senha incorreta.
  2. Para autenticação integrada, confirme a identidade sob a qual a aplicação é executada. Uma conta de serviço ou conta de tarefas agendadas pode diferir do usuário que testou a conexão com sucesso. Se a mensagem incluir Não é possível gerar o contexto SSPI, siga a solução de problemas da Interface de Provedor de Suporte de Segurança (SSPI) e o suporte ao Nome da Entidade de Serviço (SPN).
  3. Para o Microsoft Entra ID, verifique se o método de autenticação selecionado se encaixa no ambiente de execução da aplicação e se sua identidade tem acesso ao banco de dados alvo. Revise as configurações específicas de cada método e as restrições de tokens de acesso no Use Microsoft Entra ID. Não combine um token de acesso com autenticação ou credenciais conflitantes.
  4. Compare as configurações efetivas com a tabela de palavras-chave correta da cadeia de conexão. IDBInitialize::Initialize, IDataInitialize::GetDataSource, e ActiveX Data Objects (ADO) usam tabelas de palavras-chave diferentes. Verifique a tabela da interface que sua aplicação usa.

O texto O nome principal alvo está incorreto pode aparecer em diferentes contextos. Se isso acompanhar Não é possível gerar contexto SSPI, investigue a autenticação do Windows e os SPNs. Se o erro identificar o aperto de mão do certificado ou da criptografia, use a próxima seção.

Falhas no certificado TLS

Erros de Segurança da Camada de Transporte (TLS) podem ocorrer antes que um login chegue ao SQL Server. O driver atual permite a criptografia obrigatória por padrão, então uma atualização pode expor um problema de confiança de certificado ou nome que uma configuração de conexão mais antiga não detectou.

  1. Se a cadeia de certificados foi emitida por uma autoridade não confiável, verifique o certificado apresentado pelo SQL Server e a cadeia de certificação emissora na qual o computador cliente confia. Configure um certificado válido de servidor e instale os certificados root e intermediários confiáveis necessários através do processo de gerenciamento de certificados da sua organização.
  2. Em caso de incompatibilidade no nome do certificado, compare o nome do servidor ou listener que o aplicativo utiliza com os nomes presentes no certificado. Use um certificado que cubra o nome da conexão pretendido. Se a aplicação usar intencionalmente um nome de conexão diferente, revise a propriedade documentada HostNameInCertificate antes de configurar o nome esperado do certificado.
  3. Verifique as configurações de criptografia e validação efetivas, incluindo as configurações do registro. Revise as tabelas de criptografia e validação de certificados para verificar precedência e Strict comportamento. No modo Strict, o driver valida o certificado independentemente da configuração de confiar no certificado do servidor.
  4. Se a falha começou durante a migração, verifique a solução de problemas de versão principal, incluindo o tipo de valor da propriedade de criptografia e a restrição ao uso de ServerCertificate fora do modo Strict.

Use requisitos de certificado para o SQL Server e solução de problemas de cadeia de certificados não confiável para verificações detalhadas. Mantenha a criptografia e validação de certificados ativadas na produção. Desativar qualquer um dos dois não resolve um problema de implantação de certificados.

Falhas de descoberta de rede e instâncias

Para servidor não encontrado, erro ao localizar o servidor/a instância especificado(a) ou erros de conexão recusada, identifique o endpoint que a aplicação está tentando acessar.

  1. Verifique o nome do servidor, nome da instância e a porta de escuta configurada com o administrador do banco de dados. Confirme que o serviço de banco de dados está em execução e que o protocolo e o ouvinte pretendidos estão ativados. Não presuma que toda instância está escutando na porta 1433.
  2. Para uma conexão TCP remota, teste o endpoint conhecido usando o formato de nome de servidor do driver tcp:<server>,<port>. Mantenha as mesmas configurações de autenticação, banco de dados e criptografia. Consulte Palavras-chave da cadeia de conexão para a palavra-chave de servidor aplicável à sua interface.
  3. Se o host explícito e a porta funcionarem, mas a instância nomeada não, investigue o SQL Server Browser e a descoberta de instâncias. Verifique o serviço do navegador e o caminho da porta 1434 do Protocolo de Datagramas do Usuário (UDP) onde a descoberta do navegador é usada.
  4. Se o endpoint explícito também falhar, verifique a resolução do Sistema de Nomes de Domínio (DNS), o roteamento e o acesso ao firewall à porta real de escuta a partir do host da aplicação. Trate erros de conexão relacionados à rede ou específicos da instância, em vez de alterar várias configurações de conexão ao mesmo tempo.

Para um ouvinte de grupo de disponibilidade, também revise o suporte de alta disponibilidade e recuperação de desastres. Para o LocalDB, use o suporte ao LocalDB para verificar a instância local e o contexto do usuário, em vez de seguir etapas de descoberta remota via TCP.

Erros de parâmetros e conversão de dados

Se a conexão abrir, mas a execução de comandos ou a recuperação de dados falharem, reduza a reprodução para o comando e valor que falham. Preserve o tipo de dado original, comprimento, status nulo e codificação de caracteres ao substituir dados sensíveis.

  1. Compare cada ? marcador de parâmetro com seu ordinal de ligação, direção e metadados. Quando você usar ICommandWithParameters::SetParameterInfo, faça corresponder o tipo de origem SQL ao comando ou ao procedimento armazenado. Não presuma que os metadados dos parâmetros são sempre derivados automaticamente. Revise os parâmetros do comando para restrições de derivação e comportamento dos parâmetros de saída.
  2. Inspecione os status de vinculação do acessório e o status e comprimento de cada valor retornado, não apenas o valor geral HRESULT. Em caso de falhas ao definir propriedades, inspecione o dwStatus de cada propriedade. Um retorno com sucesso parcial, como DB_S_ERRORSOCCURRED pode exigir inspeção de array de status mesmo quando nenhum objeto de erro está disponível. Consulte os códigos de retorno.
  3. Em caso de conversão ou truncamento, compare o tipo e o tamanho do buffer do consumidor com os metadados reais da coluna ou do parâmetro. Verifique a precisão e a escala para valores numéricos, intervalos válidos e frações de segundo para valores de data/hora, e comprimentos de bytes para buffers de caracteres. Investigue DBSTATUS_E_CANTCONVERTVALUEe não trate DBSTATUS_S_TRUNCATED como um valor completo. Use mapeamento de tipos de dados, busca de linhas e conversões de data e hora para as regras aplicáveis.
  4. Se parâmetros de saída limitados aparecerem faltando, esgote os conjuntos de linhas retornados antes de lê-los. Consulte Use IMultipleResults para processar múltiplos conjuntos de resultados. Para parâmetros de saída transmitidos, consuma ou libere fluxos pendentes antes de solicitar o próximo resultado, conforme descrito no suporte de streaming para parâmetros de saída.

Para mapeamentos específicos do ADO, consulte Usar o ADO com o Driver OLE DB e as restrições de autenticação em DataTypeCompatibility, em Usar o Microsoft Entra ID. Não adicione uma configuração de compatibilidade sem verificar os dois.

Para strings estreitas corrompidas em uma coluna sql_variant após uma atualização do driver, revise o problema conhecido e o procedimento de recuperação existente do SSVARIANT antes de modificar os dados armazenados.

Perda de conexão e tempos de espera

Registre quando a conexão funcionou pela última vez, qual operação falhou e quanto tempo essa operação durou. Distinga esses casos antes de mudar as configurações de tentativa ou tempo de expiração.

Estágio de falha Verificações e orientações detalhadas
Abrindo uma conexão. Inspecione primeiro os erros do provedor, rede, autenticação e TLS. Verifique a DBPROP_INIT_TIMEOUT em vigor ou a palavra-chave de conexão correspondente. Veja Solução de problemas de tempo limite de conexão.
Executando um comando. Verifique DBPROP_COMMANDTIMEOUT ou a configuração de tempo limite de comando do aplicativo. Investigue bloqueios e o desempenho das consultas com a solução de problemas de tempo limite de consulta. Aumentar o tempo de espera da conexão não altera o tempo de espera do comando.
Reutilizando uma conexão ociosa. Verifique as condições de recuperação, as configurações de retentativa e os erros esperados em Resiliência de conexão ociosa. A recuperação pode falhar quando o tempo limite do comando expira antes da conclusão da reconexão.
Perda de conexão durante a execução ou o commit. Correlacione eventos de cliente e servidor para verificar interrupção de rede, reinício do servidor ou failover. Estabeleça o resultado da operação antes de decidir se é seguro tentar novamente.

A resiliência de conexão ociosa não oferece tentativas iniciais de conexão nem reprodução automática de comandos e transações arbitrárias. Para uma falha transitória confirmada, use retentativas limitadas da aplicação com um intervalo entre elas e registre cada tentativa. Não tente repetidamente erros de carregamento do provedor, credenciais rejeitadas ou falhas na validação de certificados sem corrigir a causa.

Caution

Se uma conexão cair durante uma gravação ou confirmação, o cliente pode não saber se o SQL Server confirmou a transação. Não reproduza a operação às cegas. Verifique seu resultado ou use um design de aplicação que previna efeitos duplicados antes de tentar novamente.

Diagnóstico e rastreamento

Colete diagnósticos no ponto da falha, antes que chamadas de provedores não relacionadas substituam as informações de erro.

  1. Capture a operação que falhou, a data e hora, o fuso horário, o tempo decorrido e HRESULT. Para consumidores nativos de OLE DB, recupere todos os registros disponíveis por meio de IErrorInfo e IErrorRecords, não apenas a primeira descrição. Inclua SQLSTATE e o número de erro nativo do SQL Server, quando disponível por meio de ISQLErrorInfo. Veja Recuperar informações de erro e detalhes de erro do SQL Server. Para ADO, capture a coleção da conexão Errors.
  2. Colete status por propriedade, por vinculação e por valor para métodos que reportam erros dessa forma. Um objeto de erro ausente não torna seguro ignorar um resultado de sucesso parcial.
  3. Correlacione a falha do cliente com o log de erros do servidor ou Eventos Estendidos. Quando disponível, registre ClientConnectionID e ActivityID. Uma falha antes do pré-login pode ocorrer sem um identificador de conexão do cliente.
  4. Se os registros de erro não forem suficientes, use as informações de diagnóstico de acesso no registro de Eventos Estendidos para rastreamento de drivers e configuração de correlação. Colete uma trilha limitada ao redor da reprodução e pare de traçar depois.

Quando você escalar, inclua a versão do driver, o provedor solicitado, a arquitetura da aplicação e do processo, a versão do servidor, o método de autenticação, as configurações de conexão eficaz, o estágio de falha, os registros de erro e uma reprodução mínima. Indique se o teste UDL correspondente foi bem-sucedido e se o problema afeta um host ou múltiplos hosts.

Remova senhas, tokens de acesso e outros segredos das configurações de conexão e logs. Revise os rastros para texto de consulta e dados sensíveis, armazene-os com acesso restrito e compartilhe-os apenas por meio de um canal de suporte aprovado.

Conteúdo relacionado

  • Last updated on