Test Data Source Connection

Sprint 3

Test the connection to a data source. This operation runs asynchronously in a thread pool executor to prevent blocking.

Endpoint

POST /api/v1/data-sources/{data_source_id}/test

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>
Content-Type	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
data_source_id	integer	Yes	Data source ID

Request Body

Optional. If not provided, uses default test query.

{
  "test_query": "SELECT 1",
  "timeout_seconds": 30
}

Parameters

Field	Type	Required	Description
test_query	string	No	Custom test query to execute
timeout_seconds	integer	No	Connection timeout in seconds

Response

Success (200)

{
  "success": true,
  "data": {
    "data_source_id": 1,
    "status": "active",
    "connection_successful": true,
    "response_time_ms": 45,
    "test_query_result": "1",
    "tested_at": "2024-12-01T11:00:00Z",
    "ssh_tunnel_established": false,
    "database_version": "PostgreSQL 14.5",
    "error_message": null,
    "error_code": null
  },
  "message": "Connection test completed"
}

Connection Failed (200)

{
  "success": true,
  "data": {
    "data_source_id": 1,
    "status": "failed",
    "connection_successful": false,
    "response_time_ms": null,
    "test_query_result": null,
    "tested_at": "2024-12-01T11:00:00Z",
    "ssh_tunnel_established": false,
    "database_version": null,
    "error_message": "Connection refused",
    "error_code": "CONNECTION_ERROR"
  },
  "message": "Connection test completed"
}

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing authentication token
403	FORBIDDEN	User is not a member of any organization
404	NOT_FOUND	Data source not found

Features

• Runs asynchronously in thread pool executor (non-blocking)
• Tests actual database connection
• Optional custom test query
• SSH tunnel testing
• Database version detection
• Updates connection status and timestamps
• Response time measurement

Example

curl -X POST "https://api.rivergen.com/api/v1/data-sources/1/test" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "test_query": "SELECT version()",
    "timeout_seconds": 30
  }'

Related Endpoints

• Get Data Source - View connection status
• Get Health - View connection health history