Welcome to Django Prepared Query documentation!¶
SQL prepared statement support for Django ORM.
Installation¶
django_prepared_query works only with Python 3 and Django 1.11+. Currently it supports only PostgreSQL and MySQL. It can be installed with pip:
$ pip install django_prepared_query
Usage¶
For using prepared statements you must replace model standard manager with PreparedManager.
from django_prepared_query import PreparedManager
class Book(Model):
objects = PreparedManger()
...
PreparedManager has 2 additional methods: prepare and execute that are equivalent to SQL prepare and execute commands.
qs = Book.objects.prepare()
result = qs.execute()
Note
After prepare you can call only execute method, other methods raises OperationOnPreparedStatement exception. Calling execute before prepare raises QueryNotPrepared exception.
It’s possible to add dynamic parameters to query using BindParam expression. It takes parameter name and not required field type for situations when it can’t automatically detect type. Parameter name will be used in execute method. Passing incorrect parameter name raises IncorrectBindParameter exception.
from django_prepared_query import BindParam
qs = Book.objects.filter(name=BindParam('book_name')).prepare()
result = qs.execute(book_name='Harry Potter')
Also you can use different built-in lookups except isnull that raises NotSupportedLookup exception.
from django_prepared_query import BindParam
qs = Book.objects.filter(name__startswith=BindParam('book_name')).prepare()
result = qs.execute(book_name='Harry Potter')
result = qs.execute_iterator(book_name='Harry Potter') # Returns iterator
Before running execute query django_prepared_query validates input parameter types, ValidationError will be raised in cases when parameter type isn’t matched.
BindParam can be used in queryset slicing as well.
qs = Book.objects.all()[BindParam('start'):BindParam('end')].prepare()
result = qs.execute(start=0, end=20)
Also you can create prepared quires with in lookup. For this you should use BindArray expression instead of BindParam. BindArray accepts additional parameter size, so you can use only arrays with specified size or smaller. In cases when you pass smaller array to BindArray expression, it will fill remaining positions with NULL that will pe optimized by database.
from django_prepared_query import BindArray
qs = Book.objects.filter(id__in=BindArray('ids', 10)).prepare()
result = qs.execute(ids=list(range(10)))
Contributing¶
To contribute to django_prepared_query create a fork on GitHub. Clone your fork, make some changes, and submit a pull request. Issues
Issues¶
Use the GitHub issue tracker to submit bugs, issues, and feature requests.