diff options
Diffstat (limited to 'docs/topics/db')
| -rw-r--r-- | docs/topics/db/aggregation.txt | 8 | ||||
| -rw-r--r-- | docs/topics/db/index.txt | 2 | ||||
| -rw-r--r-- | docs/topics/db/managers.txt | 9 | ||||
| -rw-r--r-- | docs/topics/db/models.txt | 20 | ||||
| -rw-r--r-- | docs/topics/db/multi-db.txt | 4 | ||||
| -rw-r--r-- | docs/topics/db/optimization.txt | 41 | ||||
| -rw-r--r-- | docs/topics/db/queries.txt | 12 | ||||
| -rw-r--r-- | docs/topics/db/sql.txt | 12 | ||||
| -rw-r--r-- | docs/topics/db/transactions.txt | 4 |
9 files changed, 47 insertions, 65 deletions
diff --git a/docs/topics/db/aggregation.txt b/docs/topics/db/aggregation.txt index 087c1bf239..eb21021038 100644 --- a/docs/topics/db/aggregation.txt +++ b/docs/topics/db/aggregation.txt @@ -1,5 +1,3 @@ -.. _topics-db-aggregation: - =========== Aggregation =========== @@ -8,7 +6,7 @@ Aggregation .. currentmodule:: django.db.models -The topic guide on :ref:`Django's database-abstraction API <topics-db-queries>` +The topic guide on :doc:`Django's database-abstraction API </topics/db/queries>` described the way that you can use Django queries that create, retrieve, update and delete individual objects. However, sometimes you will need to retrieve values that are derived by summarizing or *aggregating* a @@ -353,7 +351,7 @@ without any harmful effects, since that is already playing a role in the query. This behavior is the same as that noted in the queryset documentation for -:ref:`distinct() <queryset-distinct>` and the general rule is the same: +:meth:`~django.db.models.QuerySet.distinct` and the general rule is the same: normally you won't want extra columns playing a part in the result, so clear out the ordering, or at least make sure it's restricted only to those fields you also select in a ``values()`` call. @@ -363,7 +361,7 @@ you also select in a ``values()`` call. for you. The main reason is consistency with ``distinct()`` and other places: Django **never** removes ordering constraints that you have specified (and we can't change those other methods' behavior, as that - would violate our :ref:`misc-api-stability` policy). + would violate our :doc:`/misc/api-stability` policy). Aggregating annotations ----------------------- diff --git a/docs/topics/db/index.txt b/docs/topics/db/index.txt index 3eb62b70ca..c49f158e64 100644 --- a/docs/topics/db/index.txt +++ b/docs/topics/db/index.txt @@ -1,5 +1,3 @@ -.. _topics-db-index: - Models and databases ==================== diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt index 123408b2bb..5ebe0b1b94 100644 --- a/docs/topics/db/managers.txt +++ b/docs/topics/db/managers.txt @@ -1,5 +1,3 @@ -.. _topics-db-managers: - ======== Managers ======== @@ -12,7 +10,7 @@ A ``Manager`` is the interface through which database query operations are provided to Django models. At least one ``Manager`` exists for every model in a Django application. -The way ``Manager`` classes work is documented in :ref:`topics-db-queries`; +The way ``Manager`` classes work is documented in :doc:`/topics/db/queries`; this document specifically touches on model options that customize ``Manager`` behavior. @@ -170,7 +168,8 @@ and ``Person.people.all()``, yielding predictable results. If you use custom ``Manager`` objects, take note that the first ``Manager`` Django encounters (in the order in which they're defined in the model) has a special status. Django interprets the first ``Manager`` defined in a class as -the "default" ``Manager``, and several parts of Django will use that ``Manager`` +the "default" ``Manager``, and several parts of Django +(including :djadmin:`dumpdata`) will use that ``Manager`` exclusively for that model. As a result, it's a good idea to be careful in your choice of default manager in order to avoid a situation where overriding ``get_query_set()`` results in an inability to retrieve objects you'd like to @@ -324,7 +323,7 @@ it will use :class:`django.db.models.Manager`. attribute only controlled the type of manager used for related field access, which is where the name came from. As it became clear the concept was more broadly useful, the name hasn't been changed. This is primarily - so that existing code will :ref:`continue to work <misc-api-stability>` in + so that existing code will :doc:`continue to work </misc/api-stability>` in future Django versions. Writing Correct Managers For Use In Automatic Manager Instances diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 6d7a7a4374..0ff34ea0e1 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -1,5 +1,3 @@ -.. _topics-db-models: - ====== Models ====== @@ -18,7 +16,7 @@ The basics: * Each attribute of the model represents a database field. * With all of this, Django gives you an automatically-generated - database-access API; see :ref:`topics-db-queries`. + database-access API; see :doc:`/topics/db/queries`. .. seealso:: @@ -64,7 +62,7 @@ Some technical notes: * The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL syntax, but it's worth noting Django uses SQL tailored to the database - backend specified in your :ref:`settings file <topics-settings>`. + backend specified in your :doc:`settings file </topics/settings>`. Using models ============ @@ -126,7 +124,7 @@ determine a few things: Django ships with dozens of built-in field types; you can find the complete list in the :ref:`model field reference <model-field-types>`. You can easily write your own fields if Django's built-in ones don't do the trick; see -:ref:`howto-custom-model-fields`. +:doc:`/howto/custom-model-fields`. Field options ------------- @@ -353,7 +351,7 @@ For example, if a ``Pizza`` has multiple ``Topping`` objects -- that is, a As with :class:`~django.db.models.ForeignKey`, you can also create :ref:`recursive relationships <recursive-relationships>` (an object with a -many-to-one relationship to itself) and :ref:`relationships to models not yet +many-to-many relationship to itself) and :ref:`relationships to models not yet defined <lazy-relationships>`; see :ref:`the model field reference <ref-manytomany>` for details. @@ -612,7 +610,7 @@ Custom field types If one of the existing model fields cannot be used to fit your purposes, or if you wish to take advantage of some less common database column types, you can create your own field class. Full coverage of creating your own fields is -provided in :ref:`howto-custom-model-fields`. +provided in :doc:`/howto/custom-model-fields`. .. _meta-options: @@ -634,8 +632,8 @@ human-readable singular and plural names (:attr:`~Options.verbose_name` and :attr:`~Options.verbose_name_plural`). None are required, and adding ``class Meta`` to a model is completely optional. -A complete list of all possible ``Meta`` options can be found in the :ref:`model -option reference <ref-models-options>`. +A complete list of all possible ``Meta`` options can be found in the :doc:`model +option reference </ref/models/options>`. .. _model-methods: @@ -684,7 +682,7 @@ properties`_. .. _Read more about properties: http://www.python.org/download/releases/2.2/descrintro/#property -The :ref:`model instance reference <ref-models-instances>` has a complete list +The :doc:`model instance reference </ref/models/instances>` has a complete list of :ref:`methods automatically given to each model <model-instance-methods>`. You can override most of these -- see `overriding predefined model methods`_, below -- but there are a couple that you'll almost always want to define: @@ -763,7 +761,7 @@ Executing custom SQL Another common pattern is writing custom SQL statements in model methods and module-level methods. For more details on using raw SQL, see the documentation -on :ref:`using raw SQL<topics-db-sql>`. +on :doc:`using raw SQL</topics/db/sql>`. .. _model-inheritance: diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt index e3f62ea71b..1a939b0e3a 100644 --- a/docs/topics/db/multi-db.txt +++ b/docs/topics/db/multi-db.txt @@ -1,5 +1,3 @@ -.. _topics-db-multi-db: - ================== Multiple databases ================== @@ -240,7 +238,7 @@ master/slave relationship between the databases ``master``, ``slave1`` and return False return None - class MasterSlaveRouter(object): + class MasterSlaveRouter(object): """A router that sets up a simple master/slave configuration""" def db_for_read(self, model, **hints): diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index 6063bc6c2a..baf8cfa268 100644 --- a/docs/topics/db/optimization.txt +++ b/docs/topics/db/optimization.txt @@ -1,11 +1,9 @@ -.. _topics-db-optimization: - ============================ Database access optimization ============================ Django's database layer provides various ways to help developers get the most -out of their databases. This documents gathers together links to the relevant +out of their databases. This document gathers together links to the relevant documentation, and adds various tips, organized under an number of headings that outline the steps to take when attempting to optimize your database usage. @@ -45,13 +43,13 @@ Use standard DB optimization techniques We will assume you have done the obvious things above. The rest of this document focuses on how to use Django in such a way that you are not doing unnecessary work. This document also does not address other optimization techniques that -apply to all expensive operations, such as :ref:`general purpose caching -<topics-cache>`. +apply to all expensive operations, such as :doc:`general purpose caching +</topics/cache>`. Understand QuerySets ==================== -Understanding :ref:`QuerySets <ref-models-querysets>` is vital to getting good +Understanding :doc:`QuerySets </ref/models/querysets>` is vital to getting good performance with simple code. In particular: Understand QuerySet evaluation @@ -101,36 +99,35 @@ Use ``iterator()`` When you have a lot of objects, the caching behaviour of the ``QuerySet`` can cause a large amount of memory to be used. In this case, -:ref:`QuerySet.iterator() <queryset-iterator>` may help. +:meth:`~django.db.models.QuerySet.iterator()` may help. Do database work in the database rather than in Python ====================================================== For instance: -* At the most basic level, use :ref:`filter and exclude <queryset-api>` to - filtering in the database to avoid loading data into your Python process, only - to throw much of it away. +* At the most basic level, use :ref:`filter and exclude <queryset-api>` to do + filtering in the database. * Use :ref:`F() object query expressions <query-expressions>` to do filtering against other fields within the same model. -* Use :ref:`annotate to do aggregation in the database <topics-db-aggregation>`. +* Use :doc:`annotate to do aggregation in the database </topics/db/aggregation>`. If these aren't enough to generate the SQL you need: Use ``QuerySet.extra()`` ------------------------ -A less portable but more powerful method is :ref:`QuerySet.extra() -<queryset-extra>`, which allows some SQL to be explicitly added to the query. -If that still isn't powerful enough: +A less portable but more powerful method is +:meth:`~django.db.models.QuerySet.extra()`, which allows some SQL to be +explicitly added to the query. If that still isn't powerful enough: Use raw SQL ----------- -Write your own :ref:`custom SQL to retrieve data or populate models -<topics-db-sql>`. Use ``django.db.connection.queries`` to find out what Django +Write your own :doc:`custom SQL to retrieve data or populate models +</topics/db/sql>`. Use ``django.db.connection.queries`` to find out what Django is writing for you and start from there. Retrieve everything at once if you know you will need it @@ -149,7 +146,7 @@ Understand :ref:`QuerySet.select_related() <select-related>` thoroughly, and use * in view code, -* and in :ref:`managers and default managers <topics-db-managers>` where +* and in :doc:`managers and default managers </topics/db/managers>` where appropriate. Be aware when your manager is and is not used; sometimes this is tricky so don't make assumptions. @@ -160,7 +157,7 @@ Use ``QuerySet.values()`` and ``values_list()`` ----------------------------------------------- When you just want a dict/list of values, and don't need ORM model objects, make -appropriate usage of :ref:`QuerySet.values() <queryset-values>`. +appropriate usage of :meth:`~django.db.models.QuerySet.values()`. These can be useful for replacing model objects in template code - as long as the dicts you supply have the same attributes as those used in the template, you are fine. @@ -168,7 +165,8 @@ are fine. Use ``QuerySet.defer()`` and ``only()`` --------------------------------------- -Use :ref:`defer() and only() <queryset-defer>` if there are database columns you +Use :meth:`~django.db.models.QuerySet.defer()` and +:meth:`~django.db.models.QuerySet.only()` if there are database columns you know that you won't need (or won't need in most cases) to avoid loading them. Note that if you *do* use them, the ORM will have to go and get them in a separate query, making this a pessimization if you use it inappropriately. @@ -243,10 +241,7 @@ individual, use a bulk SQL UPDATE statement, via :ref:`QuerySet.update() Note, however, that these bulk update methods cannot call the ``save()`` or ``delete()`` methods of individual instances, which means that any custom behaviour you have added for these methods will not be executed, including anything driven from the -normal database object :ref:`signals <ref-signals>`. - -Don't retrieve things you already have -====================================== +normal database object :doc:`signals </ref/signals>`. Use foreign key values directly ------------------------------- diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 981d727f4f..b0d053c2e9 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -1,15 +1,13 @@ -.. _topics-db-queries: - ============== Making queries ============== .. currentmodule:: django.db.models -Once you've created your :ref:`data models <topics-db-models>`, Django +Once you've created your :doc:`data models </topics/db/models>`, Django automatically gives you a database-abstraction API that lets you create, retrieve, update and delete objects. This document explains how to use this -API. Refer to the :ref:`data model reference <ref-models-index>` for full +API. Refer to the :doc:`data model reference </ref/models/index>` for full details of all the various model lookup options. Throughout this guide (and in the reference), we'll refer to the following @@ -825,6 +823,8 @@ a join with an ``F()`` object, a ``FieldError`` will be raised:: # THIS WILL RAISE A FieldError >>> Entry.objects.update(headline=F('blog__name')) +.. _topics-db-queries-related: + Related objects =============== @@ -937,7 +937,7 @@ be accessed from an instance:: In addition to the ``QuerySet`` methods defined in "Retrieving objects" above, the ``ForeignKey`` ``Manager`` has additional methods used to handle the set of related objects. A synopsis of each is below, and complete details can be found -in the :ref:`related objects reference <ref-models-relations>`. +in the :doc:`related objects reference </ref/models/relations>`. ``add(obj1, obj2, ...)`` Adds the specified model objects to the related object set. @@ -1067,7 +1067,7 @@ Falling back to raw SQL If you find yourself needing to write an SQL query that is too complex for Django's database-mapper to handle, you can fall back on writing SQL by hand. Django has a couple of options for writing raw SQL queries; see -:ref:`topics-db-sql`. +:doc:`/topics/db/sql`. Finally, it's important to note that the Django database layer is merely an interface to your database. You can access your database via other tools, diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt index f55a164373..9f2be7a2ef 100644 --- a/docs/topics/db/sql.txt +++ b/docs/topics/db/sql.txt @@ -1,12 +1,10 @@ -.. _topics-db-sql: - ========================== Performing raw SQL queries ========================== .. currentmodule:: django.db.models -When the :ref:`model query APIs <topics-db-queries>` don't go far enough, you +When the :doc:`model query APIs </topics/db/queries>` don't go far enough, you can fall back to writing raw SQL. Django gives you two ways of performing raw SQL queries: you can use :meth:`Manager.raw()` to `perform raw queries and return model instances`__, or you can avoid the model layer entirely and @@ -116,9 +114,9 @@ Fields may also be left out:: >>> people = Person.objects.raw('SELECT id, first_name FROM myapp_person') -The ``Person`` objects returned by this query will be :ref:`deferred -<queryset-defer>` model instances. This means that the fields that are omitted -from the query will be loaded on demand. For example:: +The ``Person`` objects returned by this query will be deferred model instances +(see :meth:`~django.db.models.QuerySet.defer()`). This means that the fields +that are omitted from the query will be loaded on demand. For example:: >>> for p in Person.objects.raw('SELECT id, first_name FROM myapp_person'): ... print p.first_name, # This will be retrieved by the original query @@ -269,7 +267,7 @@ Connections and cursors ----------------------- ``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_ -(except when it comes to :ref:`transaction handling <topics-db-transactions>`). +(except when it comes to :doc:`transaction handling </topics/db/transactions>`). If you're not familiar with the Python DB-API, note that the SQL statement in ``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters directly within the SQL. If you use this technique, the underlying database diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index fb6e3f8646..2d99c17a32 100644 --- a/docs/topics/db/transactions.txt +++ b/docs/topics/db/transactions.txt @@ -1,5 +1,3 @@ -.. _topics-db-transactions: - ============================== Managing database transactions ============================== @@ -306,7 +304,7 @@ Database-level autocommit .. versionadded:: 1.1 With PostgreSQL 8.2 or later, there is an advanced option to run PostgreSQL -with :ref:`database-level autocommit <ref-databases>`. If you use this option, +with :doc:`database-level autocommit </ref/databases>`. If you use this option, there is no constantly open transaction, so it is always possible to continue after catching an exception. For example:: |