From b50a35a669d3e458f714a36b0d6f48d5d7be4fd0 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Mon, 8 Mar 2010 03:19:26 +0000
Subject: [PATCH] Fixed #12941 -- Added documentation for the connections
 dictionary. Thanks to atlithorn@gmail.com for the report, and Alex Gaynor for
 the original text.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@12709 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/topics/db/multi-db.txt | 12 ++++++++++++
 docs/topics/db/sql.txt      | 13 +++++++++++--
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt
index ac09191cbd..0b8e90832b 100644
--- a/docs/topics/db/multi-db.txt
+++ b/docs/topics/db/multi-db.txt
@@ -535,3 +535,15 @@ This example sets up two admin sites. On the first site, the
 objects have an tabular inline showing books published by that
 publisher. The second site exposes just publishers, without the
 inlines.
+
+Using raw cursors with multiple databases
+=========================================
+
+If you are using more than one database you can use
+``django.db.connections`` to obtain the connection (and cursor) for a
+specific database. ``django.db.connections`` is a dictionary-like
+object that allows you to retrieve a specific connection using it's
+alias::
+
+    from django.db import connections
+    cursor = connections['my_db_alias'].cursor()
diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt
index 5ec048528a..f55a164373 100644
--- a/docs/topics/db/sql.txt
+++ b/docs/topics/db/sql.txt
@@ -196,8 +196,8 @@ In these cases, you can always access the database directly, routing around
 the model layer entirely.
 
 The object ``django.db.connection`` represents the
-current database connection, and ``django.db.transaction`` represents the
-current database transaction. To use the database connection, call
+default database connection, and ``django.db.transaction`` represents the
+default database transaction. To use the database connection, 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. After performing a data
@@ -220,6 +220,15 @@ is required. For example::
 
         return row
 
+If you are using more than one database you can use
+``django.db.connections`` to obtain the connection (and cursor) for a
+specific database. ``django.db.connections`` is a dictionary-like
+object that allows you to retrieve a specific connection using it's
+alias::
+
+    from django.db import connections
+    cursor = connections['my_db_alias'].cursor()
+
 .. _transactions-and-raw-sql:
 
 Transactions and raw SQL