Fixed #12941 -- Added documentation for the connections dictionary. Thanks to atlithorn@gmail.com for the report, and Alex Gaynor for the original text.

freakboy3742 · freakboy3742 · commit b50a35a669d3 · 2010-03-08T03:19:26.000Z
git-svn-id: http://code.djangoproject.com/svn/django/trunk@12709 bcc190cf-cafb-0310-a4f2-bffc1f526a37
diff --git 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
@@ -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
