Skip to main content
A maioria das falhas de conexão com banco de dados na Square Cloud se resume a uma de três coisas: um certificado SSL ausente, uma whitelist de IP que não considera um IP dinâmico, ou credenciais erradas. Encontre o erro exato abaixo.

​
”Host ‘X’ is not allowed to connect to this MySQL server”

O que significa: o cliente MySQL rejeita a conexão com esta mensagem exata. Por que acontece: os bancos de dados hospedados da Square Cloud exigem SSL em toda conexão. Este erro aparece quando a conexão é tentada sem o certificado carregado, não por causa de um firewall/whitelist de host como a mensagem sugere. Como corrigir:
  1. Abra o banco de dados no dashboard da Square Cloud e baixe os arquivos de certificado (CA, cert, key, geralmente 2-3 campos).
  2. Carregue-os na configuração SSL/TLS do seu cliente:
    • Clientes GUI (MySQL Workbench, DBeaver, HeidiSQL): configure os arquivos de certificado baixados na aba SSL do cliente, depois conecte com o host/porta/usuário/senha exibidos no dashboard.
    • Código (Prisma ORM): converta o cert+key do cliente em um .p12:
      Depois defina:
      Envie o client.p12 dentro do zip da aplicação, defina DATABASE_URL nas variáveis de ambiente da aplicação e reinicie a aplicação.
  3. Verifique se o usuário e a senha correspondem ao que é exibido no dashboard, e reinicie o banco de dados se o certificado acabou de ser gerado.
Nunca faça commit do certificate.pem ou client.p12 em um repositório público, mantenha-o fora do controle de versão, mas inclua-o no .zip de deploy quando sua aplicação o lê do disco.

​
MongoNetworkError e falhas de whitelist de IP do MongoDB Atlas

O que significa: um cluster MongoDB Atlas hospedado externamente (não um banco de dados gerenciado da Square Cloud) recusa a conexão com MongoNetworkError: connection ... closed, mesmo com as credenciais corretas. Por que acontece: os containers de aplicação da Square Cloud usam um endereço IPv4 dinâmico que muda a cada reinício. Uma whitelist de IP do MongoDB Atlas configurada para um único IP estático vai funcionar até o próximo reinício, e então quebrar silenciosamente. Como corrigir, escolha uma opção:
  1. Recomendado se você precisa do Atlas externo: no Atlas → Network Access, adicione 0.0.0.0/0 para permitir conexões de qualquer IP, e compense a whitelist mais ampla com credenciais fortes (senha longa e aleatória, usuário de banco de dados dedicado, connection string mantida apenas em variáveis de ambiente). Veja também whitelist do MongoDB Atlas com IP dinâmico.
  2. Recomendado no geral: mova o banco de dados para um banco de dados gerenciado da Square Cloud em vez de um cluster Atlas externo. Hospedar o banco de dados ao lado da aplicação elimina completamente o problema de whitelist de IP e oferece latência quase zero.

​
Timeout de conexão e ECONNREFUSED

O que significa: a aplicação trava até dar timeout, ou falha imediatamente com ECONNREFUSED, ao tentar acessar um banco de dados. Por que acontece, como regra geral:
  • Um timeout (a conexão trava, sem rejeição imediata) geralmente significa que um firewall ou whitelist de IP no banco de dados de destino está bloqueando a conexão. Muitos provedores externos bloqueiam IPs de datacenter/estrangeiros por padrão.
  • Um ECONNREFUSED imediato ou “authentication failed” geralmente significa que o host/porta está acessível, mas as credenciais, nome do banco, ou número da porta estão errados.
Como corrigir:
  1. Se estiver conectando a um provedor externo (não um banco de dados gerenciado da Square Cloud), permita os ASNs da Square Cloud no firewall de destino: 398395 e 26548. Onde apenas whitelist baseada em IP é suportada (como o MongoDB Atlas), use 0.0.0.0/0 com credenciais fortes em vez disso, já que o IP de origem é dinâmico.
  2. Confira host, porta, usuário e senha contra o que o provedor ou o dashboard da Square Cloud mostram.
  3. Codifique em URL quaisquer caracteres especiais na connection string (@, :, /, etc. dentro de uma senha vão quebrar o parsing se deixados sem codificação).
  4. Verifique se o driver do provedor exige um parâmetro explícito ssl=true (ou similar) na connection string.

​
Erros de conexão SSL/TLS

O que significa: o cliente falha ao estabelecer um handshake TLS com o banco de dados, ou falha logo depois com um erro que parece de autenticação mas na verdade é um problema de certificado. Por que acontece: os bancos de dados gerenciados da Square Cloud exigem SSL em toda conexão. Cada engine de banco de dados espera o certificado em um formato ligeiramente diferente:
  • Redis: o protocolo deve ser rediss:// (dois s), nunca redis://. Formato: rediss://default:PASSWORD@HOST:PORT. O node-redis também aceita socket: { tls: true, ca: fs.readFileSync("certificate.pem") }; a biblioteca redis do Python usa ssl_ca_certs/ssl_certfile/ssl_keyfile (o certificate.pem combinado baixado do dashboard funciona para todos eles).
  • Drizzle ORM (Postgres): um Pool padrão do pg com ssl: { ca, cert, key }, todos carregados via fs.readFileSync a partir do certificate.pem combinado, e o mesmo objeto ssl no drizzle.config.ts.
  • JDBC (Java): a chave do cliente deve ser convertida para o formato PK8/DER e referenciada nas propriedades SSL da URL JDBC.
Como corrigir: baixe novamente o certificado da página do banco de dados no dashboard (um arquivo de certificado antigo ou parcial é uma causa comum), confirme que a connection string usa o protocolo/esquema com TLS habilitado para o seu engine, e reinicie o banco de dados se você acabou de criá-lo.

​
Guias relacionados

Se a mensagem de erro não corresponder a nada acima, nossa equipe de suporte pode ajudar a diagnosticar a falha de conexão exata.

​
Contate-nos

Se você continuar enfrentando dificuldades técnicas, nossa equipe de suporte especializada está disponível para auxiliá-lo. Entre em contato conosco e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com 4,9/5 em 402 avaliações no Google e Trustpilot.