8 files changed, 90 insertions, 54 deletions
diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt
index 1cf4ddb729..7f0ea3799d 100644
--- a/docs/howto/custom-model-fields.txt
+++ b/docs/howto/custom-model-fields.txt
@@ -219,9 +219,9 @@ parameters:
 * :attr:`~django.db.models.Field.choices`
 * :attr:`~django.db.models.Field.help_text`
 * :attr:`~django.db.models.Field.db_column`
-* :attr:`~django.db.models.Field.db_tablespace`: Currently only used with
-  the Oracle backend and only for index creation. You can usually ignore
-  this option.
+* :attr:`~django.db.models.Field.db_tablespace`: Only for index creation, if the
+  backend supports :doc:`tablespaces </topics/db/tablespaces>`. You can usually
+  ignore this option.
 * :attr:`~django.db.models.Field.auto_created`: True if the field was
   automatically created, as for the `OneToOneField` used by model
   inheritance. For advanced use only.
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 9a83e059e5..9ea0fe72cc 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -646,49 +646,6 @@ The ``RETURNING INTO`` clause can be disabled by setting the
 In this case, the Oracle backend will use a separate ``SELECT`` query to
 retrieve AutoField values.
 
-Tablespace options
-------------------
-
-A common paradigm for optimizing performance in Oracle-based systems is the
-use of `tablespaces`_ to organize disk layout. The Oracle backend supports
-this use case by adding ``db_tablespace`` options to the ``Meta`` and
-``Field`` classes.  (When you use a backend that lacks support for tablespaces,
-Django ignores these options.)
-
-.. _`tablespaces`: http://en.wikipedia.org/wiki/Tablespace
-
-A tablespace can be specified for the table(s) generated by a model by
-supplying the ``db_tablespace`` option inside the model's ``class Meta``.
-Additionally, you can pass the ``db_tablespace`` option to a ``Field``
-constructor to specify an alternate tablespace for the ``Field``'s column
-index. If no index would be created for the column, the ``db_tablespace``
-option is ignored::
-
-    class TablespaceExample(models.Model):
-        name = models.CharField(max_length=30, db_index=True, db_tablespace="indexes")
-        data = models.CharField(max_length=255, db_index=True)
-        edges = models.ManyToManyField(to="self", db_tablespace="indexes")
-
-        class Meta:
-            db_tablespace = "tables"
-
-In this example, the tables generated by the ``TablespaceExample`` model
-(i.e., the model table and the many-to-many table) would be stored in the
-``tables`` tablespace. The index for the name field and the indexes on the
-many-to-many table would be stored in the ``indexes`` tablespace. The ``data``
-field would also generate an index, but no tablespace for it is specified, so
-it would be stored in the model tablespace ``tables`` by default.
-
-Use the :setting:`DEFAULT_TABLESPACE` and :setting:`DEFAULT_INDEX_TABLESPACE`
-settings to specify default values for the db_tablespace options.
-These are useful for setting a tablespace for the built-in Django apps and
-other applications whose code you cannot control.
-
-Django does not create the tablespaces for you. Please refer to `Oracle's
-documentation`_ for details on creating and managing tablespaces.
-
-.. _`Oracle's documentation`: http://download.oracle.com/docs/cd/B19306_01/server.102/b14200/statements_7003.htm#SQLRF01403
-
 Naming issues
 -------------
 
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 3ae35f0dc2..f3a4ef4f77 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -178,10 +178,11 @@ If ``True``, djadmin:`django-admin.py sqlindexes <sqlindexes>` will output a
 
 .. attribute:: Field.db_tablespace
 
-The name of the database tablespace to use for this field's index, if this field
-is indexed. The default is the project's :setting:`DEFAULT_INDEX_TABLESPACE`
-setting, if set, or the :attr:`~Field.db_tablespace` of the model, if any. If
-the backend doesn't support tablespaces, this option is ignored.
+The name of the :doc:`database tablespace </topics/db/tablespaces>` to use for
+this field's index, if this field is indexed. The default is the project's
+:setting:`DEFAULT_INDEX_TABLESPACE` setting, if set, or the
+:attr:`~Options.db_tablespace` of the model, if any. If the backend doesn't
+support tablespaces for indexes, this option is ignored.
 
 ``default``
 -----------
diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
index 14446b69b4..4ae105af92 100644
--- a/docs/ref/models/options.txt
+++ b/docs/ref/models/options.txt
@@ -73,8 +73,10 @@ Django quotes column and table names behind the scenes.
 
 .. attribute:: Options.db_tablespace
 
