Debian Codegraph @

docs/topics/db/instrumentation.txt

raw
1 ========================
2 Database instrumentation
3 ========================
4
5 To help you understand and control the queries issued by your code, Django
6 provides a hook for installing wrapper functions around the execution of
7 database queries. For example, wrappers can count queries, measure query
8 duration, log queries, or even prevent query execution (e.g. to make sure that
9 no queries are issued while rendering a template with prefetched data).
10
11 The wrappers are modeled after :doc:`middleware </topics/http/middleware>` --
12 they are callables which take another callable as one of their arguments. They
13 call that callable to invoke the (possibly wrapped) database query, and they
14 can do what they want around that call. They are, however, created and
15 installed by user code, and so don't need a separate factory like middleware do.
16
17 Installing a wrapper is done in a context manager -- so the wrappers are
18 temporary and specific to some flow in your code.
19
20 As mentioned above, an example of a wrapper is a query execution blocker. It
21 could look like this::
22
23 def blocker(*args):
24 raise Exception("No database access allowed here.")
25
26 And it would be used in a view to block queries from the template like so::
27
28 from django.db import connection
29 from django.shortcuts import render
30
31
32 def my_view(request):
33 context = {...} # Code to generate context with all data.
34 template_name = ...
35 with connection.execute_wrapper(blocker):
36 return render(request, template_name, context)
37
38 The parameters sent to the wrappers are:
39
40 * ``execute`` -- a callable, which should be invoked with the rest of the
41 parameters in order to execute the query.
42
43 * ``sql`` -- a ``str``, the SQL query to be sent to the database.
44
45 * ``params`` -- a list/tuple of parameter values for the SQL command, or a
46 list/tuple of lists/tuples if the wrapped call is ``executemany()``.
47
48 * ``many`` -- a ``bool`` indicating whether the ultimately invoked call is
49 ``execute()`` or ``executemany()`` (and whether ``params`` is expected to be
50 a sequence of values, or a sequence of sequences of values).
51
52 * ``context`` -- a dictionary with further data about the context of
53 invocation. This includes the connection and cursor.
54
55 Using the parameters, a slightly more complex version of the blocker could
56 include the connection name in the error message::
57
58 def blocker(execute, sql, params, many, context):
59 alias = context["connection"].alias
60 raise Exception("Access to database '{}' blocked here".format(alias))
61
62 For a more complete example, a query logger could look like this::
63
64 import time
65
66
67 class QueryLogger:
68 def __init__(self):
69 self.queries = []
70
71 def __call__(self, execute, sql, params, many, context):
72 current_query = {"sql": sql, "params": params, "many": many}
73 start = time.monotonic()
74 try:
75 result = execute(sql, params, many, context)
76 except Exception as e:
77 current_query["status"] = "error"
78 current_query["exception"] = e
79 raise
80 else:
81 current_query["status"] = "ok"
82 return result
83 finally:
84 duration = time.monotonic() - start
85 current_query["duration"] = duration
86 self.queries.append(current_query)
87
88 To use this, you would create a logger object and install it as a wrapper::
89
90 from django.db import connection
91
92 ql = QueryLogger()
93 with connection.execute_wrapper(ql):
94 do_queries()
95 # Now we can print the log.
96 print(ql.queries)
97
98 .. currentmodule:: django.db.backends.base.DatabaseWrapper
99
100 ``connection.execute_wrapper()``
101 --------------------------------
102
103 .. method:: execute_wrapper(wrapper)
104
105 Returns a context manager which, when entered, installs a wrapper around
106 database query executions, and when exited, removes the wrapper. The wrapper is
107 installed on the thread-local connection object.
108
109 ``wrapper`` is a callable taking five arguments. It is called for every query
110 execution in the scope of the context manager, with arguments ``execute``,
111 ``sql``, ``params``, ``many``, and ``context`` as described above. It's
112 expected to call ``execute(sql, params, many, context)`` and return the return
113 value of that call.