Skip to main content

jarify

Bespoke SQL linter and formatter for DuckDB, built on sqlglot.

Existing SQL formatters can't be configured to enforce a specific team style, and none of them are DuckDB-aware. Jarify parses SQL with the DuckDB dialect and rewrites it through an opinionated, non-configurable formatter — no style debates, consistent output everywhere.

Installation

uv tool install jarify

Or run one-off without installing:

uvx jarify fmt path/to/query.sql

Upgrade

uv tool upgrade jarify

Pin to a specific version

uv tool install 'jarify==0.1.0'

Commands

jarify fmt — format SQL files

jarify fmt [OPTIONS] [FILES]...

Reads each file, formats it, and writes the result back in place.

Option Description
- Read from stdin
--config PATH Load config from an explicit file path
--check Exit non-zero if any file would change (useful in CI)
--diff Print a unified diff instead of rewriting files
--stdin-filename NAME Config discovery anchor and diff label when reading from stdin

Exit codes: 0 = all files already formatted, 1 = files were reformatted, 2 = error.

# Format a single file
jarify fmt query.sql

# Check all .sql files without modifying them (CI mode)
jarify fmt --check **/*.sql

# Preview changes as a diff
jarify fmt --diff query.sql

# Pipe from stdin
cat query.sql | jarify fmt -

jarify lint — lint SQL files

jarify lint [OPTIONS] [FILES]...

Reports style and semantic violations. Does not modify files.

Option Description
--config PATH Load config from an explicit file path
--stdin-filename NAME Config discovery anchor and filename label when reading from stdin
`--format text json`
jarify lint query.sql

jarify init — create a config file

jarify init

Writes a project-local jarify.toml in the current directory.

jarify show-config — inspect active config

jarify show-config
jarify show-config --config path/to/jarify.toml

Prints the effective configuration (syntax-highlighted TOML).

Configuration files

When --config PATH is provided, that file wins and no discovery runs. Without --config, Jarify looks for config in this order:

  1. Project-local jarify.toml, found by walking upward from the config start directory.
    • For stdin, --stdin-filename sets the start directory.
    • Otherwise, discovery starts from the current working directory.
  2. The first existing global config:
    1. $XDG_CONFIG_HOME/jarify/config.toml
    2. $XDG_CONFIG_HOME/jarify/jarify.toml
    3. ~/.config/jarify/config.toml
    4. ~/.config/jarify/jarify.toml
    5. ~/jarify.toml
  3. Built-in defaults

When both project-local and global config exist, Jarify loads the global config first and overlays the project-local config on top. Tables such as [jarify.rules.*] merge key by key; any other value, including a list such as uppercase_functions, is replaced as a whole by the project value. This lets global config hold personal defaults while project config still enforces repository policy. Explicit --config PATH is not merged with any other config.

Project-local config is best for repository style rules that should be shared by every contributor:

[jarify]
no_select_star = "error"

Global config is useful for personal preferences that should not be committed to a repo:

# ~/.config/jarify/config.toml
[jarify]
indent = 4

Two options tune where column aliases align. min-column-alias sets a floor for the alignment column. alias_visual_guide_interval (or alias-visual-guide-interval) moves AS to the first column, counted from 1, that is a multiple of the interval, so it sits on your editor's visual guides (DataGrip calls them Visual guides). With both set, the floor applies first. See Column alias alignment for examples.

Function name case

Jarify writes aggregate and window functions uppercase and every other function lowercase. To override that for specific function names, list them (case-insensitively) in uppercase_functions or lowercase_functions:

[jarify]
uppercase_functions = ["list"]          # always written uppercase
lowercase_functions = ["any_value"]     # always written lowercase

A name in both lists is a config error. If a project config lists a name that global config puts in the other list, the project config wins. See Function case overrides for examples.

Style and lint rules

Jarify enforces a single, opinionated default style with limited config for rule severity and personal preferences. See the SQL Style Guide for the complete rule reference with bad/good examples for every formatting and lint rule.

Development

Requires mise and uv.

git clone https://github.com/amfaro/jarify.git
cd jarify
uv sync --all-groups

mise run test    # run tests
mise run lint    # ruff check
mise run check   # lint + test

Adding a new fixture test

  1. Create tests/fixtures/<category>/<name>.input.sql with the raw SQL
  2. Run uv run pytest tests/test_fixtures.py --update-fixtures to generate the expected output
  3. Review tests/fixtures/<category>/<name>.expected.sql and commit both files

Releases

Releases are fully automated across two workflows — no manual tagging required.

prepare-release.yml runs on every push to main that touches src/** or tests/**. It uses git-cliff to compute the next semver from unreleased conventional commits, bumps the version in pyproject.toml, regenerates CHANGELOG.md, and opens (or updates) a release/vX.Y.Z PR. If there are no new conventional commits since the last tag, it exits silently.

publish.yml triggers when pyproject.toml changes on main (i.e., when the release PR is merged). It builds the package with uv build, publishes to PyPI via OIDC trusted publishing, creates the vX.Y.Z git tag, and creates a GitHub Release with auto-generated notes and dist artifacts.

Human steps:

  1. Land a feature or fix on main using conventional commit messages (feat:, fix:, etc.) → the release PR is opened automatically.
  2. Review the CHANGELOG entries in the release PR, then merge it → PyPI publish, git tag, and GitHub Release happen automatically.

Metadata

Release files for jarify 0.15.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jarify 0.15.0
File Size Uploaded Provenance Actions
jarify-0.15.0.tar.gz 232.9 kB Without provenance Details for jarify-0.15.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jarify 0.15.0
File Interpreter ABI Platform Actions
jarify-0.15.0-py3-none-any.whl Python 3 none any Details for jarify-0.15.0-py3-none-any.whl

Total release size: 343.0 kB

Release files / jarify-0.15.0.tar.gz

Download URL jarify-0.15.0.tar.gz
Size 232.9 kB
Tags Source
SHA-256 checksum
How to use checksums
fe6dc4a0caaa059b734eb081cccbffb58ee5a6dbb17dcbe1dc99181824fc15c4
BLAKE2b-256 checksum
How to use checksums
27aa4c94b7976414e8c5b0dd05fa4ee92f1b05f616afbb8f0c746716cc115a35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / jarify-0.15.0-py3-none-any.whl

Download URL jarify-0.15.0-py3-none-any.whl
Size 110.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d90533ab798cbcc89bef327fc0754f526b3dfb7302f135d7fc94b3b1fc29948d
BLAKE2b-256 checksum
How to use checksums
9d762c4f3fe09f8a7cafde895e1c0596ef090b256c1fc3f7dd339a42b80d511d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for jarify 0.15.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.15.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page