Skip to main content

sqlfmt is an opinionated CLI tool that formats your sql files

Project description

sqlfmt

PyPI Lint and Test PyPI - Python Version Runs on Windows Runs on MacOS Runs on Linux Code style: black Imports: isort Checked with mypy

sqlfmt is an opinionated CLI tool that formats your dbt sql files. It is similar in nature to black, gofmt, and rustfmt.

sqlfmt is not configurable, except for line length. It enforces a single style. sqlfmt maintains comments and some extra newlines, but largely ignores all indentation and line breaks in the input file.

sqlfmt is not a linter. It does not parse your code; it just tokenizes it and tracks a small subset of tokens that impact formatting. This lets us "do one thing and do it well:" sqlfmt is very fast, and easier to extend than linters that need a full sql grammar.

sqlfmt is designed to work with sql files that contain jinja tags and blocks. It formats the code that users look at, and therefore doesn't need to know anything about what happens after the templates are rendered.

Installation and Getting Started

You will need Python 3.7-3.10 installed. sqlfmt has a dependency on Click, so you should use pipx or install into a virtual environment (maybe as a dev-dependency in your project).

Install Using pipx (recommended)

pipx install shandy-sqlfmt

Other Installation Options

You should use a virutal environment to isolate sqlfmt's dependencies from others on your system. We recommend poetry (poetry add -D shandy-sqlfmt), or pipenv (pipenv install -d shandy-sqlfmt), but a simple pip install shandy-sqlfmt will also work.

Other prerequisits

sqlfmt is an alpha product and will not always produce the formatted output you might want. It might even break your sql syntax. It is highly recommended to only run sqlfmt on files in a version control system (like git), so that it is easy for you to revert any changes made by sqlfmt. On your first run, be sure to make a commit before running sqlfmt.

Using sqlfmt

sqlfmt is a command-line tool. It works on any posix terminal and on Windows Powershell. If you have used black, the sqlfmt commands will look familiar. To list commands and options:

sqlfmt --help

From your current working directory, sqlfmt . will format all files .sql or .sql.jinja files in your working directory or any nested directories. You can also supply a path to a single file or a directory as an argument sqlfmt /path/to/my/dir. Using the --check or --diff options, like sqlfmt --check will prevent sqlfmt from writing formatted files, and the program will exit with an exit code of 1 if it detects any changes.

Contributing

Setting up Your Dev Environment and Running Tests

  1. Install Poetry if you don't have it already. You may also need or want pyenv, make, and gcc. A complete setup from a fresh install of Ubuntu can be found here
  2. Clone this repo into a directory (let's call it sqlfmt), then cd sqlfmt
  3. Use poetry install to install the project (editable) and its dependencies into a new virtual env. To run sqlfmt_primer, you will need to install it (and its dependencies) by specifying it as an extra: poetry install -E sqlfmt_primer
  4. Use poetry shell to spawn a subshell
  5. Type make to run all tests and linters, or run pytest, black, flake8, isort, and mypy individually.

Note: If encountering a JSONDecodeError during poetry install, you will want to clear the poetry cache with poetry cache clear pypi --all.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

shandy-sqlfmt-0.2.0.tar.gz (26.9 kB view hashes)

Uploaded Source

Built Distribution

shandy_sqlfmt-0.2.0-py3-none-any.whl (29.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page