When you access a field that's a ForeignKey, you'll get the related model object. Consider this example:

>>> b = Book.objects.get(id=50)
>>> b.publisher
<Publisher: Apress Publishing>
>>> b.publisher.website
u'http://www.apress.com/'

With ForeignKey fields, API access works in reverse, too, but it's slightly different due to the nonsymmetrical nature of the relationship. To get a list of books for a given publisher, use publisher.book_set.all(), like this:

>>> p = Publisher.objects.get(name='Apress Publishing')
>>> p.book_set.all()
[<Book: The Django Book>, <Book: Dive Into Python>, ...]

Behind the scenes, book_set is just a QuerySet (as covered in Chapter 5), and it can be filtered and sliced like any other QuerySet. Consider this example:

>>> p = Publisher.objects.get(name='Apress Publishing')
>>> p.book_set.filter(name__icontains='django')
[<Book: The Django Book>, <Book: Pro Django>]

The attribute name book_set is generated by appending the lowercase model name to _set.

Many-to-many values work like foreign-key values, except we deal with QuerySet values instead of model instances. For example, here's how to view the authors for a book:

>>> b = Book.objects.get(id=50)
>>> b.authors.all()
[<Author: Adrian Holovaty>, <Author: Jacob Kaplan-Moss>]
>>> b.authors.filter(first_name='Adrian')
[<Author: Adrian Holovaty>]
>>> b.authors.filter(first_name='Adam')
[]

It works in reverse, too. To view all of the books for an author, use author.book_set, like this:

