django-query-builder

What it is and what it does

django-query-builder is a Django library that lets you construct and execute SQL queries programmatically, filling gaps where Django's ORM and .raw() fall short. It's designed for developers who need to build queries dynamically—where the structure itself changes based on runtime conditions—rather than writing static raw SQL strings. The library mirrors SQL syntax closely in its API, so function calls map directly to SQL keywords, making the query construction process more transparent than Django querysets but requiring more SQL familiarity than the ORM.

The package sits between Django's high-level querysets (simple, safe, but limited) and raw SQL strings (flexible but not dynamic). It requires Django 5.2–6.0, Python 3.10–3.14, and Postgres 14+, and depends only on Django itself. It's actively maintained, has no known security vulnerabilities, and carries a permissive MIT license.

Use it for:

• Build upsert (insert-or-update) operations that Django's ORM doesn't natively support
• Construct WHERE clauses, JOINs, or GROUP BY logic dynamically based on user input or application state
• Execute complex nested queries or subqueries that would be awkward to express in Django querysets
• Perform batch database operations with custom logic
• Generate reports or analytics queries with conditional aggregations

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Builds and executes complex SQL queries dynamically in Django applications for database operations that Django's ORM doesn't handle well.

Yes, if you work with Django and Postgres and regularly hit the limits of Django's ORM for complex or dynamic queries. The low install friction, active maintenance, permissive license, and zero known vulnerabilities make it a safe choice. Not necessary if your queries fit comfortably within Django querysets or if you're not using Postgres.

Install

django-query-builder on PyPI

pip install django-query-builder

uv add django-query-builder

poetry add django-query-builder

Installing django-query-builder

Before you install

Low friction install with a single Django dependency. Active maintenance as of 2026-07-07, last commit recent. Supports modern Python versions (3.10–3.14) and current Django releases (5.2–6.0).

License in practice

MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install django-query-builder

from django_query_builder import QueryBuilder

qb = QueryBuilder().select('*').from_('users').where('age > 21')
results = qb.execute()

Requires Postgres 14+; Django 5.2–6.0; Python 3.10–3.14. Not compatible with other database backends.

Verify before relying

• Scope of SQL operations supported beyond upsert (e.g., window functions, CTEs, complex joins)
• Performance characteristics on large result sets or deeply nested queries
• Postgres-only limitation: whether other databases are supported despite the requirement listing
• Specific example usage patterns and API surface for dynamic query construction

Package facts

Evidence: django_query_builder-4.0.0-py2.py3-none-any.whl

Keywords: django, database, query, sql, postgres, upsert

Tags

More Database packages