django-sql-compiler 0.1.1__tar.gz → 1.0.0__tar.gz

django_sql_compiler-1.0.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-11-01
+
+The first release with safe SQL composition: `sql_and_params`, `compose`/`ComposeResult` and `fetch_rows` turn querysets into parameterized SQL, embed them in hand-written queries and return typed rows, and psycopg 3 is now supported. `executable_query` users upgrading from 0.2.0 get no breaking changes. Two behavior changes are worth knowing: empty querysets now return zero-row SQL instead of raising `EmptyResultSet` (see Fixed), and a PostgreSQL connection whose raw connection is neither psycopg2 nor psycopg 3 now raises `NotImplementedError`; stock Django never creates one (see Changed).
+
+### Added
+
+- `fetch_rows(result, row)` runs a `compose()` result once on its alias through Django's cursor and returns a list of rows: dataclass instances (pass the dataclass type; columns are matched to its constructor fields by exact, case-sensitive name, and fields with defaults may be missing) or dicts in select order (pass `dict`), with values exactly as the driver returns them, on every Django backend. Input other than a `ComposeResult`, or a row kind other than `dict` or a dataclass type, raises `TypeError` before any SQL runs; extra columns, missing fields, duplicate column names, a statement with no result set and a result with no columns raise `ValueError`.
+- `compose(template, **slots)` (and its result type `ComposeResult`) embeds querysets, earlier `compose()` results and plain values in a hand-written SQL template with `%(name)s` slots and returns `(sql, params)` for the querysets' shared alias (`.alias`), with params in placeholder order and repeated for reused slots, values always bound as params, `%%` kept as a literal `%`, on every Django backend; mixed aliases, missing or unused slots, bad `%` forms, a template with no queryset, and Manager, RawQuerySet, Query, expression, Q or tuple slots raise `ValueError` or `TypeError`.
+- `sql_and_params(queryset)` and `SQLCompilerQuerySet.sql_and_params()` return a queryset's parameterized SQL and params (a tuple) compiled for the queryset's own database alias, on every Django backend, for executing through Django's cursor or `raw()` on that alias. Empty querysets return zero-row SQL with the same columns. Anything that isn't a QuerySet raises TypeError.
+- psycopg 3 support (psycopg >=3.2) for the PostgreSQL ENGINE strings `django.db.backends.postgresql` and `django_tenants.postgresql_backend`, with Django's default client-side binding and with `OPTIONS={'server_side_binding': True}`. `executable_query` used to raise TypeError or AttributeError under psycopg 3. Values are escaped by psycopg 3 itself, so some literals differ from psycopg2's (for example strings with a backslash render as `E'...'`).
+
+### Changed
+
+- The README and PyPI summary now lead with parameterized composition ("Use Django querysets inside raw SQL, safely.") with one complete CTE example returning typed rows, PyPI keywords were added, and the README's `executable_query` examples no longer pass a params argument (`raw(sql, None)`, `cursor.execute(sql)`), which broke on `%` in inlined values.
+- A PostgreSQL connection whose raw connection is neither psycopg2 nor psycopg 3 now raises `NotImplementedError` naming its module and class.
+
+### Fixed
+
+- `executable_query` no longer raises `EmptyResultSet` for querysets Django evaluates as empty (`.none()`, `filter(id__in=[])`, an empty slice such as `qs[5:5]`, an empty HAVING clause, a union of empty parts, a subquery on an empty queryset). It returns SQL that has the same columns as the non-empty queryset and matches no rows, so it can be embedded in a CTE, a UNION or an `IN (...)` subquery. SQL for querysets that already compiled is unchanged. Known limitation: an aggregate written as raw SQL (`RawSQL` or `extra(select=...)`, such as `COUNT(*)`) in a queryset with no aggregate Django recognizes has no GROUP BY, so its empty SQL returns one row instead of none. An empty slice's zero-row SQL has no LIMIT/OFFSET; other sliced querysets keep theirs.
+
+### Packaging
+
+- The Development Status classifier is now `5 - Production/Stable`.
+
+## [0.2.0] - 2026-10-25
+
+The first release since 0.1.1 (June 2021). It ships correctness fixes and first-time MySQL support.
+
+### Added
+
+- MySQL support for `django.db.backends.mysql` (via mysqlclient), contributed in [PR 2](https://github.com/JaredStufftGD/django-sql-compiler/pull/2). It is covered by the live-database test suite and CI. In 0.1.1 the MySQL compiler was a stub and was not registered.
+
+### Fixed
+
+- Non-ASCII parameters are decoded with the connection's encoding instead of byte by byte, so values like `café` are no longer garbled. 0.1.1 corrupted them.
+- SQL is compiled for the queryset's own database alias (`.using()` or a database router) instead of the default alias.
+- The unsupported-backend error names the ENGINE instead of saying "None backend is not supported".
+
+### Changed
+
+- Decoding is strict. Compiler output that can't be decoded with the connection's codec raises `UnicodeDecodeError` (or `LookupError` for an unknown client encoding) instead of returning garbled text. A Postgres connection on `SQL_ASCII`, or another unusual client encoding, with non-ASCII data now raises where 0.1.1 returned text. A compiler that returns non-bytes raises `TypeError`.
+- Semi-public API:
+  - `sql_compiler.utils.bytes_to_string` now requires an `encoding` argument.
+  - `BaseSQLCompiler` has a new `python_encoding(connection)` method that custom compiler subclasses must implement (the base raises `NotImplementedError`).
+  - `MySQLCompiler` is exported from `sql_compiler.compilers`.
+- Install requirements: Python >=3.10 and Django >=4.2. The package declares no database driver (psycopg2 or mysqlclient comes from your Django setup). Effects on existing environments:
+  - With an older Django installed but not pinned, upgrading django-sql-compiler can upgrade Django (accepted, because Django <4.2 is end-of-life).
+  - With Django <4.2 pinned, or on Python <3.10, pip stays on 0.1.1.
+  - An install from git master already reports 0.2.3, so pip won't treat 0.2.0 as an upgrade. Install `django-sql-compiler==0.2.0` explicitly.
+
+### Packaging
+
+- Ships a wheel again (0.1.1 was sdist-only; 0.0.5a0 and 0.1.0 had wheels).
+- Built with flit_core instead of setuptools.
+- The license is declared with PEP 639 `License-Expression: MIT`, and LICENSE ships in both artifacts.
+- Metadata-Version 2.5.
+- CHANGELOG.md ships in the sdist.
+
+### Known issues
+
+- psycopg 3 is not supported yet. With psycopg 3 installed, Django uses it and `executable_query` raises (planned for 1.0). 0.1.1 had this issue too.
+- `.none()` querysets raise `EmptyResultSet` (planned for 1.0). 0.1.1 had this issue too.
+
+[1.0.0]: https://github.com/JaredStufftGD/django-sql-compiler/releases/tag/v1.0.0
+[0.2.0]: https://github.com/JaredStufftGD/django-sql-compiler/releases/tag/v0.2.0

django_sql_compiler-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Grok Data
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_sql_compiler-1.0.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.5
+Name: django-sql-compiler
+Version: 1.0.0
+Summary: Use Django querysets inside raw SQL, safely.
+Keywords: django,raw sql,cte,subquery,queryset,sql composition
+Author-email: Grok Data / Jared Stufft <jared@grokdata.tech>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Project-URL: Changelog, https://github.com/JaredStufftGD/django-sql-compiler/blob/master/CHANGELOG.md
+Project-URL: Homepage, https://github.com/JaredStufftGD/django-sql-compiler
+Project-URL: Issues, https://github.com/JaredStufftGD/django-sql-compiler/issues
+Project-URL: Source, https://github.com/JaredStufftGD/django-sql-compiler
+Import-Name: sql_compiler
+
+# Django SQL Compiler
+
+[![CI](https://github.com/JaredStufftGD/django-sql-compiler/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/JaredStufftGD/django-sql-compiler/actions/workflows/ci.yml)
+
+Use Django querysets inside raw SQL, safely.
+
+Build any queryset with the ORM (filters, joins, annotations, aggregates, `values()`) and write the rest (CTEs, window functions, anything the ORM can't express well) by hand. The ORM builds and validates the queryset, so user input never has to be pasted into SQL text: every value stays a parameter that the database driver binds, on the queryset's own database. When you need a finished literal SQL string instead (for COPY, CREATE VIEW, logs or another tool), see "Finished literal SQL" under "Choosing an API" below.
+
+## Installation
+```
+pip install django-sql-compiler
+```
+
+No database driver is installed with the package and there are no extras: it uses the database connection your Django project already has, so the driver (for example psycopg2, psycopg 3 or mysqlclient) comes from your existing Django setup.
+
+Add `sql_compiler` to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...,
+    'sql_compiler'
+]
+```
+
+`sql_and_params()`, `compose()` and `fetch_rows()` work on plain Django querysets with no custom manager. `SQLCompilerManager` is only needed for the queryset methods described below (`qs.sql_and_params()` and the finished-literal-SQL property).
+
+## Filter with the ORM, finish in SQL.
+Any queryset works here; this example uses two filtered ones. The ORM builds and binds them, and the handwritten SQL joins the two sets, groups them, filters on the aggregate and ranks the result in one readable statement.
+
+Write the handwritten SQL in your database's dialect; this example's SQL is portable (PostgreSQL, SQLite, MySQL 8).
+
+Models and the result type (no custom manager needed):
+
+```python
+import dataclasses
+import datetime
+
+from django.db import models
+from sql_compiler import compose, fetch_rows
+
+
+class Customer(models.Model):
+    name = models.CharField(max_length=100)
+    region = models.CharField(max_length=20)
+
+
+class Order(models.Model):
+    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
+    placed = models.DateField()
+    amount_cents = models.IntegerField()
+
+
+@dataclasses.dataclass
+class RegionLeader:
+    name: str
+    orders: int
+    total_cents: int
+    place: int
+```
+
+Data:
+
+```python
+ada = Customer.objects.create(name='Ada', region='west')
+bo = Customer.objects.create(name='Bo', region='west')
+cy = Customer.objects.create(name='Cy', region='west')
+di = Customer.objects.create(name='Di', region='east')
+
+for customer, placed, amount_cents in [
+    (ada, datetime.date(2026, 3, 3), 4000),
+    (ada, datetime.date(2026, 3, 20), 3000),
+    (bo, datetime.date(2026, 3, 10), 9000),
+    (bo, datetime.date(2026, 2, 28), 500),
+    (cy, datetime.date(2026, 3, 15), 1500),
+    (di, datetime.date(2026, 3, 5), 50000),
+]:
+    Order.objects.create(customer=customer, placed=placed, amount_cents=amount_cents)
+```
+
+Query:
+
+```python
+region = 'west'                                                     # user input, bound
+start, end = datetime.date(2026, 3, 1), datetime.date(2026, 4, 1)   # user input, bound
+min_total_cents = 5000                                              # extra value in handwritten SQL, bound
+
+customers = Customer.objects.filter(region=region).values('id', 'name')
+orders = Order.objects.filter(placed__gte=start, placed__lt=end).values('customer_id', 'amount_cents')
+
+leaderboard = compose(
+    '''
+    WITH c AS (%(customers)s), o AS (%(orders)s)
+    SELECT c.name AS name,
+           COUNT(*) AS orders,
+           SUM(o.amount_cents) AS total_cents,
+           RANK() OVER (ORDER BY SUM(o.amount_cents) DESC) AS place
+    FROM c JOIN o ON o.customer_id = c.id
+    GROUP BY c.id, c.name
+    HAVING SUM(o.amount_cents) >= %(min_total_cents)s
+    ORDER BY place, name
+    ''',
+    customers=customers,
+    orders=orders,
+    min_total_cents=min_total_cents,
+)
+rows = fetch_rows(leaderboard, RegionLeader)   # runs on leaderboard.alias ('default' here)
+# [RegionLeader(name='Bo', orders=1, total_cents=9000, place=1),
+#  RegionLeader(name='Ada', orders=2, total_cents=7000, place=2)]
+```
+
+- `region`, `start`, `end` and `min_total_cents` are all params that the driver binds. Params follow placeholder order: the CTE params first, then the HAVING value. Params are adapted by the backend, so they are not printed here.
+- The handwritten SQL references only the CTE names, so no table names are needed.
+- Output columns are aliased explicitly in lowercase, because `fetch_rows` matches names exactly.
+- The template is trusted SQL written by you, and a literal `%` in it is written `%%`. The package does not validate SQL or make interpolated identifiers safe.
+
+## Choosing an API
+
+### SQL and params
+`sql_and_params(queryset)` returns the parameterized SQL (a `str` with Django's `%s` placeholders) and its params (a `tuple`) for any Django queryset. It compiles for the database the queryset runs on (`qs.db`, from `.using()` or your database routers), recompiles on every call, and leaves values in params for the driver to bind.
+
+```python
+from django.db import connections
+from sql_compiler import sql_and_params
+
+qs = Customer.objects.filter(region='west')
+sql, params = sql_and_params(qs)
+with connections[qs.db].cursor() as cursor:
+    cursor.execute('select count(*) from ({}) a'.format(sql), params)
+```
+
+Querysets from `SQLCompilerManager` also have `qs.sql_and_params()`, which returns the same pair. Anything that isn't a QuerySet (a manager, a RawQuerySet) raises `TypeError`.
+
+- The pair is for Django's cursor on that alias (`connections[qs.db].cursor()`), and for `qs.raw(sql, params)` (or `Customer.objects.raw(sql, params, using=qs.db)`), which runs on that alias, when the queryset selects the model's own instances (no `values()`, `values_list()` or aggregates). `Customer.objects.raw(sql, params)` without `using=` runs on the router's or default alias, not `qs.db`. The raw driver cursor is not supported (SQLite's, for example, uses `?`).
+- In hand-written SQL around it, keep user input in params and write a literal `%` as `%%`.
+- Empty querysets (`.none()`, `filter(id__in=[])`, an empty HAVING, an empty slice such as `qs[5:5]`) return SQL that matches no rows with the same columns.
+- Known limitation: an aggregate written as raw SQL (`RawSQL` or `extra(select=...)`, such as `COUNT(*)`) in a queryset with no aggregate Django recognizes has no GROUP BY, so its empty SQL returns one row instead of none.
+
+### Compose
+`compose(template, **slots)` fills the `%(name)s` slots of a hand-written SQL template with querysets, earlier `compose()` results and plain values. It returns one result that unpacks as `sql, params` for the querysets' shared database, with params in placeholder order and every value bound by the driver.
+
+```python
+from django.db import connections
+from sql_compiler import compose
+
+# start comes from the CTE example above
+result = compose(
+    'WITH recent AS (%(recent)s), big AS (%(big)s) '
+    'SELECT recent.id FROM recent JOIN big ON big.id = recent.id WHERE recent.amount_cents > %(min_cents)s',
+    recent=Order.objects.filter(placed__gte=start).values('id', 'amount_cents'),
+    big=Order.objects.filter(amount_cents__gte=1000).values('id'),
+    min_cents=50,
+)
+with connections[result.alias].cursor() as cursor:
+    cursor.execute(*result)
+    rows = cursor.fetchall()
+```
+
+- A QuerySet slot inserts its SQL as `sql_and_params` compiles it, a `compose()` result inserts its SQL (so results nest), and anything else becomes a `%s` param. Lists go to the driver unchanged.
+- Write a literal `%` as `%%`. It stays `%%` in the result, also when nested.
+- Embedded SQL is inserted as is, without added parentheses, so write them in the template.
+- All querysets and nested results must share one alias (`result.alias`), otherwise `ValueError`. At least one slot must hold a queryset or a `compose()` result.
+- Missing or unused slots, a positional `%s`, a lone `%` and any other `%(...)` form raise `ValueError` (with the position for `%` problems). A manager, a RawQuerySet, a Query, a Django expression such as `Subquery` and a `Q` raise `TypeError`.
+- A tuple (such as a `sql_and_params` pair) raises `TypeError`, because drivers bind tuples differently. Pass the queryset or a `compose()` result instead.
+- The template is trusted SQL: never build it from user input. Keep input in slots. A `%(name)s` inside a SQL string literal in the template is still a slot.
+- The result is for Django's cursor on `result.alias`, not the raw driver cursor. For `raw()`, use `Order.objects.raw(*result, using=result.alias)`.
+- Empty querysets embed SQL that matches no rows, with the same raw-SQL aggregate limitation as `sql_and_params`.
+
+### Typed rows
+`fetch_rows(result, row)` runs a `compose()` result and returns the rows as dataclass instances or dicts.
+
+```python
+from sql_compiler import fetch_rows
+
+# leaderboard: the compose() result from the CTE example above
+dicts = fetch_rows(leaderboard, dict)             # [{'name': 'Bo', 'orders': 1, 'total_cents': 9000, 'place': 1}, ...]
+leaders = fetch_rows(leaderboard, RegionLeader)   # [RegionLeader(...), ...]
+```
+
+- It runs the result once on `result.alias` through Django's cursor and returns a list (empty when there are no rows). It adds no transaction.
+- `row=dict` gives dicts with the columns in select order. `row=<dataclass type>` builds instances by keyword.
+- For a dataclass, the column names must match the constructor fields exactly and case-sensitively. Fields with a default or default_factory may be missing. `init=False` fields and ClassVar are not columns.
+- Values are passed through exactly as the driver returns them, with no conversion (SQLite returns decimals as float, MySQL returns the SUM of an integer as Decimal, so on MySQL the example's `total_cents` is a `Decimal`), so alias columns explicitly in lowercase.
+- Anything but a `compose()` result, or a row kind other than `dict` or a dataclass type, raises `TypeError` before any SQL runs.
+- A statement with no result set (it has already run), a result with no columns, duplicate column names, and extra columns or missing fields raise `ValueError`, checked before any row is built.
+
+### Finished literal SQL: executable_query
+`executable_query` gives you usable SQL from a QuerySet as one finished string, with every value escaped by the database driver. It is a property of `SQLCompilerQuerySet`, so the model needs `objects = SQLCompilerManager()`.
+
+Casting a queryset's `Query` object with `str(qs.query)` prints out what looks like valid SQL, but Django renders it for display: values are not escaped or quoted by the driver, so it is not actually valid SQL once there are dynamic components (such as filters from user input) in the `QuerySet`.
+
+Use it when a finished literal string is required: COPY, CREATE VIEW, logs, or passing the SQL to another tool. Prefer the parameterized APIs above whenever the SQL can be executed with params.
+
+```python
+from django.db import connections, models
+from sql_compiler import SQLCompilerManager
+
+
+class Customer(models.Model):
+    objects = SQLCompilerManager()
+    name = models.CharField(max_length=100)
+    region = models.CharField(max_length=20)
+
+
+qs = Customer.objects.filter(region='west')
+sql = qs.executable_query
+
+with connections[qs.db].cursor() as cursor:
+    cursor.execute('CREATE VIEW west_customers AS ' + sql)
+
+west = Customer.objects.raw('SELECT * FROM ({}) a'.format(sql), None, using=qs.db)
+```
+
+It works only on the ENGINEs and drivers listed under "Backend and version support"; other backends (for example SQLite) raise `NotImplementedError`. Empty querysets compile to zero-row SQL with the same columns.
+
+- Never supply a params argument when passing its output to `raw()` or `cursor.execute()`: `%` characters in inlined values (any `contains` or `startswith` lookup, or a value like `50% off`) can be interpreted as formatting placeholders. Call `cursor.execute(sql)` with no second argument. With `raw()`, pass `None` explicitly as params (`Customer.objects.raw(sql, None)`), because raw()'s default `()` counts as a params argument at the driver. Handwritten text wrapped around the output must not contain `%s` placeholders either.
+- Filter values appear in plaintext in the SQL, so treat it as sensitive data in logs and caches.
+- The property is cached per queryset instance (each `.filter()` returns a new queryset), so read it after the queryset is fully built.
+
+### Django's cursor or raw()
+- Use `connections[result.alias].cursor()` (or `connections[qs.db]`) with `cursor.execute(*result)` when you need arbitrary columns or aggregates, or `fetch_rows` to get rows as dicts or dataclasses.
+- Use `raw(sql, params)` only when the SQL returns the model's own rows, including its primary key.
+- Pass `using=` (`result.alias` or `qs.db`) to `raw()`: `Model.objects.raw` without it runs on the router's or default alias.
+- Never use the raw driver cursor.
+
+## Backend and version support
+The parameterized APIs (`sql_and_params`, `compose`, `fetch_rows`) compile through Django's own backend compiler and work on every Django backend. SQL you write around them can still depend on the backend's features (the CTE example needs CTEs and window functions).
+
+`executable_query` supports exactly these Django `ENGINE` values:
+
+- `django.db.backends.postgresql`
+- `django.db.backends.postgresql_psycopg2`: a legacy alias for the PostgreSQL backend that Django removed in Django 3.0. The package still accepts the ENGINE string and maps it to the same compiler.
+- `django_tenants.postgresql_backend` (django-tenants)
+- `django.db.backends.mysql` (via mysqlclient)
+
+PostgreSQL connections work with psycopg2 and with psycopg 3 (psycopg >=3.2), including Django's `server_side_binding` option. Other PostgreSQL drivers raise `NotImplementedError`.
+
+Python >=3.10 and Django >=4.2 are supported, subject to Django's own Python compatibility for each release. CI tests Django 4.2, 5.2 and 6.1 (on Python 3.10 to 3.14), plus live PostgreSQL 18 (psycopg2, psycopg 3 and psycopg 3 with server-side binding) and MySQL 8.4 jobs, and SQLite in every run. A job against Django's development branch runs for information only and is not a support promise.
+

django_sql_compiler-1.0.0/README.md

@@ -0,0 +1,237 @@
+# Django SQL Compiler
+
+[![CI](https://github.com/JaredStufftGD/django-sql-compiler/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/JaredStufftGD/django-sql-compiler/actions/workflows/ci.yml)
+
+Use Django querysets inside raw SQL, safely.
+
+Build any queryset with the ORM (filters, joins, annotations, aggregates, `values()`) and write the rest (CTEs, window functions, anything the ORM can't express well) by hand. The ORM builds and validates the queryset, so user input never has to be pasted into SQL text: every value stays a parameter that the database driver binds, on the queryset's own database. When you need a finished literal SQL string instead (for COPY, CREATE VIEW, logs or another tool), see "Finished literal SQL" under "Choosing an API" below.
+
+## Installation
+```
+pip install django-sql-compiler
+```
+
+No database driver is installed with the package and there are no extras: it uses the database connection your Django project already has, so the driver (for example psycopg2, psycopg 3 or mysqlclient) comes from your existing Django setup.
+
+Add `sql_compiler` to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...,
+    'sql_compiler'
+]
+```
+
+`sql_and_params()`, `compose()` and `fetch_rows()` work on plain Django querysets with no custom manager. `SQLCompilerManager` is only needed for the queryset methods described below (`qs.sql_and_params()` and the finished-literal-SQL property).
+
+## Filter with the ORM, finish in SQL.
+Any queryset works here; this example uses two filtered ones. The ORM builds and binds them, and the handwritten SQL joins the two sets, groups them, filters on the aggregate and ranks the result in one readable statement.
+
+Write the handwritten SQL in your database's dialect; this example's SQL is portable (PostgreSQL, SQLite, MySQL 8).
+
+Models and the result type (no custom manager needed):
+
+```python
+import dataclasses
+import datetime
+
+from django.db import models
+from sql_compiler import compose, fetch_rows
+
+
+class Customer(models.Model):
+    name = models.CharField(max_length=100)
+    region = models.CharField(max_length=20)
+
+
+class Order(models.Model):
+    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
+    placed = models.DateField()
+    amount_cents = models.IntegerField()
+
+
+@dataclasses.dataclass
+class RegionLeader:
+    name: str
+    orders: int
+    total_cents: int
+    place: int
+```
+
+Data:
+
+```python
+ada = Customer.objects.create(name='Ada', region='west')
+bo = Customer.objects.create(name='Bo', region='west')
+cy = Customer.objects.create(name='Cy', region='west')
+di = Customer.objects.create(name='Di', region='east')
+
+for customer, placed, amount_cents in [
+    (ada, datetime.date(2026, 3, 3), 4000),
+    (ada, datetime.date(2026, 3, 20), 3000),
+    (bo, datetime.date(2026, 3, 10), 9000),
+    (bo, datetime.date(2026, 2, 28), 500),
+    (cy, datetime.date(2026, 3, 15), 1500),
+    (di, datetime.date(2026, 3, 5), 50000),
+]:
+    Order.objects.create(customer=customer, placed=placed, amount_cents=amount_cents)
+```
+
+Query:
+
+```python
+region = 'west'                                                     # user input, bound
+start, end = datetime.date(2026, 3, 1), datetime.date(2026, 4, 1)   # user input, bound
+min_total_cents = 5000                                              # extra value in handwritten SQL, bound
+
+customers = Customer.objects.filter(region=region).values('id', 'name')
+orders = Order.objects.filter(placed__gte=start, placed__lt=end).values('customer_id', 'amount_cents')
+
+leaderboard = compose(
+    '''
+    WITH c AS (%(customers)s), o AS (%(orders)s)
+    SELECT c.name AS name,
+           COUNT(*) AS orders,
+           SUM(o.amount_cents) AS total_cents,
+           RANK() OVER (ORDER BY SUM(o.amount_cents) DESC) AS place
+    FROM c JOIN o ON o.customer_id = c.id
+    GROUP BY c.id, c.name
+    HAVING SUM(o.amount_cents) >= %(min_total_cents)s
+    ORDER BY place, name
+    ''',
+    customers=customers,
+    orders=orders,
+    min_total_cents=min_total_cents,
+)
+rows = fetch_rows(leaderboard, RegionLeader)   # runs on leaderboard.alias ('default' here)
+# [RegionLeader(name='Bo', orders=1, total_cents=9000, place=1),
+#  RegionLeader(name='Ada', orders=2, total_cents=7000, place=2)]
+```
+
+- `region`, `start`, `end` and `min_total_cents` are all params that the driver binds. Params follow placeholder order: the CTE params first, then the HAVING value. Params are adapted by the backend, so they are not printed here.
+- The handwritten SQL references only the CTE names, so no table names are needed.
+- Output columns are aliased explicitly in lowercase, because `fetch_rows` matches names exactly.
+- The template is trusted SQL written by you, and a literal `%` in it is written `%%`. The package does not validate SQL or make interpolated identifiers safe.
+
+## Choosing an API
+
+### SQL and params
+`sql_and_params(queryset)` returns the parameterized SQL (a `str` with Django's `%s` placeholders) and its params (a `tuple`) for any Django queryset. It compiles for the database the queryset runs on (`qs.db`, from `.using()` or your database routers), recompiles on every call, and leaves values in params for the driver to bind.
+
+```python
+from django.db import connections
+from sql_compiler import sql_and_params
+
+qs = Customer.objects.filter(region='west')
+sql, params = sql_and_params(qs)
+with connections[qs.db].cursor() as cursor:
+    cursor.execute('select count(*) from ({}) a'.format(sql), params)
+```
+
+Querysets from `SQLCompilerManager` also have `qs.sql_and_params()`, which returns the same pair. Anything that isn't a QuerySet (a manager, a RawQuerySet) raises `TypeError`.
+
+- The pair is for Django's cursor on that alias (`connections[qs.db].cursor()`), and for `qs.raw(sql, params)` (or `Customer.objects.raw(sql, params, using=qs.db)`), which runs on that alias, when the queryset selects the model's own instances (no `values()`, `values_list()` or aggregates). `Customer.objects.raw(sql, params)` without `using=` runs on the router's or default alias, not `qs.db`. The raw driver cursor is not supported (SQLite's, for example, uses `?`).
+- In hand-written SQL around it, keep user input in params and write a literal `%` as `%%`.
+- Empty querysets (`.none()`, `filter(id__in=[])`, an empty HAVING, an empty slice such as `qs[5:5]`) return SQL that matches no rows with the same columns.
+- Known limitation: an aggregate written as raw SQL (`RawSQL` or `extra(select=...)`, such as `COUNT(*)`) in a queryset with no aggregate Django recognizes has no GROUP BY, so its empty SQL returns one row instead of none.
+
+### Compose
+`compose(template, **slots)` fills the `%(name)s` slots of a hand-written SQL template with querysets, earlier `compose()` results and plain values. It returns one result that unpacks as `sql, params` for the querysets' shared database, with params in placeholder order and every value bound by the driver.
+
+```python
+from django.db import connections
+from sql_compiler import compose
+
+# start comes from the CTE example above
+result = compose(
+    'WITH recent AS (%(recent)s), big AS (%(big)s) '
+    'SELECT recent.id FROM recent JOIN big ON big.id = recent.id WHERE recent.amount_cents > %(min_cents)s',
+    recent=Order.objects.filter(placed__gte=start).values('id', 'amount_cents'),
+    big=Order.objects.filter(amount_cents__gte=1000).values('id'),
+    min_cents=50,
+)
+with connections[result.alias].cursor() as cursor:
+    cursor.execute(*result)
+    rows = cursor.fetchall()
+```
+
+- A QuerySet slot inserts its SQL as `sql_and_params` compiles it, a `compose()` result inserts its SQL (so results nest), and anything else becomes a `%s` param. Lists go to the driver unchanged.
+- Write a literal `%` as `%%`. It stays `%%` in the result, also when nested.
+- Embedded SQL is inserted as is, without added parentheses, so write them in the template.
+- All querysets and nested results must share one alias (`result.alias`), otherwise `ValueError`. At least one slot must hold a queryset or a `compose()` result.
+- Missing or unused slots, a positional `%s`, a lone `%` and any other `%(...)` form raise `ValueError` (with the position for `%` problems). A manager, a RawQuerySet, a Query, a Django expression such as `Subquery` and a `Q` raise `TypeError`.
+- A tuple (such as a `sql_and_params` pair) raises `TypeError`, because drivers bind tuples differently. Pass the queryset or a `compose()` result instead.
+- The template is trusted SQL: never build it from user input. Keep input in slots. A `%(name)s` inside a SQL string literal in the template is still a slot.
+- The result is for Django's cursor on `result.alias`, not the raw driver cursor. For `raw()`, use `Order.objects.raw(*result, using=result.alias)`.
+- Empty querysets embed SQL that matches no rows, with the same raw-SQL aggregate limitation as `sql_and_params`.
+
+### Typed rows
+`fetch_rows(result, row)` runs a `compose()` result and returns the rows as dataclass instances or dicts.
+
+```python
+from sql_compiler import fetch_rows
+
+# leaderboard: the compose() result from the CTE example above
+dicts = fetch_rows(leaderboard, dict)             # [{'name': 'Bo', 'orders': 1, 'total_cents': 9000, 'place': 1}, ...]
+leaders = fetch_rows(leaderboard, RegionLeader)   # [RegionLeader(...), ...]
+```
+
+- It runs the result once on `result.alias` through Django's cursor and returns a list (empty when there are no rows). It adds no transaction.
+- `row=dict` gives dicts with the columns in select order. `row=<dataclass type>` builds instances by keyword.
+- For a dataclass, the column names must match the constructor fields exactly and case-sensitively. Fields with a default or default_factory may be missing. `init=False` fields and ClassVar are not columns.
+- Values are passed through exactly as the driver returns them, with no conversion (SQLite returns decimals as float, MySQL returns the SUM of an integer as Decimal, so on MySQL the example's `total_cents` is a `Decimal`), so alias columns explicitly in lowercase.
+- Anything but a `compose()` result, or a row kind other than `dict` or a dataclass type, raises `TypeError` before any SQL runs.
+- A statement with no result set (it has already run), a result with no columns, duplicate column names, and extra columns or missing fields raise `ValueError`, checked before any row is built.
+
+### Finished literal SQL: executable_query
+`executable_query` gives you usable SQL from a QuerySet as one finished string, with every value escaped by the database driver. It is a property of `SQLCompilerQuerySet`, so the model needs `objects = SQLCompilerManager()`.
+
+Casting a queryset's `Query` object with `str(qs.query)` prints out what looks like valid SQL, but Django renders it for display: values are not escaped or quoted by the driver, so it is not actually valid SQL once there are dynamic components (such as filters from user input) in the `QuerySet`.
+
+Use it when a finished literal string is required: COPY, CREATE VIEW, logs, or passing the SQL to another tool. Prefer the parameterized APIs above whenever the SQL can be executed with params.
+
+```python
+from django.db import connections, models
+from sql_compiler import SQLCompilerManager
+
+
+class Customer(models.Model):
+    objects = SQLCompilerManager()
+    name = models.CharField(max_length=100)
+    region = models.CharField(max_length=20)
+
+
+qs = Customer.objects.filter(region='west')
+sql = qs.executable_query
+
+with connections[qs.db].cursor() as cursor:
+    cursor.execute('CREATE VIEW west_customers AS ' + sql)
+
+west = Customer.objects.raw('SELECT * FROM ({}) a'.format(sql), None, using=qs.db)
+```
+
+It works only on the ENGINEs and drivers listed under "Backend and version support"; other backends (for example SQLite) raise `NotImplementedError`. Empty querysets compile to zero-row SQL with the same columns.
+
+- Never supply a params argument when passing its output to `raw()` or `cursor.execute()`: `%` characters in inlined values (any `contains` or `startswith` lookup, or a value like `50% off`) can be interpreted as formatting placeholders. Call `cursor.execute(sql)` with no second argument. With `raw()`, pass `None` explicitly as params (`Customer.objects.raw(sql, None)`), because raw()'s default `()` counts as a params argument at the driver. Handwritten text wrapped around the output must not contain `%s` placeholders either.
+- Filter values appear in plaintext in the SQL, so treat it as sensitive data in logs and caches.
+- The property is cached per queryset instance (each `.filter()` returns a new queryset), so read it after the queryset is fully built.
+
+### Django's cursor or raw()
+- Use `connections[result.alias].cursor()` (or `connections[qs.db]`) with `cursor.execute(*result)` when you need arbitrary columns or aggregates, or `fetch_rows` to get rows as dicts or dataclasses.
+- Use `raw(sql, params)` only when the SQL returns the model's own rows, including its primary key.
+- Pass `using=` (`result.alias` or `qs.db`) to `raw()`: `Model.objects.raw` without it runs on the router's or default alias.
+- Never use the raw driver cursor.
+
+## Backend and version support
+The parameterized APIs (`sql_and_params`, `compose`, `fetch_rows`) compile through Django's own backend compiler and work on every Django backend. SQL you write around them can still depend on the backend's features (the CTE example needs CTEs and window functions).
+
+`executable_query` supports exactly these Django `ENGINE` values:
+
+- `django.db.backends.postgresql`
+- `django.db.backends.postgresql_psycopg2`: a legacy alias for the PostgreSQL backend that Django removed in Django 3.0. The package still accepts the ENGINE string and maps it to the same compiler.
+- `django_tenants.postgresql_backend` (django-tenants)
+- `django.db.backends.mysql` (via mysqlclient)
+
+PostgreSQL connections work with psycopg2 and with psycopg 3 (psycopg >=3.2), including Django's `server_side_binding` option. Other PostgreSQL drivers raise `NotImplementedError`.
+
+Python >=3.10 and Django >=4.2 are supported, subject to Django's own Python compatibility for each release. CI tests Django 4.2, 5.2 and 6.1 (on Python 3.10 to 3.14), plus live PostgreSQL 18 (psycopg2, psycopg 3 and psycopg 3 with server-side binding) and MySQL 8.4 jobs, and SQLite in every run. A job against Django's development branch runs for information only and is not a support promise.