-    The name of the database tablespace to use for the model. If the backend
-    doesn't support tablespaces, this option is ignored.
+    The name of the :doc:`database tablespace </topics/db/tablespaces>` to use
+    for this model. The default is the project's :setting:`DEFAULT_TABLESPACE`
+    setting, if set. If the backend doesn't support tablespaces, this option is
+    ignored.
 
 ``get_latest_by``
 -----------------
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 0669750565..4ff5d4d068 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -864,7 +864,7 @@ DEFAULT_INDEX_TABLESPACE
 Default: ``''`` (Empty string)
 
 Default tablespace to use for indexes on fields that don't specify
-one, if the backend supports it.
+one, if the backend supports it (see :doc:`/topics/db/tablespaces`).
 
 .. setting:: DEFAULT_TABLESPACE
 
@@ -874,7 +874,7 @@ DEFAULT_TABLESPACE
 Default: ``''`` (Empty string)
 
 Default tablespace to use for models that don't specify one, if the
-backend supports it.
+backend supports it (see :doc:`/topics/db/tablespaces`).
 
 .. setting:: DISALLOWED_USER_AGENTS
 
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index a035f44567..3e364fbe23 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -405,6 +405,8 @@ Django 1.4 also includes several smaller improvements worth noting:
   code are slightly emphasized. This change makes it easier to scan a stacktrace
   for issues in user code.
 
+* :doc:`Tablespace support </topics/db/tablespaces>` in PostgreSQL.
+
 * Customizable names for :meth:`~django.template.Library.simple_tag`.
 
 * In the documentation, a helpful :doc:`security overview </topics/security>`
diff --git a/docs/topics/db/index.txt b/docs/topics/db/index.txt
index 24a6202564..0e0fc8adb6 100644
--- a/docs/topics/db/index.txt
+++ b/docs/topics/db/index.txt
@@ -17,4 +17,5 @@ model maps to a single database table.
    sql
    transactions
    multi-db
+   tablespaces
    optimization
diff --git a/docs/topics/db/tablespaces.txt b/docs/topics/db/tablespaces.txt
new file mode 100644
index 0000000000..7fcd5588e7
--- /dev/null
+++ b/docs/topics/db/tablespaces.txt
@@ -0,0 +1,73 @@
+===========
+Tablespaces
+===========
+
+A common paradigm for optimizing performance in database systems is the use of
+`tablespaces`_ to organize disk layout.
+
+.. _`tablespaces`: http://en.wikipedia.org/wiki/Tablespace
+
+.. warning::
+    Django does not create the tablespaces for you. Please refer to your
+    database engine's documentation for details on creating and managing
+    tablespaces.
+
+
+Declaring tablespaces for tables
+--------------------------------
+
+A tablespace can be specified for the table generated by a model by supplying
+the :attr:`~django.db.models.Options.db_tablespace` option inside the model's
+``class Meta``. This option also affects tables automatically created for
+:class:`~django.db.models.ManyToManyField`\ s in the model.
+
+You can use the :setting:`DEFAULT_TABLESPACE` setting to specify a default value
+for :attr:`~django.db.models.Options.db_tablespace`. This is useful for setting
+a tablespace for the built-in Django apps and other applications whose code you
+cannot control.
+
+Declaring tablespaces for indexes
+---------------------------------
+
+You can pass the :attr:`~django.db.models.Field.db_tablespace` option to a
+``Field`` constructor to specify an alternate tablespace for the ``Field``'s
+column index. If no index would be created for the column, the option is
+ignored.
+
+You can use the :setting:`DEFAULT_INDEX_TABLESPACE` setting to specify
+a default value for :attr:`~django.db.models.Field.db_tablespace`.
+
+If :attr:`~django.db.models.Field.db_tablespace` isn't specified and you didn't
+set :setting:`DEFAULT_INDEX_TABLESPACE`, the index is created in the same
+tablespace as the tables.
+
+An example
+----------
+
+.. code-block:: python
+
+    class TablespaceExample(models.Model):
+        name = models.CharField(max_length=30, db_index=True, db_tablespace="indexes")
+        data = models.CharField(max_length=255, db_index=True)
+        edges = models.ManyToManyField(to="self", db_tablespace="indexes")
+
+        class Meta:
+            db_tablespace = "tables"
+
+In this example, the tables generated by the ``TablespaceExample`` model (i.e.
+the model table and the many-to-many table) would be stored in the ``tables``
+tablespace. The index for the name field and the indexes on the many-to-many
+table would be stored in the ``indexes`` tablespace. The ``data`` field would
+also generate an index, but no tablespace for it is specified, so it would be
+stored in the model tablespace ``tables`` by default.
+
+Database support
+----------------
+
+PostgreSQL and Oracle support tablespaces. SQLite and MySQL don't.
+
+When you use a backend that lacks support for tablespaces, Django ignores all
+tablespace-related options.
+
+.. versionchanged:: 1.4
+    Since Django 1.4, the PostgreSQL backend supports tablespaces.