2021-06-30 10:45:10 +00:00
|
|
|
import json
|
2017-09-10 14:34:18 +00:00
|
|
|
import unittest
|
2021-07-05 06:17:31 +00:00
|
|
|
import xml.etree.ElementTree
|
2017-09-10 14:34:18 +00:00
|
|
|
|
|
|
|
from django.db import NotSupportedError, connection, transaction
|
|
|
|
from django.db.models import Count
|
2019-09-07 17:28:19 +00:00
|
|
|
from django.test import TestCase, skipIfDBFeature, skipUnlessDBFeature
|
2017-09-10 14:34:18 +00:00
|
|
|
from django.test.utils import CaptureQueriesContext
|
|
|
|
|
|
|
|
from .models import Tag
|
|
|
|
|
|
|
|
|
|
|
|
@skipUnlessDBFeature("supports_explaining_query_execution")
|
|
|
|
class ExplainTests(TestCase):
|
|
|
|
def test_basic(self):
|
|
|
|
querysets = [
|
|
|
|
Tag.objects.filter(name="test"),
|
|
|
|
Tag.objects.filter(name="test").select_related("parent"),
|
|
|
|
Tag.objects.filter(name="test").prefetch_related("children"),
|
|
|
|
Tag.objects.filter(name="test").annotate(Count("children")),
|
|
|
|
Tag.objects.filter(name="test").values_list("name"),
|
|
|
|
]
|
2024-08-20 14:29:35 +00:00
|
|
|
if connection.features.supports_select_union:
|
|
|
|
querysets.append(
|
|
|
|
Tag.objects.order_by().union(Tag.objects.order_by().filter(name="test"))
|
|
|
|
)
|
2022-04-13 08:17:14 +00:00
|
|
|
if connection.features.has_select_for_update:
|
|
|
|
querysets.append(Tag.objects.select_for_update().filter(name="test"))
|
2017-09-10 14:34:18 +00:00
|
|
|
supported_formats = connection.features.supported_explain_formats
|
|
|
|
all_formats = (
|
|
|
|
(None,)
|
|
|
|
+ tuple(supported_formats)
|
|
|
|
+ tuple(f.lower() for f in supported_formats)
|
2022-02-03 19:24:19 +00:00
|
|
|
)
|
2017-09-10 14:34:18 +00:00
|
|
|
for idx, queryset in enumerate(querysets):
|
|
|
|
for format in all_formats:
|
|
|
|
with self.subTest(format=format, queryset=idx):
|
2022-04-14 05:53:15 +00:00
|
|
|
with self.assertNumQueries(1) as captured_queries:
|
|
|
|
result = queryset.explain(format=format)
|
2017-09-10 14:34:18 +00:00
|
|
|
self.assertTrue(
|
2022-04-14 05:53:15 +00:00
|
|
|
captured_queries[0]["sql"].startswith(
|
|
|
|
connection.ops.explain_prefix
|
2017-09-10 14:34:18 +00:00
|
|
|
)
|
2022-02-03 19:24:19 +00:00
|
|
|
)
|
2017-09-10 14:34:18 +00:00
|
|
|
self.assertIsInstance(result, str)
|
|
|
|
self.assertTrue(result)
|
2022-04-19 06:24:24 +00:00
|
|
|
if not format:
|
|
|
|
continue
|
|
|
|
if format.lower() == "xml":
|
2021-07-05 06:17:31 +00:00
|
|
|
try:
|
|
|
|
xml.etree.ElementTree.fromstring(result)
|
|
|
|
except xml.etree.ElementTree.ParseError as e:
|
|
|
|
self.fail(
|
|
|
|
f"QuerySet.explain() result is not valid XML: {e}"
|
|
|
|
)
|
2022-04-19 06:24:24 +00:00
|
|
|
elif format.lower() == "json":
|
2021-06-30 10:45:10 +00:00
|
|
|
try:
|
|
|
|
json.loads(result)
|
|
|
|
except json.JSONDecodeError as e:
|
|
|
|
self.fail(
|
|
|
|
f"QuerySet.explain() result is not valid JSON: {e}"
|
|
|
|
)
|
2017-09-10 14:34:18 +00:00
|
|
|
|
|
|
|
def test_unknown_options(self):
|
2022-04-01 11:48:47 +00:00
|
|
|
with self.assertRaisesMessage(ValueError, "Unknown options: TEST, TEST2"):
|
|
|
|
Tag.objects.explain(**{"TEST": 1, "TEST2": 1})
|
2017-09-10 14:34:18 +00:00
|
|
|
|
|
|
|
def test_unknown_format(self):
|
|
|
|
msg = "DOES NOT EXIST is not a recognized format."
|
|
|
|
if connection.features.supported_explain_formats:
|
|
|
|
msg += " Allowed formats: %s" % ", ".join(
|
|
|
|
sorted(connection.features.supported_explain_formats)
|
2022-02-03 19:24:19 +00:00
|
|
|
)
|
2022-04-14 00:17:00 +00:00
|
|
|
else:
|
|
|
|
msg += f" {connection.display_name} does not support any formats."
|
2017-09-10 14:34:18 +00:00
|
|
|
with self.assertRaisesMessage(ValueError, msg):
|
2022-02-22 09:29:38 +00:00
|
|
|
Tag.objects.explain(format="does not exist")
|
2017-09-10 14:34:18 +00:00
|
|
|
|
|
|
|
@unittest.skipUnless(connection.vendor == "postgresql", "PostgreSQL specific")
|
|
|
|
def test_postgres_options(self):
|
|
|
|
qs = Tag.objects.filter(name="test")
|
|
|
|
test_options = [
|
|
|
|
{"COSTS": False, "BUFFERS": True, "ANALYZE": True},
|
|
|
|
{"costs": False, "buffers": True, "analyze": True},
|
|
|
|
{"verbose": True, "timing": True, "analyze": True},
|
|
|
|
{"verbose": False, "timing": False, "analyze": True},
|
2021-01-19 11:25:20 +00:00
|
|
|
{"summary": True},
|
2022-05-19 07:26:48 +00:00
|
|
|
{"settings": True},
|
2023-09-20 11:45:51 +00:00
|
|
|
{"analyze": True, "wal": True},
|
2017-09-10 14:34:18 +00:00
|
|
|
]
|
2023-09-26 10:05:26 +00:00
|
|
|
if connection.features.is_postgresql_16:
|
|
|
|
test_options.append({"generic_plan": True})
|
2017-09-10 14:34:18 +00:00
|
|
|
for options in test_options:
|
|
|
|
with self.subTest(**options), transaction.atomic():
|
|
|
|
with CaptureQueriesContext(connection) as captured_queries:
|
|
|
|
qs.explain(format="text", **options)
|
|
|
|
self.assertEqual(len(captured_queries), 1)
|
|
|
|
for name, value in options.items():
|
|
|
|
option = "{} {}".format(name.upper(), "true" if value else "false")
|
|
|
|
self.assertIn(option, captured_queries[0]["sql"])
|
|
|
|
|
2024-08-20 14:29:35 +00:00
|
|
|
@skipUnlessDBFeature("supports_select_union")
|
2024-03-13 18:10:54 +00:00
|
|
|
def test_multi_page_text_explain(self):
|
|
|
|
if "TEXT" not in connection.features.supported_explain_formats:
|
|
|
|
self.skipTest("This backend does not support TEXT format.")
|
|
|
|
|
|
|
|
base_qs = Tag.objects.order_by()
|
|
|
|
qs = base_qs.filter(name="test").union(*[base_qs for _ in range(100)])
|
|
|
|
result = qs.explain(format="text")
|
|
|
|
self.assertGreaterEqual(result.count("\n"), 100)
|
|
|
|
|
2022-04-01 11:48:47 +00:00
|
|
|
def test_option_sql_injection(self):
|
|
|
|
qs = Tag.objects.filter(name="test")
|
|
|
|
options = {"SUMMARY true) SELECT 1; --": True}
|
|
|
|
msg = "Invalid option name: 'SUMMARY true) SELECT 1; --'"
|
|
|
|
with self.assertRaisesMessage(ValueError, msg):
|
|
|
|
qs.explain(**options)
|
|
|
|
|
|
|
|
def test_invalid_option_names(self):
|
|
|
|
qs = Tag.objects.filter(name="test")
|
|
|
|
tests = [
|
|
|
|
'opt"ion',
|
|
|
|
"o'ption",
|
|
|
|
"op`tion",
|
|
|
|
"opti on",
|
|
|
|
"option--",
|
|
|
|
"optio\tn",
|
|
|
|
"o\nption",
|
|
|
|
"option;",
|
|
|
|
"你 好",
|
|
|
|
# [] are used by MSSQL.
|
|
|
|
"option[",
|
|
|
|
"option]",
|
|
|
|
]
|
|
|
|
for invalid_option in tests:
|
|
|
|
with self.subTest(invalid_option):
|
|
|
|
msg = f"Invalid option name: {invalid_option!r}"
|
|
|
|
with self.assertRaisesMessage(ValueError, msg):
|
|
|
|
qs.explain(**{invalid_option: True})
|
|
|
|
|
2017-09-10 14:34:18 +00:00
|
|
|
@unittest.skipUnless(connection.vendor == "mysql", "MySQL specific")
|
|
|
|
def test_mysql_text_to_traditional(self):
|
2019-10-21 16:32:56 +00:00
|
|
|
# Ensure these cached properties are initialized to prevent queries for
|
|
|
|
# the MariaDB or MySQL version during the QuerySet evaluation.
|
|
|
|
connection.features.supported_explain_formats
|
2017-09-10 14:34:18 +00:00
|
|
|
with CaptureQueriesContext(connection) as captured_queries:
|
|
|
|
Tag.objects.filter(name="test").explain(format="text")
|
|
|
|
self.assertEqual(len(captured_queries), 1)
|
|
|
|
self.assertIn("FORMAT=TRADITIONAL", captured_queries[0]["sql"])
|
|
|
|
|
2019-10-21 16:34:19 +00:00
|
|
|
@unittest.skipUnless(
|
|
|
|
connection.vendor == "mysql", "MariaDB and MySQL >= 8.0.18 specific."
|
|
|
|
)
|
|
|
|
def test_mysql_analyze(self):
|
|
|
|
qs = Tag.objects.filter(name="test")
|
|
|
|
with CaptureQueriesContext(connection) as captured_queries:
|
|
|
|
qs.explain(analyze=True)
|
|
|
|
self.assertEqual(len(captured_queries), 1)
|
|
|
|
prefix = "ANALYZE " if connection.mysql_is_mariadb else "EXPLAIN ANALYZE "
|
|
|
|
self.assertTrue(captured_queries[0]["sql"].startswith(prefix))
|
|
|
|
with CaptureQueriesContext(connection) as captured_queries:
|
|
|
|
qs.explain(analyze=True, format="JSON")
|
|
|
|
self.assertEqual(len(captured_queries), 1)
|
|
|
|
if connection.mysql_is_mariadb:
|
|
|
|
self.assertIn("FORMAT=JSON", captured_queries[0]["sql"])
|
|
|
|
else:
|
|
|
|
self.assertNotIn("FORMAT=JSON", captured_queries[0]["sql"])
|
|
|
|
|
2017-09-10 14:34:18 +00:00
|
|
|
|
|
|
|
@skipIfDBFeature("supports_explaining_query_execution")
|
|
|
|
class ExplainUnsupportedTests(TestCase):
|
|
|
|
def test_message(self):
|
|
|
|
msg = "This backend does not support explaining query execution."
|
|
|
|
with self.assertRaisesMessage(NotSupportedError, msg):
|
|
|
|
Tag.objects.filter(name="test").explain()
|