readsql

Convert SQL to the most human-readable format. For the time being, it uppercases SQL keywords; it might prettify or even suggest improvements to SQL code in the future. It converts SQL code and even SQL strings in programming languages (only Python at the moment).

So if we write

select sushi, avg(price) from tokyo where ocean = 'pacific' group by sushi

readsql will help us read it as

SELECT sushi, AVG(price) FROM tokyo WHERE ocean = 'pacific' GROUP BY sushi

Installation

pip install readsql

Requires Python 3.8+.

Usage

• Format SQL code provided in command line
• readsql -s
• Format an SQL file or folder
• as in a folder, it will look for files ending with .sql or .py
• readsql

It supports multiple strings and files or folders as well

1.

readsql   -s

• In Python files, it looks for variable query strings and formats them

readsql  

We can look for different strings in Python files with -py arguments

readsql  -py  

Note: readsql uses Python's AST parser, so it supports:

- Type Hints: query: str = "..."

- F-strings: f"SELECT * FROM {table}"

- Nested Scopes: Robustly handles variables inside functions and classes.

- Comments/Docstrings: Correctly ignores SQL-like text in comments or docstrings.

Usage examples

• readsql 'select sushi from tokyo' -s command returns
• SELECT sushi FROM tokyo
• a. readsql sql_example.sql command, while sql_example.sql is a SQL file with code as below,

select max(height), avg(mass), min(age) from jungle group by forest where animal=elephant;

replaces the file with this code

SELECT MAX(height), AVG(mass), MIN(age) FROM jungle GROUP BY forest WHERE animal=elephant;

• b. The readsql sql_in_python_variable_example.py command, while sql_in_python_variable_example.py is a Python file with code as below,

def get_query():
    limit = 6
    query = f"SELEct speed from world where animal='dolphin' limit {limit}"
    return query

replaces the file with this code

def get_query():
    limit = 6
    query = f"SELECT speed FROM world WHERE animal='dolphin' LIMIT {limit}"
    return query

• c. readsql sql_in_python_variable_example.py -py sql command, while sql_in_python_variable_example.py is a Python file with code as below,

def get_query():
    limit = 6
    sql = f"SELEct speed from world where animal='dolphin' limit {limit}"
    return sql

replaces the file with this code

def get_query():
    limit = 6
    sql = f"SELECT speed FROM world WHERE animal='dolphin' LIMIT {limit}"
    return sql

• d. The readsql tests -n command outputs all of the formatted SQL code in the tests folder; files are not replaced by the formatted version (-n argument stands for not-replace)

More examples can be found in the /tests folder

Add a pre-commit hook

How to add a pre-commit hook for readsql?

repos:
  repo: https://github.com/AzisK/readsql
    
rev: v1.0.0  # Replace by any tag/version: https://github.com/azisk/readsql/tags
    hooks:
    
  id: readsql

Development

Clone the repo and use uv for development:

uv sync --all-extras                                    # Install dependencies
uv run readsql "select sushi from tokyo" -s             # Format a string
uv run readsql tests/sql_example.sql                    # Format SQL file
uv run readsql tests/sql_in_python_example.py           # Format SQL in Python
uv run readsql tests/sql_in_python_variable_example.py -py sql  # Custom variable
uv run readsql tests                                    # Format all files in folder

Testing

uv run pytest -v

--- Tranlated By Open Ai Tx | Last indexed: 2026-05-30 ---