### Install sqlfmt with uv

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Installs sqlfmt into an isolated environment using the uv tool command.

```bash
uv tool install "shandy-sqlfmt[jinjafmt]"
```

--------------------------------

### Install uv

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Commands to install the uv package manager on POSIX or Windows systems.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```pwsh
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Verify sqlfmt installation

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Runs the sqlfmt executable to verify it is correctly installed and accessible in the PATH.

```bash
sqlfmt
```

--------------------------------

### Jinja Block Indentation Examples

Source: https://github.com/tconbeer/sqlfmt/blob/main/CHANGELOG.md

Examples demonstrating the updated indentation style for Jinja blocks within SQL files.

```sql
select
    some_field,
    {% for some_item in some_sequence %}
        some_function({{ some_item }}){% if not loop.last %}, {% endif %}
    {% endfor %}
```

```sql
{%- for col in cols -%}
    {%- if col.column.lower() not in remove | map(
        "lower"
    ) and col.column.lower() not in exclude | map("lower") -%}
        {% do include_cols.append(col) %}
    {%- endif %}
{%- endfor %}
```

--------------------------------

### Install sqlfmt with pip

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Installs the package using pip within an activated Python virtual environment.

```bash
pip install "shandy-sqlfmt[jinjafmt]"
```

--------------------------------

### Format Jinja templates

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

sqlfmt supports formatting Jinja tags within SQL files when the jinjafmt extra is installed.

```sql
-- Before formatting
{% set my_list = ['a','b','c',] %}
{{ dbt_utils.date_spine(datepart="day",start_date="'2021-01-01'",end_date="sysdate()") }}

-- After formatting (with jinjafmt)
{% set my_list = ["a", "b", "c"] %}
{{
    dbt_utils.date_spine(
        datepart="day",
        start_date="'2021-01-01'",
        end_date="sysdate()",
    )
}}
```

```python
# Install with jinjafmt support
# pip install "shandy-sqlfmt[jinjafmt]"

from sqlfmt.api import format_string
from sqlfmt.mode import Mode

# Jinja formatting enabled by default when black is available
mode = Mode()
source = "{% set x=['a','b','c'] %}\nselect {{ x }}"
formatted = format_string(source, mode)

# Disable Jinja formatting
mode = Mode(no_jinjafmt=True)
formatted = format_string(source, mode)
```

--------------------------------

### Display sqlfmt help

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Lists available commands and options for the sqlfmt tool.

```bash
sqlfmt --help
```

--------------------------------

### Run sqlfmt via CLI

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Execute sqlfmt from the command line with custom configuration paths or overrides.

```bash
# Use specific config file
sqlfmt --config /path/to/pyproject.toml .

# CLI options override config file settings
sqlfmt --config pyproject.toml --line-length 88 .
```

--------------------------------

### run Function

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Executes sqlfmt on a list of files with configurable modes and returns a report object.

```APIDOC
## run(files, mode)

### Description
Executes sqlfmt on multiple files with full reporting capabilities. This is the primary API for batch processing.

### Parameters
- **files** (List[Path]) - Required - A list of Path objects to format.
- **mode** (Mode) - Required - The configuration mode object.

### Response
- **report** (Report) - An object containing number_changed, number_unchanged, number_errored, and a list of results.
```

--------------------------------

### Configure sqlfmt via pyproject.toml

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Define formatting options in the [tool.sqlfmt] section of your pyproject.toml file.

```toml
# pyproject.toml
[tool.sqlfmt]
line_length = 100
dialect = "polyglot"
exclude = ["target/**/*", "dbt_packages/**/*", "snapshots/**/*"]
encoding = "utf-8"
fast = false
no_jinjafmt = false

