Custom format SQL statements

Preview

This feature is in Public Preview.

This article explains how to customize SQL auto-formatting options in the Databricks UI.

Overview

SQL formatting improves the readability and maintainability of your queries. By standardizing indentation, keyword casing, and other stylistic preferences, a well-formatted query is easier to understand, debug, and share with your team.

In Databricks, you can configure formatting options using a .dbsql-formatter-config.json file saved in your workspace home directory. After saving the file, your SQL code is automatically formatted based on your preferences when you run or format code in the editor or a SQL notebook.

How to configure SQL formatting settings

To configure your personal SQL formatting options:

1. Click Workspace in the sidebar.
2. Click Create > File.
3. Name the file .dbsql-formatter-config.json.
4. Add your desired settings as key-value pairs in JSON format. See Formatter options
5. To apply the latest formatting settings, refresh the page.

Example configuration file

The following example shows a valid .dbsql-formatter-config.json configuration.

JSON

{
  "printWidth": 80,
  "indentationStyle": "spaces",
  "indentationWidth": 4,
  "keywordCasing": "uppercase",
  "shouldExpandExpressions": true
}

Formatter options

The following table lists the supported configuration options.

Option	Config file name	Allowed values	Default	Description
Print width	printWidth	Any integer >= 0	100	Sets the target line width for formatted code.
Indentation style	indentationStyle	'spaces', 'tabs'	'spaces'	Specifies whether to use spaces or tabs for indentation. If set, indentationWidth is ignored.
Indentation width	indentationWidth	Integer from 0 to 99	2	Number of spaces used when indentationStyle is set to 'spaces'.
Keyword casing	keywordCasing	'uppercase', 'lowercase', 'none'	'none'	Controls formatting of SQL keywords. 'none' leaves casing unchanged.
Function name casing	functionNameCasing	'uppercase', 'lowercase', 'none'	'none'	Controls formatting of SQL function names. 'none' leaves casing unchanged.
Comma placement	commaPosition	'beginning', 'end'	'end'	Controls where commas are placed in lists.
Line breaks between statements	numNewLinesBetweenStatements	Integer from 0 to 99	1	Number of new lines inserted between statements.
Line breaks between clauses	numNewLinesBetweenClauses	Integer from 0 to 99	0	Number of new lines inserted between clauses within a statement.
Expand boolean expressions	shouldExpandExpressions	true, false	true	Expands boolean expressions onto separate lines.
Expand CASE statements	shouldExpandCaseStatements	true, false	true	Expands each clause in a CASE statement onto its own line.
Expand IN lists	shouldExpandInStatements	true, false	false	Expands items in IN lists onto separate lines.
Expand BETWEEN conditions	shouldExpandBetweenConditions	true, false	false	Expands BETWEEN conditions onto separate lines.
Break JOIN conditions	shouldBreakOnJoinSections	true, false	true	Breaks JOIN conditions onto separate lines.