Added notes to README on `debugsqlshell` management command

1 files changed, 50 insertions, 0 deletions

diff --git a/README.rst b/README.rst
index 8d2d5a0..479d4c0 100644
--- a/README.rst
+++ b/README.rst
@@ -18,6 +18,11 @@ Currently, the following panels have been written and are working:
 - List of signals, their args and receivers
 - Logging output via Python's built-in logging module
 
+There is also one Django management command currently:
+
+- `debugsqlshell`: Outputs the SQL that gets executed as you work in the Python
+  interactive shell.  (See example below)
+
 If you have ideas for other panels please let us know.
 
 Installation
@@ -121,6 +126,51 @@ The debug toolbar has two settings that can be set in `settings.py`:
 	    'HIDE_DJANGO_SQL': False,
 	}
 
+`debugsqlshell`
+===============
+The following is sample output from running the `debugsqlshell` management
+command.  Each ORM call that results in a database query will be beautifully
+output in the shell::
+
+    $ ./manage.py debugsqlshell
+    Python 2.6.1 (r261:67515, Jul  7 2009, 23:51:51) 
+    [GCC 4.2.1 (Apple Inc. build 5646)] on darwin
+    Type "help", "copyright", "credits" or "license" for more information.
+    (InteractiveConsole)
+    >>> from page.models import Page
+    >>> ### Lookup and use resulting in an extra query...
+    >>> p = Page.objects.get(pk=1)
+    SELECT "page_page"."id",
+           "page_page"."number",
+           "page_page"."template_id",
+           "page_page"."description"
+    FROM "page_page"
+    WHERE "page_page"."id" = 1
+    
+    >>> print p.template.name
+    SELECT "page_template"."id",
+           "page_template"."name",
+           "page_template"."description"
+    FROM "page_template"
+    WHERE "page_template"."id" = 1
+    
+    Home
+    >>> ### Using select_related to avoid 2nd database call...
+    >>> p = Page.objects.select_related('template').get(pk=1)
+    SELECT "page_page"."id",
+           "page_page"."number",
+           "page_page"."template_id",
+           "page_page"."description",
+           "page_template"."id",
+           "page_template"."name",
+           "page_template"."description"
+    FROM "page_page"
+    INNER JOIN "page_template" ON ("page_page"."template_id" = "page_template"."id")
+    WHERE "page_page"."id" = 1
+    
+    >>> print p.template.name
+    Home
+
 TODOs and BUGS
 ==============
 See: http://github.com/robhudson/django-debug-toolbar/issues