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	No	Target dialect; defaults to `bigquery` when omitted. Supported canonical values: `bigquery`, `postgresql`, `mysql`, `mssql`, `clickhouse`, `snowflake`, `duckdb`, `sqlite`, `oracle`, `databricks`, `sparksql`, `hive`, `redshift`, `generic`
options	object	No	Formatting configuration object (details below).
options.max_length	number	No	Maximum target line length before wrapping (default: 80 when omitted).
options.keyword_handling	string	No	`TEXT_CASE_UPPER_CASE` or `TEXT_CASE_LOWER_CASE`
options.dialect	string	No	Compatibility field in the protobuf schema. The public handler uses the top-level `dialect` field to select the parser; set that field instead.
options.indent_cte_definitions	boolean	No	Indent common table expression bodies (default: true).
options.always_break_select	boolean	No	Put each SELECT clause on its own line when enabled (default: false).
options.always_break_query	boolean	No	Prefer a multiline layout for each query or statement (default: false). It is forced on when `always_break_select` is enabled.
options.googlesql.always_break_pipe	boolean	No	Break each GoogleSQL pipe (\|>) onto a newline (default: false).
options.googlesql.builtin_function_handling	string	No	`TEXT_CASE_UNSPECIFIED`, `TEXT_CASE_UPPER_CASE`, or `TEXT_CASE_LOWER_CASE`. UNSPECIFIED preserves the original function spelling.
options.sqlserver.version	string	MSSQL only	Optional ScriptDOM grammar version from `SQL_SERVER_VERSION_80` through `SQL_SERVER_VERSION_180`. Omit it to use the latest supported grammar.

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`).
metadata	object	MSSQL response	Reports the effective SQL Server grammar in `sqlserver_version` and whether the response used `SQL_FORMAT_MODE_LINE` or `SQL_FORMAT_MODE_SCRIPTDOM_FALLBACK`.
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.

HTTP Behavior and Errors

Successful requests return HTTP 200 with a JSON response containing formatted SQL and the applied dialect.
Invalid SQL, an empty sql value, or an unsupported dialect returns HTTP 400 with code: "invalid_argument".
Formatter or engine failures use a non-2xx Connect error such as internal (500) or unavailable (503). Do not treat an error body as a FormatSqlResponse.
Normal requests are ephemeral and require no API key. Browser calls are CORS-enabled for the production formatter and local development origins.

{
  "code": "invalid_argument",
  "message": "Parse error at line 1, column 15: Unexpected token"
}

Code Integration Examples

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",
      "indent_cte_definitions": true,
      "always_break_select": false,
      "always_break_query": true,
      "googlesql": {
        "always_break_pipe": true,
        "builtin_function_handling": "TEXT_CASE_UNSPECIFIED"
      }
    }
  }' | jq -r '.formatted_sql'

Sample JSON Response

{
  "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