Troubleshooting connections

When Test connection fails, the cause is almost always one of four things, in this order: network reachability, TLS mismatch, credentials, or permissions. Work down the list.

1. Network reachability (timeouts)

A test that hangs and then fails with a timeout means the DataSquares server can’t reach your database at all.

Firewall / security group: allow inbound connections from your DataSquares server’s IP on the database port. Cloud databases (RDS, Azure SQL, Cloud SQL) deny everything by default.
Host, not localhost: localhost refers to the DataSquares server itself. Use the database server’s real hostname or IP.
Port: the wizard prefills the engine default — check yours if the server runs on a non-standard port.
Private networks: a database on a private VPC needs a route from the DataSquares host (peering, tunnel, or an allowlisted public endpoint).

2. TLS mismatches

Server requires TLS (common on managed cloud databases): enable the TLS toggle in the connection form.
TLS handshake errors with self-signed certificates: your server presents a certificate the client can’t verify — use a certificate from a real CA, or consult your database’s documentation for its TLS modes.

3. Credentials

Authentication errors (password authentication failed, Login failed for user, …) mean the server was reached — recheck username and password.
Some engines scope users per database or per host — make sure the user is allowed to connect to this database from this client address (e.g. MySQL’s user@host grants, PostgreSQL’s pg_hba.conf).
If a previously working source starts failing after a password rotation, edit the source in Data Sources and update the stored credentials.

4. Permissions

A connection that succeeds but shows no tables (or fails when previewing data) usually lacks read grants:

Grant SELECT (and schema USAGE where the engine has it) on the tables you want to analyze.
Warehouses add their own layer: a Snowflake user also needs usage on the warehouse and role; BigQuery service accounts need Data Viewer plus Job User; Athena needs S3 read on the data and write on the staging location.

Upload & API sources

File uploads: if an upload fails, check the file parses outside DataSquares (encoding for CSV, valid workbook for Excel, valid JSON/NDJSON).
Google Sheets: the #1 miss is not sharing the sheet with the service account’s email address.
REST API: test the endpoint with curl first; if it needs auth, put the header (e.g. Authorization: Bearer …) in the connection’s headers field, and set the records path if the array is nested in the response.

Still stuck?

Re-run Test connection after each change — it re-validates everything. If the error text isn’t listed here, it comes verbatim from the database driver, so searching it together with your engine’s name usually finds the server-side cause.