# For ClickHouse projects with case-sensitive identifiers:
# dialect = "clickhouse"
```

--------------------------------

### Format SQL files

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Formats all .sql and .sql.jinja files in the current directory and subdirectories.

```bash
sqlfmt .
```

--------------------------------

### Configure pre-commit hook

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Add sqlfmt to your .pre-commit-config.yaml to automate SQL formatting.

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/tconbeer/sqlfmt
    rev: v0.29.0
    hooks:
      - id: sqlfmt
        # Optional: specify additional arguments
        args: ["--line-length", "100"]
        # Optional: limit to specific paths
        files: ^models/
```

--------------------------------

### Format SQL files via CLI

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Use the sqlfmt command to format SQL files in place within the current directory or specific paths.

```bash
# Format all SQL files in current directory recursively
sqlfmt .

# Format a specific file
sqlfmt path/to/query.sql

# Format multiple paths
sqlfmt models/ tests/sql/
```

--------------------------------

### Run sqlfmt on Multiple Files

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Execute sqlfmt on a list of files with various reporting options. Use `Mode(check=True)` to only verify formatting without changes, or `Mode(diff=True)` to display differences without modifying files. Access detailed results via the `report` object.

```python
from pathlib import Path
from sqlfmt.api import run, get_matching_paths
from sqlfmt.mode import Mode

# Get all SQL files in a directory
mode = Mode()
files = get_matching_paths([Path("./models")], mode)

# Run sqlfmt and get a report
report = run(files=files, mode=mode)

# Access results
print(f"Changed: {report.number_changed}")
print(f"Unchanged: {report.number_unchanged}")
print(f"Errors: {report.number_errored}")

# Check mode - don't modify files
mode = Mode(check=True)
report = run(files=files, mode=mode)
if report.number_changed > 0:
    print("Some files need formatting!")

# Diff mode - show changes without modifying
mode = Mode(diff=True)
report = run(files=files, mode=mode)
report.display_report()  # Prints colored diff to stderr

# Access individual results
for result in report.results:
    if result.has_changed:
        print(f"Would format: {result.source_path}")
    if result.has_error:
        print(f"Error in: {result.source_path} - {result.exception}")
```

--------------------------------

### Format via standard input

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Process SQL strings piped through stdin and output to stdout.

```bash
# Format SQL from stdin
echo "select 1,2,3" | sqlfmt -

# Output:
# select 1, 2, 3

# Pipe formatted output to a file
cat query.sql | sqlfmt - > formatted_query.sql
```

--------------------------------

### Configure performance options

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Adjust execution behavior for debugging, caching, or safety checks.

```bash
# Force single-process execution (useful for debugging)
sqlfmt --single-process .

# Reset cache and reformat all files
sqlfmt --reset-cache .

# Fast mode - skip safety check for faster processing
sqlfmt --fast .

# Safe mode - always run safety check (default)
sqlfmt --safe .
```

--------------------------------

### Configure sqlfmt Behavior with Mode

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

The `Mode` class centralizes all configuration for sqlfmt, including line length, dialect, exclusion patterns, and output options. It provides sensible defaults and allows for detailed customization.

```python
from pathlib import Path
from sqlfmt.mode import Mode

# Default mode
mode = Mode()
print(mode.line_length)  # 88
print(mode.dialect_name)  # "polyglot"

# Full configuration example
mode = Mode(
    line_length=100,
    dialect_name="clickhouse",  # or "polyglot"
    check=False,                # True to only check, not modify
    diff=False,                 # True to show diff output
    exclude=["target/**/*"],
    exclude_root=Path("."),     # Root for relative exclude patterns
    encoding="utf-8",           # File encoding
    fast=False,                 # True to skip safety check
    single_process=False,       # True to disable multiprocessing
    no_jinjafmt=False,          # True to skip Jinja formatting
    reset_cache=False,          # True to clear cache before run
    verbose=False,              # True for verbose output
    quiet=False,                # True for minimal output
    no_progressbar=False,       # True to disable progress bar
    no_color=False,             # True to disable colored output
    force_color=False,          # True to force colored output
)

# Access the configured dialect
analyzer = mode.dialect.initialize_analyzer(line_length=mode.line_length)
```

