Troubleshooting connections

When a Test connection check fails, the root cause almost always falls into one of four categories: network reachability, TLS mismatch, credentials, or insufficient permissions.

Work through the diagnostic steps below.

1. Network reachability & timeouts

A connection test that hangs before reporting a timeout indicates that the DataSquares server cannot establish a TCP connection to the specified host and port.

Firewall & Security Groups — Ensure inbound traffic is permitted from the DataSquares server’s public or private IP on the database port. Managed cloud databases (AWS RDS, Azure Database, Google Cloud SQL) deny inbound connections by default.
Host vs. Localhost — localhost and 127.0.0.1 refer to the DataSquares host machine itself. Always specify the fully qualified domain name (FQDN) or external IP of your database server.
Non-standard ports — Verify whether your database engine uses a non-default port (e.g. AWS Aurora custom endpoints or Docker port mappings).
Private VPCs & tunnels — Databases hosted inside isolated private VPCs require VPC peering, an SSH tunnel, or an allowlisted reverse proxy to be accessible.

2. TLS & SSL configuration

Mandatory TLS — Cloud database providers (Supabase, Neon, Azure SQL, PlanetScale) mandate encrypted connections. Verify that the TLS toggle is enabled.
Self-signed certificates — If your internal database uses a private or self-signed SSL certificate, enable the Trust self-signed certificate checkbox in the connection modal to allow the connection while maintaining wire encryption.
Certificate revocation & CN mismatches — Ensure the database hostname in the form matches the Common Name (CN) or Subject Alternative Name (SAN) on the server’s TLS certificate.

3. Authentication & credentials

Host-scoped user grants — Many SQL engines (such as MySQL and PostgreSQL) restrict user logins based on client origin IP (e.g. 'user'@'10.0.%' or pg_hba.conf client CIDR rules). Verify that the database user is permitted to log in from the DataSquares host IP.
Password rotations — If a previously working connection fails with authentication errors, click Edit on the source card in Data Sources to update the saved password or token.
Special characters in passwords — Characters like @, :, /, or % are handled automatically by the wizard’s driver layer, but verify credentials by testing with standard CLI tools if issues persist.

4. Permissions & access roles

A connection that passes the test but displays no tables, or errors out during queries, is missing read grants:

Relational databases — Grant SELECT on target tables, and schema USAGE (for PostgreSQL, SQL Server, and Oracle) to the connection user.
Snowflake — User requires USAGE on the virtual warehouse, USAGE on the database and schema, and SELECT on tables, plus an assigned default role.
Google BigQuery — The Service Account must have the BigQuery Data Viewer and BigQuery Job User IAM roles.
Amazon Athena — IAM credentials must grant athena:StartQueryExecution, athena:GetQueryResults, AWS Glue catalog read permissions, S3 read permissions on source data, and S3 read/write permissions on the staging output bucket.
Databricks — The Personal Access Token (PAT) user requires CAN USE on the SQL Warehouse and SELECT on catalog schemas.

File upload, object store & API troubleshooting

File uploads:
- Ensure CSV files use valid UTF-8 encoding and standard delimiters (comma, tab, semicolon).
- Verify Excel workbooks are .xlsx format (legacy .xls is not supported).
- For JSON files, verify the array structure or specify the correct Records path (e.g. items or results.data).
Object stores (S3 / Azure / GCS):
- Ensure the bucket/container exists in the specified region.
- S3 IAM keys require s3:ListBucket and s3:GetObject.
- For multi-part partition folders, use the Import Prefix mode in the Object Browser.
Google Sheets:
- The spreadsheet must be explicitly shared with the service account email address with Viewer access.
REST APIs:
- Test the endpoint via curl to confirm JSON output.
- Verify headers (e.g. Authorization: Bearer <token>) and specify the recordsPath if the target records array is nested inside a root object.