{"id":21189310,"url":"https://github.com/uptick/django-pev","last_synced_at":"2026-03-03T02:03:33.192Z","repository":{"id":63686293,"uuid":"568327613","full_name":"uptick/django-pev","owner":"uptick","description":"Django Postgres Explain Visualizer (via https://explain.dalibo.com)","archived":false,"fork":false,"pushed_at":"2024-01-22T06:44:01.000Z","size":724,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-04-08T00:10:33.528Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uptick.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-20T06:59:55.000Z","updated_at":"2024-06-19T06:50:31.343Z","dependencies_parsed_at":"2024-06-19T06:50:21.496Z","dependency_job_id":"7b544aee-97fe-45d4-a951-58a9224b78c1","html_url":"https://github.com/uptick/django-pev","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptick%2Fdjango-pev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptick%2Fdjango-pev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptick%2Fdjango-pev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptick%2Fdjango-pev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uptick","download_url":"https://codeload.github.com/uptick/django-pev/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243646523,"owners_count":20324582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T18:51:42.169Z","updated_at":"2026-03-03T02:03:33.063Z","avatar_url":"https://github.com/uptick.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django Postgres Explain Visualizer (Django-PEV)\n\n[![PyPI version](https://badge.fury.io/py/django-pev.svg)](https://pypi.org/project/django-pev/)\n[![versions](https://img.shields.io/pypi/pyversions/django-pev.svg)](https://pypi.org/project/django-pev/)\n[![Lint](https://github.com/uptick/django-pev/actions/workflows/ci.yaml/badge.svg)](https://github.com/uptick/django-pev/actions/workflows/ci.yaml)\n\nThis tool captures sql queries and uploads the query plan to postgresql explain visualizer (PEV) by [dalibo](https://explain.dalibo.com/). This is especially helpful for debugging slow queries.\n\nThis tool also exports a graphical UI similar to [pghero](https://github.com/ankane/pghero) but is embedded within your django app.\n\n# Installation\n\n1. `pip install django-pev`\n\n2. Add to your urls\n\n```\n# urls.py\nfrom django.urls import include, path\n\nurlpatterns = [\n    # ....\n\n    path('django-pev/', include(('django_pev.urls', 'django_pev'), namespace='django_pev')),\n]\n```\n\n3. Add to your installed apps\n```\n# settings.py\n\nINSTALLED_APPS = [\n    # ...\n    \"django_pev\"\n]\n```\n\n\n# Usage\n\nWrap some code with the explain context manager. All sql queries are captured\nalongside a stacktrace (to locate where it was called). The slowest query is accessible via `.slowest`.\n\n```python\nimport django_pev\nfrom django.contrib.auth.models import User\n\nwith django_pev.explain() as e:\n    # Every SQL query is captured\n    list(User.objects.filter(email='test@test.com').all())\n\n# Rerun the slowest query with `EXPLAIN (ANALYZE, COSTS, VERBOSE, BUFFERS, FORMAT JSON)`\npev_response = e.slowest.visualize(\n    # By default the text of the query is not uploaded for security reasons\n    upload_query=True,\n    # Set to false if the query is slow and you want only an explain\n    analyze=True,\n    # Give a helpful title for the uploaded query plan\n    title=\"Measuring email filter\",\n)\nprint(pev_response.url)\n\n# View the postgres explain visualization\ne.slowest.visualize_in_browser()\n\n\n# Print the optimization prompt\ne.slowest.optimization_prompt()\n\n# Find N+1 queries\nfor query, count in e.nplusones.items():\n    print(f\"Found N+1 query executed {count} times:\")\n    print(query.sql)\n    print(f\"Stack trace:\\n{query.stack_trace}\")\n\n# View the stack trace of the slowest query\nprint(e.slowest.stacktrace)\n\n# Delete the plan hosted on https://explain.dalibo.com\npev_response.delete()\n```\n\nOptionally configure additional settings:\n```python\n# Replace the default test client used during explain with a custom class\nDJANGO_PEV_EXPLAIN_TEST_CLIENT = 'django.test.Client'\n\n```\n\n**How to debug a slow endpoint in production**\n\nIf you have access to `python manage.py shell` on the production server;\nyou can run the following code snippet to get an explain plan uploaded. In general this technique is all types of profiling.\n\n```python\nimport django_pev\n\nfrom django.contrib.auth.models import User\nfrom django.test import Client as TestClient\n\nclient = TestClient()\n# Authentication\nclient.force_login(User.objects.get(id=1))\nurl = \"/some_slow_url\"\n\nwith django_pev.explain() as e:\n    response = client.get(url)\n\nprint(e.slowest.visualize(title=f\"Fetching {url}\"))\n\n```\n\n# How do I\n## Create a release\nJust merge to main and let Release Please bot do its job. Merge the release branch to publish to pypi.\n\n# TODO\n- [ ] Add migration to ensure pg_stats_statement_info is correct\n\n\n# Disclaimer\n\nCredit goes to Pierre Giraud (@pgiraud) for PEV2 and Alex Tatiyants (@AlexTatiyants) for the original pev tool.\n\nIN NO EVENT SHALL DALIBO BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF DALIBO HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\nDALIBO SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN \"AS IS\" BASIS, AND DALIBO HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuptick%2Fdjango-pev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuptick%2Fdjango-pev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuptick%2Fdjango-pev/lists"}