> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros de Conexão com Banco de Dados na Square Cloud: MySQL Host Not Allowed, MongoNetworkError, SSL

> Corrija Host is not allowed to connect to this MySQL server, MongoNetworkError, falhas de whitelist de IP do MongoDB Atlas, timeout de conexão, ECONNREFUSED, e erros de conexão SSL/TLS na Square Cloud.

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`:
     ```bash theme={null}
     openssl pkcs12 -export -out client.p12 -inkey client.key -in client.crt
     ```
     Depois defina:
     ```
     DATABASE_URL=mysql://USER:PASSWORD@HOST:PORT/DB?sslidentity=./client.p12&sslpassword=PASSWORD
     ```
     Envie o `client.p12` dentro do `.zip` da aplicação e defina `DATABASE_URL` nas Environment Variables do dashboard.
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.

<Warning>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.</Warning>

## 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).
2. **Recomendado no geral:** mova o banco de dados para um [banco de dados gerenciado da Square Cloud](/pt-br/services/databases) 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.

Para criar e se conectar a um banco de dados gerenciado do zero, veja [Bancos de Dados](/pt-br/services/databases).

<Tip>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.</Tip>

## Contate-nos

Se você continuar enfrentando **dificuldades técnicas**, nossa **equipe de suporte especializada** está disponível para auxiliá-lo. [**Entre em contato conosco**](https://squarecloud.app/pt-br/support) 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**](https://www.trustpilot.com/review/squarecloud.app) no Google e Trustpilot.