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

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