--------------------------------

### Display formatting diffs

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Preview formatting changes without applying them to the files.

```bash
# Show diff of formatting changes
sqlfmt --diff path/to/query.sql

# Output:
# --- source_query
# +++ formatted_query
# @@ -1,3 +1,4 @@
# -select column_a,column_b from my_table
# +select
# +    column_a,
# +    column_b
# +from my_table
```

--------------------------------

### Manage formatting cache

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Interact with the sqlfmt cache to speed up formatting or clear stale results.

```python
from sqlfmt.cache import load_cache, clear_cache, get_cache_file

# Get cache file location
cache_path = get_cache_file()
print(f"Cache location: {cache_path")} 
# Example: ~/.cache/sqlfmt/cache-0.29.0.pickle

# Load existing cache
cache = load_cache()
print(f"Cached files: {len(cache)}")

# Clear the cache programmatically
clear_cache()

# Clear cache via CLI
# sqlfmt --reset-cache .
```

--------------------------------

### Mode Configuration Class

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

The Mode class holds all configuration options for sqlfmt.

```APIDOC
## Mode Class

### Description
The Mode class is a dataclass that holds all configuration options for sqlfmt with sensible defaults.

### Configuration Options
- **line_length** (int) - Default 88
- **dialect_name** (str) - Default "polyglot"
- **check** (bool) - If True, only check without modifying
- **diff** (bool) - If True, show diff output
- **exclude** (List[str]) - Glob patterns to exclude
- **exclude_root** (Path) - Root for relative exclude patterns
```

--------------------------------

### Integrate Progress Bar

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Initialize and use a progress bar for batch operations, including callback support for custom progress updates. The `initialize_progress_bar` function returns both the progress bar object and a callback function to be passed to `run()`.

```python
from pathlib import Path
from sqlfmt.api import run, get_matching_paths, initialize_progress_bar
from sqlfmt.mode import Mode

mode = Mode()
files = get_matching_paths([Path("./models")], mode)

# Create progress bar and callback
progress_bar, callback = initialize_progress_bar(
    total=len(files),
    mode=mode,
    force_progress_bar=False  # True to force even on non-TTY
)

# Run with progress updates
report = run(files=files, mode=mode, callback=callback)
```

--------------------------------

### Select SQL dialect

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Specify the SQL dialect to use for formatting, such as polyglot or clickhouse.

```bash
# Format with ClickHouse dialect (preserves case in identifiers)
sqlfmt --dialect clickhouse .

# Default polyglot dialect (lowercases keywords and identifiers)
sqlfmt --dialect polyglot .
```

--------------------------------

### Discover SQL Files

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Find SQL files within specified directories using configured patterns and exclusions. Supports custom SQL extensions and common dbt exclusion patterns.

```python
from pathlib import Path
from sqlfmt.api import get_matching_paths
from sqlfmt.mode import Mode

# Find all SQL files in directories
mode = Mode()
paths = [Path("./models"), Path("./analyses")]
matched_files = get_matching_paths(paths, mode)
print(f"Found {len(matched_files)} SQL files")

# With exclusions (common dbt setup)
mode = Mode(
    exclude=["target/**/*", "dbt_packages/**/*"],
    exclude_root=Path(".")
)
matched_files = get_matching_paths([Path(".")], mode)

# Custom SQL extensions are automatically detected
# Default: .sql and .sql.jinja
for f in matched_files:
    print(f.name)
```

--------------------------------

### get_matching_paths Function

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Discovers SQL files matching the configured patterns and exclusions.

```APIDOC
## get_matching_paths(paths, mode)

### Description
Discover SQL files matching the configured patterns and exclusions.

### Parameters
- **paths** (List[Path]) - Required - A list of directories or files to search.
- **mode** (Mode) - Required - The configuration mode object containing exclude patterns.
```

