Resumo
🧩 Este artigo ensina, de forma objetiva, como atualizar a biblioteca dbapi.dll (DBAPI) usada pelo TOTVS | Application Server (AppServer) para se conectar ao TOTVS | DBAccess. Inclui checklist, passo a passo, validações pós-atualização, rollback e erros comuns.

Aplicabilidade

• Produto: Microsiga Protheus — Framework / AppServer

• Versões: 12.x ou superior (Windows)

• Cenário típico: Atualização do DBAccess e necessidade de alinhar a DBAPI dentro da pasta do AppServer para manter compatibilidade.

Pré-requisitos

• 🛑 Parar os serviços do Protheus/AppServer antes de substituir arquivos.

• 🔐 Permissões de administrador no servidor.

• 💾 Pacote DBAccess correspondente à arquitetura do ambiente (32 ou 64 bits).

• 📦 Espaço para backup do arquivo atual.

Passo a passo (Windows)

1. Parar serviços do Protheus

   • Pare o(s) serviço(s) do AppServer (HOMOLOGAÇÃO/PRODUÇÃO, agendadores, etc.).

2. Backup do arquivo atual

   • No diretório do executável do AppServer (ex.: C:\totvs\protheus\bin\appserver\), copie o arquivo dbapi.dll existente para uma pasta de backup e remova-o da pasta do AppServer.

3. Baixar o DBAccess mais recente

   • Obtenha o instalador/zip do DBAccess no Portal do Cliente TOTVS, respeitando a arquitetura (x86/x64). TDN

4. Extrair e localizar a DBAPI correta

   • Descompacte/instale o DBAccess e localize a DBAPI:

     • DBAccess ≤ 19.2.0.x (histórico 64 bits): nome de arquivo podia ser dbapi64.dll.

     • A partir de 19.2.1.0: a DBAPI 64 bits é disponibilizada na pasta client e padronizada como dbapi.dll.

   • Copie a dbapi.dll para a pasta do AppServer (onde fica o appserver.exe).

   • Ambientes com múltiplos AppServers: repita a cópia em cada servidor/instância que utiliza o mesmo DBAccess.

   • Observação de boas práticas TOTVS: sempre que atualizar o DBAccess, alinhe a DBAPI do AppServer; a versão/data da DBAPI no AppServer deve ser igual ou superior à do DBAccess. TDN

5. Reiniciar serviços

   • Inicie novamente o(s) serviço(s) do AppServer/Protheus.

Validações pós-atualização

• 🔎 Log do AppServer: verifique o appserver.log logo após a inicialização. Procure linhas que indiquem o carregamento da DBAPI (versão/data).

• ⚙️ Conexão com BD: abra uma rotina simples para garantir que a conexão via TopConnect/DBAccess está operando.

• 🧭 Padronização em cluster/fazenda: confirme que todas as instâncias utilizam a mesma dbapi.dll.

Checklist rápido (antes de liberar o ambiente)

• Serviços parados e backup do dbapi.dll realizado

• DBAccess mais recente obtido (x86/x64 corretos) TDN

• dbapi.dll copiada para cada pasta do AppServer aplicável

•  Serviços reiniciados sem erros no log

•  Teste funcional executado (login, consulta simples)

Rollback (se necessário)

1. Pare os serviços do AppServer.

2. Restaure a dbapi.dll anterior do backup para a pasta do AppServer.

3. Inicie os serviços e valide pelo log.

Erros comuns e como resolver

• Arquitetura incorreta (x86 vs x64):
  Sintoma: erro ao carregar biblioteca / serviço não inicia.
  👉 Baixe e utilize a DBAPI com a mesma arquitetura do AppServer/DBAccess. TDN

• Versão desalinada (DBAccess atualizado, DBAPI antiga):
  Sintoma: falhas de conexão ou mensagens de incompatibilidade.
  👉 Atualize a dbapi.dll no AppServer sempre que atualizar o DBAccess. TDN

• Arquivo não encontrado / caminho incorreto:
  Sintoma: “module not found” ou erro de inicialização.
  👉 Garanta que a dbapi.dll esteja na mesma pasta do appserver.exe (não use System32).
  👉 Repita a cópia em todas as instâncias do AppServer envolvidas.

FAQ

1) Preciso atualizar a dbapi.dll toda vez que atualizar o DBAccess?
Sim. A DBAPI do AppServer deve estar alinhada à versão do DBAccess em uso. TDN

2) Onde encontro a dbapi.dll nas versões recentes do DBAccess?
A partir das versões novas, a DBAPI 64 bits fica na pasta client do pacote do DBAccess; o nome do arquivo é dbapi.dll (padronizado). Consulte o material oficial do DBAccess. TDN

3) Preciso fazer algo no appserver.ini?
Normalmente não para a simples troca da dbapi.dll. Para facilitar diagnósticos de log, considere habilitar parâmetros de log via appserver.ini (por exemplo, ConsoleLog=1) conforme documentação do AppServer. TDN

Referências (links oficiais TOTVS)

• DBAccess — Como atualizar a biblioteca DBAPI / Boas práticas de alinhamento DBAPI x DBAccess. TDN

• DBAccess — Guia “Como fazer” (índice de artigos relacionados). TDN

• AppServer — Instalação / Manual (Windows/Linux) e requisitos. TDN+1

• Portal do Cliente TOTVS — área de downloads (para obter o instalador/zip do DBAccess). TDN

Observações finais

• Em ambientes multisservidor/cluster, padronize a biblioteca em todas as instâncias para evitar comportamentos diferentes entre nodes.

• Após a atualização, monitore os logs nas primeiras horas de operação para garantir estabilidade.