CLI¶

sqlty [-h] [--version]
      {rewrite,strip,check,breaking,rule,skill,version} ...

sqlty rewrite .   # "--sql\n..." -> SQL[T]("--sql\n...")
sqlty check .     # lint row types, drift, SELECT *
sqlty check --fix .  # apply the fixable rules, report the rest
sqlty strip .     # SQL[T]("--sql\n...") -> "--sql\n..."

Each command takes files or directories (default: the current directory) and processes every .py file under them, skipping the default and configured excludes (.venv, .git, node_modules, ...) while walking a directory; a file named on the command line is always processed unless --force-exclude is given. A path that does not exist is an error. Each file uses [tool.sqlty] from the nearest pyproject.toml above it that has one; see Configuration. Command-line flags override it.

Configuration flags¶

To run sqlty on a project without editing its pyproject.toml, pass the settings on the command line or in a file of your own. The flags follow ty and ruff:

sqlty check --config-file ~/sqlty.toml .            # one file for every path
sqlty check -c 'schema = "db/"' -c 'dialect = "mysql"' .  # override single keys
sqlty check --isolated --schema db/ .               # defaults plus flags only
sqlty check --ignore select-star --error stale-type .  # rule severities
sqlty check --extend-exclude 'legacy/*' .           # skip more than the config does
sqlty rewrite --exclude migrations --exclude build .  # replace the excludes

--config-file PATH reads [tool.sqlty] from a file named pyproject.toml and the same keys at the top level of any other file, such as sqlty.toml.

sqlty.toml:

schema = "db/schema"
extend-exclude = ["migrations"]

[rules]
select-star = "ignore"

It replaces the per-file lookup for every path, and its relative paths (schema, exclude, extend-exclude) start from the current directory, so the file can live outside the project. SQLTY_CONFIG_FILE sets it when --config-file is not given. --isolated ignores every configuration file, including SQLTY_CONFIG_FILE; it cannot be combined with --config-file.

-c/--config KEY=VALUE is a TOML assignment applied on top of whichever configuration applies, --isolated included. Repeat it for several keys; the last value of a key wins, and tables merge key by key, so -c 'rules.select-star = "ignore"' keeps the other configured rules. Its schema, exclude and extend-exclude are relative to the current directory, like the flags of the same name, which take precedence.

--error RULE, --warn RULE and --ignore RULE set a rule's severity over [tool.sqlty.rules] and -c; for a rule given several times, the last flag wins.

--exclude GLOB replaces exclude from the config together with the default excludes; the config's extend-exclude still applies. --extend-exclude GLOB adds to whichever list applies. Both repeat, and their globs follow the rules of exclude, relative to the current directory. --force-exclude applies the excludes to files and directories named on the command line too, which is useful when a tool such as pre-commit passes file names.

Exit codes¶

Common options¶

rewrite, strip and check accept:

strip accepts --dialect and --schema but does not use them.

sqlty reads Python files as UTF-8. A file it changes keeps its byte order mark and its line endings, \n or \r\n, as the first line has them.

sqlty rewrite¶

Wrap --sql strings in SQL[T](...) with the inferred row type and add the imports the types need. Implicitly concatenated strings are wrapped as one query. Existing wrappers are left alone. --sql strings that are not plain literals (f-, t-, raw or bytes strings, alone or in a concatenation) are skipped and reported on stderr (fstring-skipped, tstring-skipped, unchecked-query) unless -q is given or the rule is set to ignore; they never change the exit code.

sqlty rewrite [-h] [--dialect DIALECT] [--schema SCHEMA]
              [--config-file PATH | --isolated] [-c KEY=VALUE]
              [--error RULE] [--warn RULE] [--ignore RULE]
              [--exclude GLOB] [--extend-exclude GLOB]
              [--force-exclude]
              [--respect-gitignore | --no-respect-gitignore] [-v] [-q]
              [-j N] [--check] [--diff] [--untyped {skip,sentinel}]
              [paths ...]

Exit code: see Exit codes; 1 with --check or --diff when files would change.

