Most database connection failures on Square Cloud come down to one of three things: a missing SSL certificate, an IP allowlist that doesn’t account for a dynamic IP, or wrong credentials. Match the exact error below.
”Host ‘X’ is not allowed to connect to this MySQL server”
What it means: the MySQL client rejects the connection with this exact message.
Why it happens: Square Cloud’s hosted databases require SSL for every connection. This error appears when the connection is attempted without the certificate loaded, not because of a firewall/host allowlist as the message implies.
How to fix:
- Open the database in the Square Cloud dashboard and download the certificate files (CA, cert, key, usually 2-3 fields).
- Load them in your client’s SSL/TLS configuration:
- GUI clients (MySQL Workbench, DBeaver, HeidiSQL): configure the downloaded certificate files in the client’s SSL tab, then connect with the host/port/user/password shown in the dashboard.
- Code (Prisma ORM): convert the client cert+key into a
.p12:
Then set:
Ship client.p12 inside the app’s .zip and set DATABASE_URL in the dashboard’s Environment Variables.
- Verify the username and password match what’s shown in the dashboard, and restart the database if the certificate was only just generated.
Never commit certificate.pem or client.p12 to a public repository, keep it out of version control, but do include it in the deploy .zip when your app reads it from disk.
MongoNetworkError and MongoDB Atlas IP whitelist failures
What it means: an externally-hosted MongoDB Atlas cluster (not a Square Cloud managed database) refuses the connection with MongoNetworkError: connection ... closed, even though the credentials are correct.
Why it happens: Square Cloud application containers use a dynamic IPv4 address that changes on every restart. A MongoDB Atlas IP allowlist configured for a single static IP will work until the next restart, then silently break.
How to fix, choose one:
- Recommended if you need external Atlas: in Atlas → Network Access, add
0.0.0.0/0 to allow connections from any IP, and compensate for the wider allowlist with strong credentials (long random password, dedicated database user, connection string kept only in environment variables).
- Recommended overall: move the database to a Square Cloud managed database instead of an external Atlas cluster. Hosting the database next to the app removes the IP-allowlist problem entirely and gives near-zero latency.
Connection timeout and ECONNREFUSED
What it means: the app hangs until it times out, or fails immediately with ECONNREFUSED, when trying to reach a database.
Why it happens, as a rule of thumb:
- A timeout (the connection hangs, no immediate rejection) usually means a firewall or IP allowlist on the destination database is blocking the connection. Many external providers block datacenter/foreign IPs by default.
- An immediate ECONNREFUSED or “authentication failed” usually means the host/port is reachable but the credentials, database name, or port number are wrong.
How to fix:
- If connecting to an external provider (not a Square Cloud managed database), allow Square Cloud’s ASNs on the destination firewall:
398395 and 26548. Where only IP-based allowlisting is supported (like MongoDB Atlas), use 0.0.0.0/0 with strong credentials instead, since the source IP is dynamic.
- Double-check host, port, username, and password against what the provider or the Square Cloud dashboard shows.
- URL-encode any special characters in the connection string (
@, :, /, etc. inside a password will break parsing if left raw).
- Check whether the provider’s driver requires an explicit
ssl=true (or similar) parameter in the connection string.
SSL/TLS connection errors
What it means: the client fails to establish a TLS handshake with the database, or fails right after with an authentication-looking error that’s actually a certificate problem.
Why it happens: Square Cloud managed databases require SSL on every connection. Each database engine expects the certificate in a slightly different shape:
- Redis: the protocol must be
rediss:// (two s’s), never redis://. Shape: rediss://default:PASSWORD@HOST:PORT. node-redis also accepts socket: { tls: true, ca: fs.readFileSync("certificate.pem") }; Python’s redis library takes ssl_ca_certs/ssl_certfile/ssl_keyfile (the combined certificate.pem downloaded from the dashboard works for all of them).
- Drizzle ORM (Postgres): a standard
pg Pool with ssl: { ca, cert, key }, all loaded via fs.readFileSync from the combined certificate.pem, and the same ssl object in drizzle.config.ts.
- JDBC (Java): the client key must be converted to PK8/DER format and referenced in the JDBC URL’s SSL properties.
How to fix: re-download the certificate from the database’s page in the dashboard (an old or partial certificate file is a common cause), confirm the connection string uses the TLS-enabled protocol/scheme for your engine, and restart the database if you just created it.
For creating and connecting to a managed database from scratch, see Databases.
If the error message doesn’t match anything above, our support team can help diagnose the exact connection failure.
