Developer Documentation

SQL Formatter API Reference

Integrate AST-level SQL formatting into CI/CD pipelines, pre-commit hooks, IDE plugins, and backend services using the Connect RPC JSON API.

Endpoint Information

POSThttps://api.leuduan.work/sqlformat.v1.SqlFormatService/FormatSql

ProtocolConnect Protocol v1 (JSON over HTTP/POST)

AuthenticationPublic (No API key required for standard use)

Required Request Headers

Header Name	Required Value	Description
Content-Type	application/json	Payload content format
Connect-Protocol-Version	1	Specifies Connect RPC protocol specification version

Request Body Parameters

Field	Type	Required	Description
sql	string	Yes	The raw SQL query or multi-statement script to format.
dialect	string	Yes	Target dialect: `bigquery`, `postgresql`, `mysql`, `mssql`, `clickhouse`, `snowflake`, `duckdb`, `sqlite`, `generic`
options	object	No	Formatting configuration object (details below).
options.max_length	number	No	Maximum target line length before wrapping (default: 120).
options.keyword_handling	string	No	`TEXT_CASE_UPPER_CASE` or `TEXT_CASE_LOWER_CASE`
options.builtin_function_handling	string	No	`TEXT_CASE_UPPER_CASE` or `TEXT_CASE_LOWER_CASE`
options.indent_cte_definitions	boolean	No	Indent common table expression bodies (default: true).
options.googlesql.always_break_pipe	boolean	No	Break each GoogleSQL pipe (\|>) onto a newline (default: true).

Response Body & Errors

Response Field	Type	Status / Presence	Description
formatted_sql	string	200 OK (Success)	The formatted SQL output text with canonical indentation and applied options.
dialect	string	200 OK (Success)	The canonical dialect identifier used for formatting (e.g. `bigquery`, `postgresql`).
code	string	4xx / 5xx (Error)	Connect error code (e.g. `invalid_argument`, `internal`).
message	string	4xx / 5xx (Error)	Human-readable error description, including syntax error locations (line and column) when parsing fails.

Code Integration Examples

cURL Request

curl -sS -X POST "https://api.leuduan.work/sqlformat.v1.SqlFormatService/FormatSql" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  -d '{
    "dialect": "bigquery",
    "sql": "SELECT c.id, c.name, SUM(o.amount) as total FROM `my_project.analytics.customers` c JOIN `my_project.analytics.orders` o ON c.id = o.customer_id GROUP BY c.id, c.name HAVING total > 1000",
    "options": {
      "max_length": 100,
      "keyword_handling": "TEXT_CASE_UPPER_CASE",
      "builtin_function_handling": "TEXT_CASE_LOWER_CASE",
      "indent_cte_definitions": true,
      "always_break_select": false,
      "always_break_query": true,
      "googlesql": {
        "always_break_pipe": true
      }
    }
  }' | jq -r '.formatted_sql'

Sample JSON Response

HTTP 200 OK

{
  "formatted_sql": "SELECT\n  c.id,\n  c.name,\n  sum(o.amount) AS total\nFROM `my_project.analytics.customers` AS c\nJOIN `my_project.analytics.orders` AS o\n  ON c.id = o.customer_id\nGROUP BY c.id, c.name\nHAVING total > 1000;",
  "dialect": "bigquery"
}

Try the Interactive Formatter

Experiment with queries, options, and live Git diffs in the web browser.

Open SQL Formatter