#9206: Improve documentation on raw SQL queries
-----------------------------------------------------------------------+----
Reporter: Richard Davies <[EMAIL PROTECTED]> | Owner:
nobody
Status: new |
Milestone:
Component: Documentation |
Version: 1.0
Resolution: |
Keywords:
Stage: Accepted |
Has_patch: 1
Needs_docs: 0 |
Needs_tests: 0
Needs_better_patch: 0 |
-----------------------------------------------------------------------+----
Changes (by mtredinnick):
* needs_better_patch: => 0
* stage: Unreviewed => Accepted
* needs_tests: => 0
* needs_docs: => 0
Comment:
Looks good. A few small changes I would suggest to clear up some problems:
1. Django does not have a mode called "auto-commit". The document says
it's ''similar'' to a database's auto-commit behaviour, but that means
it's not identical and so we shouldn't use that term to describe Django's
mode. It will lead to even more confusion than when people don't read the
current text. Now, if they do read the text, they'll end up with the wrong
term. So let's find a better way of describing that mode (e.g "when Django
isn't configured for manual transaction management (via the XYZ setting)"
or something similar).
2. I think this change should also be clear that things like
`commit_unless_managed()` are only needed for data-changing operations.
Select queries for example (one of the more common uses of custom SQL)
don't require a call to that method and people don't have to go around
adding it everywhere just for that case. It currently sounds all very
intrusive, but it's really just for one particular style of query, so make
that clear.
3. The documentation of savepoints should go in the transaction document,
not in the raw SQL section. It's transaction related, after all. That
documentation should be written something along the lines of "if you want
your application to work transparently with PostgreSQL 8.x ..." and
probably also include a note that savepoints don't work on PostgreSQL 7.x,
so if your data changing transaction fails there, you're screwed and have
to just roll back.
--
Ticket URL: <http://code.djangoproject.com/ticket/9206#comment:1>
Django <http://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