--------------------------------

### Verify formatting with check mode

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Check if files are properly formatted without modifying them. Returns exit code 1 if formatting is needed.

```bash
# Check formatting without modifying files
sqlfmt --check .

# Output:
# 5 files passed formatting check.
# 2 files failed formatting check.
```

--------------------------------

### Mode Configuration

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Configuration object used to define formatting behavior such as line length and SQL dialect.

```APIDOC
## Mode Configuration

### Description
Defines the settings for the sqlfmt formatter.

### Parameters
#### Request Body
- **line_length** (int) - Optional - Maximum line length for formatted output (default: 88).
- **dialect_name** (string) - Optional - SQL dialect to use (e.g., 'polyglot', 'clickhouse').

### Request Example
```python
# Custom line length and dialect
mode = Mode(line_length=120, dialect_name="clickhouse")
```
```

--------------------------------

### Configure line length

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Set the maximum line length for the formatter using long or short flags.

```bash
# Set custom line length
sqlfmt --line-length 120 .

# Short form
sqlfmt -l 100 models/
```

--------------------------------

### Configure output verbosity

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Control the level of feedback provided during the formatting process.

```bash
# Disable progress bar
sqlfmt --no-progressbar .

# Verbose output - show unchanged files
sqlfmt --verbose .

# Quiet mode - minimal output
sqlfmt --quiet .

# Disable colored output
sqlfmt --no-color .

# Force colored output (overrides NO_COLOR env var)
sqlfmt --force-color .
```

--------------------------------

### format_string(source, mode)

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

The primary function for formatting SQL strings programmatically. It accepts a raw SQL string and a Mode configuration object to return the formatted SQL.

```APIDOC
## format_string(source, mode)

### Description
Formats a raw SQL string based on the provided configuration mode.

### Parameters
#### Request Body
- **source** (string) - Required - The raw SQL string to be formatted.
- **mode** (Mode) - Required - A configuration object defining formatting rules like line length and dialect.

### Request Example
```python
from sqlfmt.api import format_string
from sqlfmt.mode import Mode

source = "select column_a,column_b from my_table"
mode = Mode(line_length=88)
formatted = format_string(source, mode)
```

### Response
#### Success Response (200)
- **formatted_sql** (string) - The resulting formatted SQL string.
```

--------------------------------

### Format SQL from stdin

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Reads SQL code from standard input and outputs the formatted result to standard output.

```bash
echo "select 1" | sqlfmt -
```

--------------------------------

### SqlFormatResult Class

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Represents the result of formatting a single file.

```APIDOC
## SqlFormatResult

### Description
Represents the result of formatting a single file, including source and formatted strings.

### Fields
- **source_path** (Path) - Path to the original file
- **source_string** (str) - Original content
- **formatted_string** (str) - Formatted content
- **has_changed** (bool) - True if formatting changed the content
- **has_error** (bool) - True if an error occurred
- **exception** (Exception) - The exception if has_error is True
```

--------------------------------

### Exclude files and directories

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Use glob patterns to ignore specific files or directories during formatting.

```bash
# Exclude specific directories (common for dbt projects)
sqlfmt . --exclude "target/**/*" --exclude "dbt_packages/**/*"

# Exclude files matching a pattern
sqlfmt . --exclude "**/test_*.sql"
```

--------------------------------

### Process Formatting Results

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

The `SqlFormatResult` class represents the outcome of formatting a single file. It provides access to original and formatted content, change status, and error details. Results are aggregated in the `Report` object returned by `run()`.

