Ticket #9206: 9206-r10628-raw-sql-docs.diff

docs/topics/db/models.txt

@@ -752 +752 @@
 --------------------
 
 Another common pattern is writing custom SQL statements in model methods and
-module-level methods. The object :class:`django.db.connection
-<django.db.backends.DatabaseWrapper>` represents the current database
-connection. To use it, call :meth:`connection.cursor()
-<django.db.backends.DatabaseWrapper.cursor>` to get a cursor object. Then, call
-``cursor.execute(sql, [params])`` to execute the SQL and
-:meth:`cursor.fetchone() <django.db.backends.CursorWrapper.fetchone>` or
-:meth:`cursor.fetchall() <django.db.backends.CursorWrapper.fetchall>` to return
-the resulting rows. For example::
+module-level methods. See :ref:`raw SQL <topic-db-sql>`.
 
-    def my_custom_sql(self):
-        from django.db import connection
-        cursor = connection.cursor()
-        cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])
-        row = cursor.fetchone()
-        return row
-
-:class:`connection <django.db.backends.DatabaseWrapper>` and :class:`cursor
-<django.db.backends.CursorWrapper>` mostly implement the standard Python
-DB-API -- see :pep:`249` -- with the addition of Django's :ref:`transaction
-handling <topics-db-transactions>`. If you're not familiar with the Python
-DB-API, note that the SQL statement in :meth:`cursor.execute()
-<django.db.backends.CursorWrapper.execute>` uses placeholders, ``"%s"``, rather
-than adding parameters directly within the SQL. If you use this technique, the
-underlying database library will automatically add quotes and escaping to your
-parameter(s) as necessary. (Also note that Django expects the ``"%s"``
-placeholder, *not* the ``"?"`` placeholder, which is used by the SQLite Python
-bindings. This is for the sake of consistency and sanity.)
-
-A final note: If all you want to do is a custom ``WHERE`` clause, you can use
-the :meth:`~QuerySet.extra` lookup method, which lets you add custom SQL to a
-query.
-
 .. _model-inheritance:
 
 Model inheritance

docs/topics/db/transactions.txt

@@ -10 +10 @@
 Django's default transaction behavior
 =====================================
 
-Django's default behavior is to commit automatically when any built-in,
-data-altering model function is called. For example, if you call
-``model.save()`` or ``model.delete()``, the change will be committed
-immediately.
+Django's default behavior is to run with an open transaction which it
+commits automatically when any built-in, data-altering model function is
+called. For example, if you call ``model.save()`` or ``model.delete()``, the
+change will be committed immediately.
 
 This is much like the auto-commit setting for most databases. As soon as you
 perform an action that needs to write to the database, Django produces the
@@ -165 +165 @@
 handle transactions as explained in this document.
 
 .. _information on MySQL transactions: http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html
+
+Transactions and savepoints in PostgreSQL
+=========================================
+
+If you're using PostgreSQL 8, then be aware that once PostgreSQL raises an
+exception, all subsequent SQL in the same transaction fails with the error
+"current transaction is aborted, queries ignored until end of transaction
+block". Whilst simple use of save() is unlikely to raise an exception in
+PostgreSQL, there are many more advanced usage patterns which might: e.g.
+save with unique fields, save with force_insert/force_update, custom SQL.
+
+In any of these cases, you can wrap the command which may throw
+IntegrityError inside savepoints, which will then allow subsequent commands
+to proceed. Example::
+
+    try:
+      sid = transaction.savepoint()
+      x.save()
+      transaction.savepoint_commit(sid)
+    except IntegrityError:
+      transaction.savepoint_rollback(sid)
+      raise
+
+Transactions and autocommit in PostgreSQL
+=========================================
+
+By default, Django starts a transaction when a database connection is first
+used and regularly commits, as above. The PostgreSQL backends normally
+operate the same as any other Django backend in this respect, but can
+additionally support database-level :ref:`autocommit mode <ref-databases>`
+with no constantly open transaction.

docs/topics/db/sql.txt

@@ -5 +5 @@
 
 Feel free to write custom SQL statements in custom model methods and
 module-level methods. The object ``django.db.connection`` represents the
-current database connection. To use it, call ``connection.cursor()`` to get a
+current database connection, and ``django.db.transaction`` represents the
+current database transaction. To use it, call ``connection.cursor()`` to get a
 cursor object. Then, call ``cursor.execute(sql, [params])`` to execute the SQL
 and ``cursor.fetchone()`` or ``cursor.fetchall()`` to return the resulting
-rows. Example::
+rows. ``transaction.commit_unless_managed()`` is needed after
+data-changing operations but not after pure selects, etc. Example::
 
     def my_custom_sql(self):
-        from django.db import connection
+        from django.db import connection, transaction
         cursor = connection.cursor()
         cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])
         row = cursor.fetchone()
+        cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [self.baz])
+        transaction.commit_unless_managed()
         return row
 
 ``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_