Testing Connections

Before a warehouse is saved or when troubleshooting an existing warehouse, SignalSmith performs a connection test to verify that the warehouse is reachable, credentials are valid, and the required permissions are in place. This page explains how connection testing works, what is validated, and how to diagnose failures.

How Connection Testing Works

When you click Test Connection in the warehouse configuration form (or call the test API endpoint), SignalSmith performs a series of validation steps:

Step 1: Network Connectivity

SignalSmith attempts to establish a TCP connection to the warehouse host on the configured port. This step verifies:

• The hostname or IP address resolves correctly via DNS
• The port is open and accepting connections
• No firewall, VPN, or security group rules are blocking the connection
• SSL/TLS handshake succeeds (if required)

Step 2: Authentication

Using the provided credentials, SignalSmith authenticates with the warehouse. Depending on the warehouse type, this may involve:

• Username/Password — Standard credential validation (Snowflake)
• Key Pair — RSA private key authentication (Snowflake)
• Service Account JSON — Google Cloud IAM authentication (BigQuery)
• Personal Access Token — Token-based authentication (Databricks)

Step 3: Authorization

After authentication, SignalSmith verifies that the authenticated user has access to the specified database, schema, or dataset:

• Checks that the database/project exists
• Confirms the user has USAGE or equivalent permissions on the target schema
• For Snowflake, verifies the user can use the specified warehouse

Step 4: Query Execution

SignalSmith executes a lightweight validation query to confirm the connection is fully functional:

-- Snowflake
SELECT 1
 
-- BigQuery
SELECT 1
 
-- Databricks
SELECT 1

This query exercises the full connection path: network, authentication, authorization, and query execution.

Connection Test Results

Success

A successful test returns a green checkmark with the message “Connection successful.” This confirms:

• Network connectivity is established
• Credentials are valid and accepted
• The user has access to the specified database and schema
• Queries can be executed against the warehouse

Failure

A failed test returns a red indicator with a specific error message. Common failure categories:

Testing via the API

You can test a warehouse connection programmatically:

Test Before Creating

Test credentials without saving a warehouse first:

curl -X POST https://your-workspace.signalsmith.dev/api/v1/sources/test \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "snowflake",
    "config": {
      "account": "xy12345.us-east-1",
      "warehouse": "COMPUTE_WH",
      "database": "ANALYTICS",
      "schema": "PUBLIC",
      "username": "CDP_USER",
      "password": "your-password"
    }
  }'

Test an Existing Warehouse

Re-test a saved warehouse (useful after credential rotation):

curl -X POST https://your-workspace.signalsmith.dev/api/v1/sources/{source_id}/test \
  -H "Authorization: Bearer $API_TOKEN"

Response Format

{
  "success": true,
  "message": "Connection successful",
  "latency_ms": 245
}

On failure:

{
  "success": false,
  "message": "Authentication failed: incorrect username or password",
  "error_code": "AUTH_FAILED"
}

Troubleshooting Connection Failures

Network / Timeout Issues

Symptoms: “Connection timed out” or “Could not resolve host”

Solutions:

1. Verify the hostname/account identifier is correct
2. Ensure SignalSmith’s IP addresses are allowlisted in your warehouse’s network policy
3. Check that the warehouse is running and not paused/suspended (common with Snowflake auto-suspend)
4. For Databricks, confirm the cluster or SQL warehouse is running
5. Verify DNS resolution from your network

Authentication Failures

Symptoms: “Authentication failed” or “Invalid credentials”

Solutions:

1. Double-check the username and password (no trailing whitespace)
2. For Snowflake key pair auth, ensure the private key is in PEM format and the public key is registered with the user
3. For BigQuery, verify the service account JSON is complete and valid
4. For Databricks, confirm the personal access token has not expired
5. Check if the user account is locked or disabled in the warehouse

Authorization Errors

Symptoms: “Insufficient privileges” or “Database/Schema not found”

Solutions:

1. Verify the database and schema names are spelled correctly (case-sensitive for some warehouses)
2. Confirm the user has been granted the necessary roles:
   • Snowflake: USAGE on warehouse, database, and schema; SELECT on tables
   • BigQuery: bigquery.dataViewer role on the dataset
   • Databricks: USE CATALOG, USE SCHEMA, and SELECT permissions
3. For Snowflake, ensure the user’s default role has the needed grants

SSL/TLS Issues

Symptoms: “SSL certificate verification failed” or “TLS handshake error”

Solutions:

1. Ensure your warehouse supports TLS (most cloud warehouses require it)
2. Verify the certificate has not expired
3. Check that the hostname in the certificate matches the configured host

Health Checks

After a warehouse is created, SignalSmith periodically runs automated health checks using the same connection test logic. If a health check fails:

1. The warehouse status changes to Unhealthy
2. Any syncs using models on that warehouse are marked with a warning
3. A notification is sent to workspace administrators
4. SignalSmith continues to retry on subsequent health check intervals

To resolve an unhealthy warehouse, edit the warehouse configuration, update credentials if needed, and re-test the connection.

Next Steps

• Create a warehouse and test the connection
• Review warehouse-specific setup: Snowflake | BigQuery | Databricks