CLI Reference#

The sqltidy command-line interface formats, rewrites, and analyzes SQL files.

Installation#

Install SQLTidy to get the sqltidy command:

pip install sqltidy

Quick Start#

# Show version
sqltidy version

# Format a SQL file
sqltidy tidy example.sql

# Format a folder recursively
sqltidy tidy "SQL Files" -r

# Rewrite and format
sqltidy rewrite complex_query.sql --tidy

# Create a dialect rulebook
sqltidy rulebooks create -d postgresql

# List supported dialects
sqltidy dialects list

Command Overview#

Main Commands#

sqltidy tidy - Format SQL Files

Format SQL files using tidy rules without changing structure.

sqltidy tidy file.sql
sqltidy tidy folder/ -r

sqltidy rewrite - Transform SQL Structure

Transform SQL structure (e.g., subquery→CTE, alias styles).

sqltidy rewrite file.sql
sqltidy rewrite file.sql --tidy

sqltidy rulebooks - Manage Configuration

Manage dialect-specific configuration rulebooks.

sqltidy rulebooks create -d postgresql
sqltidy rulebooks list
sqltidy rulebooks edit mysql

sqltidy rules - Manage Custom Rules

Manage custom formatting/rewrite rule plugins.

sqltidy rules add my_rule.py
sqltidy rules list
sqltidy rules remove old_rule.py

sqltidy dialects - Explore SQL Dialects

Explore SQL dialects and their features.

sqltidy dialects list
sqltidy dialects keywords postgresql
sqltidy dialects datatypes sqlserver
sqltidy dialects functions mysql

Additional Commands#

parse

Tokenize and analyze SQL structure.

sqltidy parse file.sql --dialect postgresql

patterns

Inspect SQL patterns and constructs.

sqltidy patterns list postgresql
sqltidy patterns show file.sql

version

Display SQLTidy version.

sqltidy version

Common Options#

These options appear across multiple commands:

-d, --dialect {sqlserver,postgresql,mysql,oracle,sqlite}

SQL dialect for parsing and formatting.

Default: sqlserver

-o, --output PATH

Output file or folder path.

-r, --recursive

Process folders recursively.

--pattern PATTERN

Glob pattern for file selection (default: *.sql).

--no-in-place

Don't modify files; output to stdout.

--format {table,json}

Output format for display commands.

Common Workflows#

Format an entire project#

# Recursively format all SQL files
sqltidy tidy "SQL Files" -r -d postgresql

Migrate to CTE style#

# First, edit rulebook to enable subquery→CTE
sqltidy rulebooks edit postgresql
# Set "enable_subquery_to_cte": true

# Then rewrite with formatting
sqltidy rewrite "Legacy SQL" -r --tidy

Set up dialect preferences#

# Create rulebook
sqltidy rulebooks create -d mysql

# Edit preferences
sqltidy rulebooks edit mysql

# Use it
sqltidy tidy queries/ -d mysql -r

Add custom formatting#

# Create rule file: remove_comments.py
# (see 'sqltidy rules' docs for examples)

# Add to SQLTidy
sqltidy rules add remove_comments.py

# Sync rulebooks
sqltidy rulebooks sync all

# Configure in rulebook
sqltidy rulebooks edit sqlserver

Compare dialects#

# Compare keywords
sqltidy dialects keywords sqlserver > sqlserver.txt
sqltidy dialects keywords postgresql > postgresql.txt
diff sqlserver.txt postgresql.txt

# View functions
sqltidy dialects functions oracle | grep -i date

Default Behavior#

Output Location#

When --output is not specified:

Single file: Creates Cleaned/ subfolder next to input
Folder: Creates Cleaned/ subfolder inside input folder
Stdin: Prints to stdout

File Discovery#

When processing folders:

Searches for *.sql files by default
Use --pattern to change (e.g., *.tsql, *.pgsql)
Respects --recursive flag for subdirectories

Configuration#

Rulebook lookup order:

User rulebook: ~/.sqltidy/rulebooks/sqltidy_{dialect}.json
Bundled rulebook: Package default
Auto-generated: From rule metadata

File Locations#

User Data#

~/.sqltidy/: User configuration directory
~/.sqltidy/rulebooks/: Custom dialect rulebooks
~/.sqltidy/rules/: Custom rule plugins

Package Data#

{package}/sqltidy/rulebooks/: Bundled dialect defaults