La maggior parte dei fallimenti di connessione al database su Square Cloud si riconducono a una di queste tre cause: un certificato SSL mancante, una allowlist IP che non tiene conto di un IP dinamico, oppure credenziali errate. Trova la corrispondenza con l’errore esatto qui sotto.
”Host ‘X’ is not allowed to connect to this MySQL server”
Cosa significa: il client MySQL rifiuta la connessione con questo identico messaggio.
Perché accade: i database gestiti di Square Cloud richiedono SSL per ogni connessione. Questo errore appare quando la connessione viene tentata senza il certificato caricato, non a causa di un firewall/allowlist host come suggerisce il messaggio.
Come risolvere:
- Apri il database nella dashboard di Square Cloud e scarica i file del certificato (CA, cert, key, di solito 2-3 campi).
- Caricali nella configurazione SSL/TLS del tuo client:
- Client GUI (MySQL Workbench, DBeaver, HeidiSQL): configura i file del certificato scaricati nella scheda SSL del client, poi connettiti con host/porta/utente/password mostrati nella dashboard.
- Codice (Prisma ORM): converti il cert+key del client in un
.p12:
Poi imposta:
Includi client.p12 all’interno dello .zip dell’app e imposta DATABASE_URL nelle Variabili d’ambiente della dashboard.
- Verifica che username e password corrispondano a quanto mostrato nella dashboard, e riavvia il database se il certificato è stato appena generato.
Non fare mai commit di certificate.pem o client.p12 in un repository pubblico, tienilo fuori dal controllo di versione, ma includilo nello .zip di deploy quando la tua app lo legge dal disco.
MongoNetworkError e fallimenti della whitelist IP di MongoDB Atlas
Cosa significa: un cluster MongoDB Atlas ospitato esternamente (non un database gestito da Square Cloud) rifiuta la connessione con MongoNetworkError: connection ... closed, anche se le credenziali sono corrette.
Perché accade: i container delle applicazioni di Square Cloud usano un indirizzo IPv4 dinamico che cambia a ogni riavvio. Una whitelist IP di MongoDB Atlas configurata per un singolo IP statico funzionerà fino al riavvio successivo, poi si interromperà silenziosamente.
Come risolvere, scegline uno:
- Consigliato se ti serve Atlas esterno: in Atlas → Network Access, aggiungi
0.0.0.0/0 per consentire connessioni da qualsiasi IP, e compensa la allowlist più ampia con credenziali forti (password lunga e casuale, utente database dedicato, connection string mantenuta solo nelle variabili d’ambiente).
- Consigliato in generale: sposta il database su un database gestito da Square Cloud invece di un cluster Atlas esterno. Ospitare il database accanto all’app elimina completamente il problema della allowlist IP e offre una latenza vicina allo zero.
Timeout di connessione ed ECONNREFUSED
Cosa significa: l’app resta in attesa fino al timeout, oppure fallisce immediatamente con ECONNREFUSED, quando cerca di raggiungere un database.
Perché accade, come regola generale:
- Un timeout (la connessione resta in attesa, nessun rifiuto immediato) di solito significa che un firewall o una allowlist IP sul database di destinazione sta bloccando la connessione. Molti provider esterni bloccano per impostazione predefinita gli IP di datacenter/esteri.
- Un ECONNREFUSED immediato o un “authentication failed” di solito significa che host/porta sono raggiungibili ma le credenziali, il nome del database o il numero di porta sono sbagliati.
Come risolvere:
- Se ti connetti a un provider esterno (non un database gestito da Square Cloud), consenti gli ASN di Square Cloud sul firewall di destinazione:
398395 e 26548. Dove è supportata solo la allowlist basata su IP (come MongoDB Atlas), usa invece 0.0.0.0/0 con credenziali forti, dato che l’IP di origine è dinamico.
- Ricontrolla host, porta, username e password rispetto a quanto mostrato dal provider o dalla dashboard di Square Cloud.
- Codifica con URL encoding qualsiasi carattere speciale nella connection string (
@, :, /, ecc. all’interno di una password comprometteranno il parsing se lasciati non codificati).
- Verifica se il driver del provider richiede un parametro esplicito
ssl=true (o simile) nella connection string.
Errori di connessione SSL/TLS
Cosa significa: il client non riesce a stabilire un handshake TLS con il database, oppure fallisce subito dopo con un errore che sembra di autenticazione ma è in realtà un problema di certificato.
Perché accade: i database gestiti di Square Cloud richiedono SSL per ogni connessione. Ogni motore di database si aspetta il certificato in una forma leggermente diversa:
- Redis: il protocollo deve essere
rediss:// (con due s), mai redis://. Forma: rediss://default:PASSWORD@HOST:PORT. node-redis accetta anche socket: { tls: true, ca: fs.readFileSync("certificate.pem") }; la libreria Python redis accetta ssl_ca_certs/ssl_certfile/ssl_keyfile (il certificate.pem combinato scaricato dalla dashboard funziona per tutti).
- Drizzle ORM (Postgres): un
Pool pg standard con ssl: { ca, cert, key }, tutti caricati tramite fs.readFileSync dal certificate.pem combinato, e lo stesso oggetto ssl in drizzle.config.ts.
- JDBC (Java): la chiave del client deve essere convertita nel formato PK8/DER e referenziata nelle proprietà SSL dell’URL JDBC.
Come risolvere: riscarica il certificato dalla pagina del database nella dashboard (un file certificato vecchio o parziale è una causa comune), conferma che la connection string usi il protocollo/schema abilitato a TLS per il tuo motore, e riavvia il database se lo hai appena creato.
Per creare e connetterti a un database gestito da zero, consulta Database.
Se il messaggio di errore non corrisponde a nulla di quanto sopra, il nostro team di supporto può aiutarti a diagnosticare il fallimento di connessione esatto.
Contattaci
Se continui a riscontrare difficoltà tecniche, il nostro team di supporto specializzato è disponibile ad assisterti. Contattaci e saremo felici di aiutarti a risolvere qualsiasi problema — la qualità del supporto è una parte importante del motivo per cui gli sviluppatori valutano Square Cloud 4,9/5 su 402 recensioni su Google e Trustpilot. 