```python
from sqlfmt.report import SqlFormatResult
from pathlib import Path

# Results are returned from run() in the Report object
# Each result contains:
# - source_path: Path to the original file
# - source_string: Original content
# - formatted_string: Formatted content
# - has_changed: True if formatting changed the content
# - has_error: True if an error occurred
# - exception: The exception if has_error is True

# Example working with results
from sqlfmt.api import run, get_matching_paths
from sqlfmt.mode import Mode

mode = Mode(check=True)
files = get_matching_paths([Path("./models")], mode)
report = run(files=files, mode=mode)

for result in report.results:
    if result.has_error:
        print(f"Error: {result.source_path}")
        print(f"  {result.exception}")
    elif result.has_changed:
        print(f"Needs formatting: {result.display_path}")
        # Access the diff
        print(f"  Source length: {len(result.source_string)}")
        print(f"  Formatted length: {len(result.formatted_string)}")
```

--------------------------------

### Exclude directories in configuration

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Configures sqlfmt to ignore specific directories when formatting, such as dbt target folders.

```toml
[tool.sqlfmt]
exclude=["target/**/*", "dbt_packages/**/*"]
```

--------------------------------

### Handle sqlfmt exceptions

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Use specific exception classes to catch and handle formatting or parsing errors.

```python
from sqlfmt.api import format_string
from sqlfmt.mode import Mode
from sqlfmt.exception import (
    SqlfmtError,           # Base class for all sqlfmt errors
    SqlfmtParsingError,    # Invalid SQL syntax
    SqlfmtBracketError,    # Mismatched brackets
    SqlfmtUnicodeError,    # File encoding issues
    SqlfmtConfigError,     # Invalid configuration
    SqlfmtEquivalenceError # Safety check failed
)

mode = Mode()

# Handling parsing errors
try:
    formatted = format_string("select )", mode)
except SqlfmtBracketError as e:
    print(f"Bracket error: {e}")

# Handling general errors
try:
    formatted = format_string("invalid {{ syntax", mode)
except SqlfmtError as e:
    print(f"Formatting error: {e}")

# Working with run() - errors don't raise, they're in results
from sqlfmt.api import run, get_matching_paths
from pathlib import Path

files = get_matching_paths([Path(".")], mode)
report = run(files=files, mode=mode)

for result in report.errored_results:
    print(f"Error in {result.source_path}: {result.exception}")
```

--------------------------------

### Format SQL using Python API

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Use the format_string function to programmatically format SQL strings with custom modes.

```python
from sqlfmt.api import format_string
from sqlfmt.mode import Mode

# Basic formatting with default settings
source = """
select column_a,column_b,
case when x > 1 then 'yes' else 'no' end as flag
from my_table where id=1
"""

mode = Mode()
formatted = format_string(source, mode)
print(formatted)
# Output:
# select
#     column_a,
#     column_b,
#     case when x > 1 then 'yes' else 'no' end as flag
# from my_table
# where id = 1

# Custom line length
mode = Mode(line_length=120)
formatted = format_string(source, mode)

# ClickHouse dialect (preserves case)
mode = Mode(dialect_name="clickhouse")
formatted = format_string("SELECT MyColumn FROM MyTable", mode)
print(formatted)
# Output: SELECT MyColumn FROM MyTable
```

--------------------------------

### Check formatting without modifying files

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Verifies if files are formatted correctly without applying changes. Exits with code 1 if files are not properly formatted.

```bash
sqlfmt --check .
sqlfmt --diff .
```

--------------------------------

### Specify file encoding

Source: https://context7.com/tconbeer/sqlfmt/llms.txt

Define the character encoding for reading and writing files.

```bash
# Use UTF-8 encoding (default)
sqlfmt --encoding utf-8 .

# Use system default encoding
sqlfmt --encoding inherit .

# Use specific encoding
sqlfmt --encoding cp1252 .
```

--------------------------------

### Format with ClickHouse dialect

Source: https://github.com/tconbeer/sqlfmt/blob/main/README.md

Uses the ClickHouse dialect to prevent unwanted lowercasing of identifiers. Can be applied via command line or configuration file.

```bash
$ sqlfmt . --dialect clickhouse
```

```toml
[tool.sqlfmt]
dialect = "clickhouse"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.