sqlty strip¶

Remove SQL[...](...) wrappers around --sql strings, including hand-written row types such as SQL[User], and the sqlty import line. When the strings can't stand alone (a comment outside them, or line breaks that only the call's parentheses allow), the parentheses stay: SQL[T]("..." # c\n) becomes ("..." # c\n). A wrapper whose argument is not only string literals (SQL[T]("--sql..." + x)) is left in place, as is a dotted mod.SQL[T](...), which check still checks.

sqlty strip [-h] [--dialect DIALECT] [--schema SCHEMA]
            [--config-file PATH | --isolated] [-c KEY=VALUE]
            [--error RULE] [--warn RULE] [--ignore RULE]
            [--exclude GLOB] [--extend-exclude GLOB] [--force-exclude]
            [--respect-gitignore | --no-respect-gitignore] [-v] [-q]
            [-j N] [--check] [--diff]
            [paths ...]

Exit code: see Exit codes; 1 with --check or --diff when files would change.

sqlty check¶

Lint --sql strings and SQL[T](...) wrappers. Prints one line per diagnostic and a summary:

queries.py:2: [narrow-type] SQL[tuple[int, str]] should be SQL[tuple[int, str, str]]
Found 1 error(s)

sqlty check [-h] [--dialect DIALECT] [--schema SCHEMA]
            [--config-file PATH | --isolated] [-c KEY=VALUE]
            [--error RULE] [--warn RULE] [--ignore RULE]
            [--exclude GLOB] [--extend-exclude GLOB] [--force-exclude]
            [--respect-gitignore | --no-respect-gitignore] [-v] [-q]
            [-j N] [--fix] [--exit-zero] [--exit-zero-on-warning]
            [--error-on-warning] [--statistics] [--explain]
            [--output-format {text,json,github}]
            [paths ...]

With --statistics, the last line counts the queries of the checked files:

Queries: 1 typed, 1 partially typed, 1 unparsed, 1 skipped (fstring-skipped: 1)

A query is typed when every column of its row type is known, and partially typed when some column's type is not (SELECT * with no schema, an unknown column). Unparsed queries are those the parser rejects, whether or not unparsed-query is enabled. Skipped strings are f-, t- and raw strings, and other --sql strings that are not plain literals, counted by the rule that reports them. Queries that return no rows are not counted.

Rule severities come from [tool.sqlty.rules], -c and --error/--warn/--ignore; see Rules.

Exit code: 1 if any diagnostic has severity error; warnings alone exit 0. As in ty, --exit-zero always exits 0, --error-on-warning also exits 1 on a warn diagnostic, and --exit-zero-on-warning keeps the default; combining --error-on-warning with either of the others is an error (exit 2).

sqlty breaking¶

Check the queries and schema of two revisions across, as during a rolling deploy: the queries of --against on the schema of --head (backward), and the queries of --head on the schema of --against (forward). Prints what the other schema breaks. --against is a git revision, a snapshot that --save wrote, a directory of snapshots, or a schema file (see Baselines without git history):

app/q.py:2: [unknown-column] column `bio` does not exist in `users` (backward: the queries of origin/main against the schema of the working tree)
Found 1 breaking change(s)

sqlty breaking [-h] [--against BASELINE] [--save PATH] [--head REF]
               [--direction {backward,forward,both}] [-q]
               [--output-format {text,json,github}]
               [paths ...]

Exit code: 1 when a change breaks either direction with an error diagnostic, 2 for an unknown revision or outside a git repository. See Breaking schema changes.

sqlty rule¶

Print a rule's documentation, or list every rule with its default severity.

sqlty rule [-h] [name]

sqlty skill¶

Print an Agent Skill for coding agents (sqlty by default), list them, or write them all into the directory your agent reads skills from. See Coding agents.

sqlty skill --install .claude/skills

sqlty skill [-h] [--install DIR | --list] [name]

sqlty version¶

Print sqlty <version> and exit. sqlty --version does the same.

Other entry points¶

Environment variables¶