>>> a = Author.objects.get(first_name='Adrian', last_name='Holovaty')
>>> a.book_set.all()
[<Book: The Django Book>, <Book: Adrian's Other Book>]

Here, as with ForeignKey fields, the attribute name book_set is generated by appending the lowercase model name to _set.

When adding a field to a table/model in a production setting, the trick is to take advantage of the fact that Django doesn't care if a table contains columns that aren't defined in the model. The strategy is to add the column in the database, and then update the Django model to include the new field.

However, there's a bit of a chicken-and-egg problem here, because in order to know how the new database column should be expressed in SQL, you need to look at the output of Django's manage.py sqlall command, which requires that the field exist in the model. (Note that you're not required to create your column with exactly the same SQL that Django would, but it's a good idea to do so, just to be sure everything's in sync.)

The solution to the chicken-and-egg problem is to use a development environment instead of making the changes on a production server. (You are using a testing/development environment, right?) The following are the detailed steps to take.

First, take these steps in the development environment (i.e., not on the production server):

Then, on the production server perform these steps:

For example, let's walk through what we'd do if we added a num_pages field to the Book model from Chapter 5. First we'd alter the model in our development environment to look like this:

class Book(models.Model):
    title = models.CharField(max_length=100)
    authors = models.ManyToManyField(Author)
    publisher = models.ForeignKey(Publisher)
    publication_date = models.DateField()
    num_pages = models.IntegerField(blank=True, null=True)

    def __unicode__(self):
        return self.title

Then we'd run the command manage.py sqlall books to see the CREATE TABLE statement. Depending on your database back-end, it would look something like this:

CREATE TABLE "books_book" (
    "id" serial NOT NULL PRIMARY KEY,
    "title" varchar(100) NOT NULL,
    "publisher_id" integer NOT NULL REFERENCES "books_publisher" ("id"),
    "publication_date" date NOT NULL,
    "num_pages" integer NULL
);

The new column is represented like this:

"num_pages" integer NULL

Next we'd start the database's interactive shell for our development database by typing psql (for PostgreSQL), and we'd execute the following statement:

ALTER TABLE books_book ADD COLUMN num_pages integer;

BEGIN;
ALTER TABLE books_book ADD COLUMN num_pages integer;
UPDATE books_book SET num_pages=0;
ALTER TABLE books_book ALTER COLUMN num_pages SET NOT NULL;
COMMIT;

After the ALTER TABLE statement, we'd verify that the change worked properly by starting the Python shell and running this code:

>>> from mysite.books.models import Book
>>> Book.objects.all()[:5]

If that code didn't cause errors, we'd switch to our production server and execute the ALTER TABLE statement on the production database. Then we'd update the model in the production environment and restart the Web server.

Removing a field from a model is a lot easier than adding one. Just follow these steps:

Be sure to perform the steps in this order. If you remove the column from your database first, Django will immediately begin raising errors.

Because many-to-many fields are different from normal fields, the removal process is different:

As in the previous section, be sure to perform the steps in this order.

Removing a model entirely is as easy as removing a field. Just follow these steps:

Note that you might need to remove any dependent tables from your database first—for instance, any tables that have foreign keys to books_book.

As in the previous sections, be sure to perform the steps in the order shown here.

Adding extra manager methods is the preferred way to add table-level functionality to your models. A table-level function is one that acts on multiple instances of models, as opposed to single instances. (For row-level functionality—i.e., functions that act on a single instance of a model object—use model methods, which are explained later in this chapter.)

For example, let's give our Book model a manager method title_count() that takes a keyword and returns the number of books that have a title containing that keyword. (This example is slightly contrived, but it demonstrates how managers work.)

# models.py

from django.db import models

# ... Author and Publisher models here ...

class BookManager(models.Manager):
    def title_count(self, keyword):
        return self.filter(title__icontains=keyword).count()

class Book(models.Model):
    title = models.CharField(max_length=100)
    authors = models.ManyToManyField(Author)
    publisher = models.ForeignKey(Publisher)
    publication_date = models.DateField()
    num_pages = models.IntegerField(blank=True, null=True)
    objects = BookManager()

    def __unicode__(self):
        return self.title

With this manager in place, we can now use the new methods:

>>> Book.objects.title_count('django')
4
>>> Book.objects.title_count('python')
18

Here are some notes about the code:

Why would we want to add a method such as title_count()? To encapsulate commonly executed queries so that we don't have to duplicate code.

A manager's base QuerySet returns all objects in the system. For example, Book.objects.all() returns all books in the book database.

You can override a manager's base QuerySet by overriding the Manager.get_query_set() method. get_query_set() should return a QuerySet with the properties you require.

For example, the following model has two managers—one that returns all objects, and one that returns only the books by Roald Dahl.

from django.db import models

# First, define the Manager subclass.
class DahlManager(models.Manager):
    def get_query_set(self):
        return super(DahlManager, self).get_query_set().filter(author='Roald Dahl')

# Then hook it into the Book model explicitly.
class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)
    # ...

    objects = models.Manager() # The default manager.
    dahl_objects = DahlManager() # The Dahl-specific manager.

With this sample model, Book.objects.all() will return all books in the database, but Book.dahl_objects.all() will return only the ones written by Roald Dahl. Note that we explicitly set objects to a vanilla Manager instance because if we hadn't, the only available manager would be dahl_objects.

Of course, because get_query_set() returns a QuerySet object, you can use filter(), exclude(), and all the other QuerySet methods on it. So these statements are all legal:

Book.dahl_objects.all()
Book.dahl_objects.filter(title='Matilda')
Book.dahl_objects.count()

This example points out another interesting technique: using multiple managers on the same model. You can attach as many Manager() instances to a model as you'd like. This is an easy way to define common filters for your models.

Consider this example:

class MaleManager(models.Manager):
    def get_query_set(self):
        return super(MaleManager, self).get_query_set().filter(sex='M')

class FemaleManager(models.Manager):
    def get_query_set(self):
        return super(FemaleManager, self).get_query_set().filter(sex='F')

class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    sex = models.CharField(max_length=1, choices=(('M', 'Male'), ('F', 'Female')))
    people = models.Manager()
    men = MaleManager()
    women = FemaleManager()

This example allows you to request Person.men.all(), Person.women.all(), 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 this first Manager defined in a class as the default Manager, and several parts of Django (though not the admin application) will use that default 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 work with.