# FAQ

## How do I type SQL queries in Python?

Start the query string with `--sql`. `sqlty rewrite .` infers the row type from the casts in the query or from your `CREATE TABLE` statements, and wraps the string as `SQL[T]`, for example `SQL[tuple[int, str]]`. `SQL[T]` is a `str` subclass, so the query still runs anywhere a string does, and mypy, pyright and ty see the row type. `sqlty check .` reports when the SQL and `T` no longer agree. See the [Quickstart](<https://sqlty.kuncar.dev/quickstart/index.md>).

## When should I use sqlty?

When you write raw SQL as string literals and want the type checker to know what each query returns and takes. sqlty fits a codebase with a schema dump or migrations in the repository, where a renamed or retyped column should fail CI, not production. It also fits code that adopts types one query at a time, scripts and notebooks, and SQL written by AI assistants. See [Use cases](<https://sqlty.kuncar.dev/use-cases/index.md>).

## When should I not use sqlty?

When the SQL is not a literal: a query built at run time, by string operations or a query builder, is not read. When you use an ORM's query API, use the ORM's typing support instead. sqlty checks statically, so if you need rows validated as they arrive, use Pydantic. See [When to use something else](<https://sqlty.kuncar.dev/motivation/#when-to-use-something-else>).

## How can I write raw SQL in Python without an ORM?

Keep the SQL as a string literal and pass it to your driver: psycopg, PyMySQL, `sqlite3` or any other. sqlty adds types around the string without changing it, so the query runs as written, with no query builder or model layer. With [psycopg](<https://sqlty.kuncar.dev/guide/psycopg/index.md>), `execute(conn, SQL[User](...))` returns a `Cursor[User]` whose rows are `User` objects. See [Raw SQL without an ORM](<https://sqlty.kuncar.dev/use-cases/#raw-sql-without-an-orm>).

## How do I pass values into a SQL query safely?

Use the driver's placeholders, such as `%s`, `%(name)s`, `$1`, `?` or `:name`, and pass the values as parameters. Never build the query with f-strings, `%` or `str.format()`: the driver escapes parameters, but not text pasted into the SQL. sqlty gives each placeholder a type from where it sits in the query, and `sqlty check` reports a call that passes the wrong number of values or a value of the wrong type. See [Query parameters](<https://sqlty.kuncar.dev/guide/parameters/index.md>).

## How do I get typed rows instead of tuples of `Any`?

Annotate the query with a row type: a `TypedDict`, `NamedTuple`, dataclass or Pydantic model, as `SQL[User](...)`. `sqlty check` compares its fields with the columns the query returns, by count, name and type. With psycopg, `sqlty.drivers.psycopg.execute` picks the matching row factory, so each row is built as `User` at runtime. See [Row types](<https://sqlty.kuncar.dev/guide/row-types/index.md>).

## Does sqlty need a database connection?

No. sqlty reads column types from casts in the query or from `CREATE TABLE` statements in a schema file, such as a `pg_dump --schema-only` dump or a migrations snapshot. It runs offline, in an editor, pre-commit or CI. See [Schema inference](<https://sqlty.kuncar.dev/guide/schema-inference/index.md>).

## Can sqlty catch totals that a join counts twice?

Yes. `fanout-aggregate` reports a `SUM`, `AVG` or `COUNT` over a table whose rows a one-to-many join repeats, such as averaging order totals after joining their items. `chasm-join` reports a table joined one-to-many to two others, such as orders to items and to payments. sqlty reads the primary, unique and foreign keys of your schema, so no database is needed. See [Joins and aggregates](<https://sqlty.kuncar.dev/guide/joins/index.md>).

## Can sqlty catch a join on the wrong key?

Yes, once you turn on `entity-mismatch` in `[tool.sqlty.rules]`. It follows foreign keys to the table whose keys each column holds, and reports a comparison such as `products.id = orders.customer_id`. It is off by default, because a polymorphic id or a schema without foreign keys can compare unrelated keys on purpose. See [Joins on the wrong key](<https://sqlty.kuncar.dev/guide/joins/#joins-on-the-wrong-key>).

## Is sqlty a semantic layer?

No. Semantic layers such as MetricFlow, Cube and LookML define metrics and generate the SQL that computes them, guarding against aggregates over rows a join repeats. sqlty generates no SQL: it reports those aggregates in the SQL you write. See [Joins and aggregates](<https://sqlty.kuncar.dev/guide/joins/index.md>).

## Which databases and drivers does sqlty support?

PostgreSQL, MySQL and SQLite are fully supported, with types following psycopg 3, PyMySQL and `sqlite3`. Other dialects that sqlparser-rs reads, such as DuckDB, BigQuery, Snowflake and ClickHouse, work on a best-effort basis. See [Drivers and ORMs](<https://sqlty.kuncar.dev/guide/drivers-and-orms/index.md>) and the [Engine](<https://sqlty.kuncar.dev/reference/engine/#dialects>).

## Does sqlty work with SQLAlchemy, Django or other ORMs?

Yes, for the raw SQL you run through them, such as SQLAlchemy's `text()` with `:name` placeholders. sqlty types the value the driver returns, and some ORMs convert it first, for example SQLite dates to `datetime.date`. [Drivers and ORMs](<https://sqlty.kuncar.dev/guide/drivers-and-orms/index.md>) lists those conversions and what to annotate.

## Can I keep queries in `.sql` files?

Yes. Point `queries` in `[tool.sqlty]` at your `.sql` files, and `sqlty check` runs the same rules on the named queries that aiosql, PugSQL and sqlc read. See [Queries in .sql files](<https://sqlty.kuncar.dev/guide/sql-files/index.md>).

## How do I format SQL query strings in Python?

Write the query as a triple-quoted string and run `sqlty format .`. It lays out the SQL with sqruff's layout rules, in your project's dialect, and changes only whitespace, so the query means the same. `sqlty format --check .` fails CI when a query is not formatted. See [Formatting queries](<https://sqlty.kuncar.dev/guide/formatting/index.md>).

## Is sqlty a query builder or an ORM?

No. You write the SQL yourself, and sqlty checks it. It infers types, rewrites the annotations in your source and lints the queries, but it never generates SQL or maps tables to classes. See [Why SQLTy?](<https://sqlty.kuncar.dev/motivation/index.md>).

## How does sqlty compare with asyncpg\_typed?

asyncpg\_typed checks types you declare by hand when asyncpg prepares each query on a live PostgreSQL server. sqlty infers the types from casts or a schema and checks them statically, with no database, for PostgreSQL, MySQL, SQLite and DuckDB, and it also infers nullability. asyncpg\_typed types the rows asyncpg returns and compares `StrEnum` values with the database; sqlty does neither yet. See [asyncpg\_typed](<https://sqlty.kuncar.dev/motivation/#asyncpg_typed>).

## Which Python versions are supported?

Python 3.14 and 3.15. Install with `pip install sqlty` or `uv add sqlty`. See [Installation](<https://sqlty.kuncar.dev/installation/index.md>).
