Consolidated Run SQL Endpoint

Execute SQL queries through a single, unified endpoint that replaces multiple legacy execution paths. This consolidation simplifies client integrations by providing one consistent interface for all SQL operations, with standardized error handling, response formats, and authorization checks across query types.

What Changed

• Single Canonical Endpoint: All SQL execution now routes through /run-sql, eliminating confusion about which endpoint to use for different query types
• Standardized Response Structure: Every query returns the same response shape with columns, rows, rowCount, and executionTime fields—no more parsing different formats
• Workspace-Scoped Authorization: Users with workspace-level access can execute queries directly, with permission checks enforced server-side based on their role
• Timeout Control: Client-configurable query timeout prevents runaway queries from blocking resources

Endpoint

POST /api/v1/accounts/{accountId}/workspaces/{workspaceId}/run-sql

Request Format

{
  "sql": "SELECT customer_id, SUM(total) as revenue FROM orders GROUP BY customer_id ORDER BY revenue DESC LIMIT 10",
  "timeout": 30000
}

Response Format

{
  "ok": true,
  "data": {
    "columns": [
      { "name": "customer_id", "type": "VARCHAR" },
      { "name": "revenue", "type": "NUMBER" }
    ],
    "rows": [
      ["CUST-001", 125000.5],
      ["CUST-042", 98500.0]
    ],
    "rowCount": 10,
    "executionTime": 245
  }
}

Migration Notes

If you were using any of these legacy patterns, migrate to the consolidated endpoint:

1. Direct SQL execution endpoints: Replace with /run-sql
2. Thread-based SQL execution: Use /run-sql directly; thread context is no longer required for standalone queries
3. Custom timeout handling: Pass timeout in the request body instead of query parameters

The response format is backwards-compatible—existing client code parsing columns and rows will continue to work.