sqlnbfmt 0.2.0

A tool to format SQL code in Jupyter notebooks.

sqlnbfmt

A SQL formatter designed specifically for Jupyter Notebooks. sqlnbfmt automatically formats SQL queries embedded in code cells, including both Python strings and SQL magic cells (%%sql), helping you maintain clean and consistent code.

Features

• 🎯 Smart SQL Detection: Automatically identifies and formats SQL queries in code cells and magic SQL cells
• 🌳 AST-Powered: Uses Abstract Syntax Tree parsing for accurate SQL string identification
• 🔒 Safe Formatting: Preserves Python comments, query parameters (e.g., %s, ?), and SQL comments
• ⚙️ Highly Configurable: Customize formatting through YAML configuration
• 🔄 Pre-commit Ready: Seamlessly integrates with pre-commit hooks
• 📦 Lightweight: Only three runtime dependencies (sqlglot, nbformat, pyyaml)

Installation

pip install sqlnbfmt

Usage

Command Line

Format a single notebook:

sqlnbfmt path/to/your_notebook.ipynb

Format all notebooks in a directory:

sqlnbfmt path/to/notebooks/

Pre-commit Integration

1. Install pre-commit:

pip install pre-commit

2. Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/flyersworder/sqlnbfmt
    rev: v0.2.0
    hooks:
      - id: sqlnbfmt
        name: sqlnbfmt
        types: [jupyter]
        args: [--config, config.yaml, --dialect, postgres]

Please run the following command for help:

sqlnbfmt -h

3. Install the hook:

pre-commit install

4. (Optional) Run on all files:

pre-commit run --all-files

Configuration

Create a config.yaml file to customize formatting behavior. Here is a template.

Configuration Options

Option	Description	Default
sql_keywords	SQL keywords to recognize and format	Common SQL keywords
function_names	Python functions containing SQL code	[]
sql_decorators	Decorators indicating SQL code	[]
single_line_threshold	Maximum length before splitting SQL	80
indent_width	Number of spaces for indentation	4

Example

Before formatting:

execute_sql("""SELECT a.col1, b.col2 FROM table_a a JOIN table_b b ON a.id = b.a_id WHERE a.status = 'active' ORDER BY a.created_at DESC""")

After formatting:

execute_sql("""
SELECT
  a.col1,
  b.col2
FROM
  table_a AS a
JOIN
  table_b AS b
  ON a.id = b.a_id
WHERE
  a.status = 'active'
ORDER BY
  a.created_at DESC
""")

Contributing

We welcome contributions! Here's how to get started:

1. Clone the repository:

git clone https://github.com/flyersworder/sqlnbfmt.git
cd sqlnbfmt

2. Use uv to sync the environment:

uv sync
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Run tests:

pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• sqlglot - SQL parsing and formatting engine
• All contributors and early adopters who helped shape this tool

---

Made with ♥️ by the sqlnbfmt team