The Django Book

The Dumb Way to Do Database Queries in Views

在视图中进行数�库查询的笨方法

Just as Chapter 3 detailed a dumb way to produce output within a view (by hard-coding the text directly within the view), theres a dumb way to retrieve data from a database in a view. Its simple: just use any existing Python library to execute an SQL query and do something with the results.

正如第三章详细介�的那个在视图中输出 HTML 的笨方法（通过在视图里对文本直接硬编�HTML），在视图中也有笨方法�以从数�库中获�数�。很简�：用现有的任何 Python 类库执行一� SQL 查询并对结果进行一些处�。

In this example view, we use the MySQLdb library (available at http://www.djangoproject.com/r/python-mysql/) to connect to a MySQL database, retrieve some records, and feed them to a template for display as a Web page:

在本例的视图中，我们使用了 MySQLdb 类库（�以从 http://www.djangoproject.com/r/python-mysql/ 获得）�连接 MySQL 数�库，�回一些记录，将它们�供给模�以显示一个网页：

from django.shortcuts import render_to_response
import MySQLdb

def book_list(request):
    db = MySQLdb.connect(user='me', db='mydb', passwd='secret', host='localhost')
    cursor = db.cursor()
    cursor.execute('SELECT name FROM books ORDER BY name')
    names = [row[0] for row in cursor.fetchall()]
    db.close()
    return render_to_response('book_list.html', {'names': names})

This approach works, but some problems should jump out at you immediately:

这个方法�用，但很快一些问题将出现在你��：

• Were hard-coding the database connection parameters. Ideally, these parameters would be stored in the Django configuration.

• 我们将数æ�®åº“连接å�‚数硬行编ç �于代ç �之中。ç�†æƒ³æƒ…况下，这些å�‚数应当ä¿�存在 Django é…�置中。

• Were having to write a fair bit of boilerplate code: creating a connection, creating a cursor, executing a statement, and closing the connection. Ideally, all wed have to do is specify which results we wanted.

• 我们ä¸�å¾—ä¸�é‡�å¤�å�Œæ ·çš„代ç �：创建数æ�®åº“连接ã€�创建数æ�®åº“游标ã€�执行æŸ�个语å�¥ã€�然å�Žå…³é—­æ•°æ�®åº“。ç�†æƒ³æƒ…况下，我们所需è¦�应该å�ªæ˜¯æŒ‡å®šæ‰€éœ€çš„结果。

• It ties us to MySQL. If, down the road, we switch from MySQL to PostgreSQL, well have to use a different database adapter (e.g., psycopg rather than MySQLdb ), alter the connection parameters, and depending on the nature of the SQL statement possibly rewrite the SQL. Ideally, the database server were using would be abstracted, so that a database server change could be made in a single place.

• 它把我们栓死在 MySQL 之上。如果过段时间，我们è¦�从 MySQL æ�¢åˆ° PostgreSQL，就ä¸�å¾—ä¸�使用ä¸�å�Œçš„æ•°æ�®åº“适é…�器（例如 psycopg 而ä¸�是 MySQLdb ），改å�˜è¿žæŽ¥å�‚数，根æ�® SQL 语å�¥çš„类型å�¯èƒ½è¿˜è¦�修改SQL 。ç�†æƒ³æƒ…况下，应对所使用的数æ�®åº“æœ�务器进行抽象，这样一æ�¥å�ªåœ¨ä¸€å¤„修改å�³å�¯å�˜æ�¢æ•°æ�®åº“æœ�务器。

As you might expect, Djangos database layer aims to solve these problems. Heres a sneak preview of how the previous view can be rewritten using Djangos database API:

正如你所期待的，Django数�库层正是致力于解决这些问题。以下���示了如何使用 Django 数�库 API �写之�那个视图。

from django.shortcuts import render_to_response
from mysite.books.models import Book

def book_list(request):
    books = Book.objects.order_by('name')
    return render_to_response('book_list.html', {'books': books})

Well explain this code a little later in the chapter. For now, just get a feel for how it looks.

我们将在本章��的地方解释这段代�。目�而言，仅需对它有个大致的认识。

The MTV Development Pattern

MTV 开�模�

Before we delve into any more code, lets take a moment to consider the overall design of a database-driven Django Web application.

在钻研更多代�之�，让我们先花点时间考虑下 Django 数�驱动 Web 应用的总体设计。

As we mentioned in previous chapters, Django is designed to encourage loose coupling and strict separation between pieces of an application. If you follow this philosophy, its easy to make changes to one particular piece of the application without affecting the other pieces. In view functions, for instance, we discussed the importance of separating the business logic from the presentation logic by using a template system. With the database layer, were applying that same philosophy to data access logic.

我们在��章节�到过，Django 的设计鼓励�耦��对应用程�中��部分的严格分割。�循这个�念的�，�想修改应用的�部分而�影�其它部分就比较容易了。在视图函数中，我们已�讨论了通过模�系统把业务逻辑和表现逻辑分隔开的��性。在数�库层中，我们对数�访问逻辑也应用了�样的�念。

Those three pieces together data access logic, business logic, and presentation logic comprise a concept thats sometimes called the Model-View-Controller (MVC) pattern of software architecture. In this pattern, Model refers to the data access layer, View refers to the part of the system that selects what to display and how to display it, and Controller refers to the part of the system that decides which view to use, depending on user input, accessing the model as needed.

把数�存�逻辑�业务逻辑和表现逻辑组�在一起的概念有时被称为软件架构的 Model-View-Controller (MVC)模�。在这个模�中， Model 代表数�存�层，View 代表的是系统中选择显示什么和怎么显示的部分，Controller 指的是系统中根�用户输入并视需�访问模型，以决定使用哪个视图的那部分。

Why the Acronym?

为什么用缩写？

The goal of explicitly defining patterns such as MVC is mostly to streamline communication among developers. Instead of having to tell your coworkers, Lets make an abstraction of the data access, then lets have a separate layer that handles data display, and lets put a layer in the middle that regulates this, you can take advantage of a shared vocabulary and say, Lets use the MVC pattern here.

� MVC 这样的明确定义模�的主�用于改善开�人员之间的沟通。与其告诉�事：“让我们对数�存�进行抽象，用�独一层负责数�显示，然�在中间放置一层�进行控制�，还�如利用通用的�汇告诉他们：“让我们在这里使用 MVC 模���。

Django follows this MVC pattern closely enough that it can be called an MVC framework. Heres roughly how the M, V, and C break down in Django:

Django 紧紧地�循这� MVC 模�，�以称得上是一� MVC 框架。以下是 Django 中 M�V 和 C �自的�义：

• M , the data-access portion, is handled by Djangos database layer, which is described in this chapter.

• M ，数æ�®å­˜å�–部分，由djangoæ•°æ�®åº“层处ç�†ï¼Œæœ¬ç« è¦�讲述的内容。

• V , the portion that selects which data to display and how to display it, is handled by views and templates.

• V ，选择显示哪些数æ�®è¦�å�Šæ€Žæ ·æ˜¾ç¤ºçš„部分，由视图和模æ�¿å¤„ç�†ã€‚

• C , the portion that delegates to a view depending on user input, is handled by the framework itself by following your URLconf and calling the appropriate Python function for the given URL.

• C ，根æ�®ç”¨æˆ·è¾“入委派视图的部分，由 Django 框架通过按照 URLconf 设置，对给定 URL 调用å�ˆé€‚çš„ python 函数æ�¥è‡ªè¡Œå¤„ç�†ã€‚

Because the C is handled by the framework itself and most of the excitement in Django happens in models, templates, and views, Django has been referred to as an MTV framework . In the MTV development pattern,

由于 C 由框架自行处�，而 Django 里更关注的是模型（Model）�模�(Template)和视图（Views），Django 也被称为 MTV 框架 。在 MTV 开�模�中：

• M stands for Model, the data access layer. This layer contains anything and everything about the data: how to access it, how to validate it, which behaviors it has, and the relationships between the data.

• M 代表模型（Model），å�³æ•°æ�®å­˜å�–层。该层处ç�†ä¸Žæ•°æ�®ç›¸å…³çš„所有事务：如何存å�–ã€�如何确认有效性ã€�包å�«å“ªäº›è¡Œä¸ºä»¥å�Šæ•°æ�®ä¹‹é—´çš„关系等。

• T stands for Template, the presentation layer. This layer contains presentation-related decisions: how something should be displayed on a Web page or other type of document.

• T 代表模æ�¿(Template)，å�³è¡¨çŽ°å±‚。该层处ç�†ä¸Žè¡¨çŽ°ç›¸å…³çš„决定：如何在页é�¢æˆ–其他类型文档中进行显示。

• V stands for View, the business logic layer. This layer contains the logic that access the model and defers to the appropriate template(s). You can think of it as the bridge between models and templates.

• V 代表视图（View），å�³ä¸šåŠ¡é€»è¾‘层。该层包å�«å­˜å�–模型å�Šè°ƒå�–æ�°å½“模æ�¿çš„相关逻辑。你å�¯ä»¥æŠŠå®ƒçœ‹ä½œæ¨¡åž‹ä¸Žæ¨¡æ�¿ä¹‹é—´çš„æ¡¥æ¢�。

If youre familiar with other MVC Web-development frameworks, such as Ruby on Rails, you may consider Django views to be the controllers and Django templates to be the views. This is an unfortunate confusion brought about by differing interpretations of MVC. In Djangos interpretation of MVC, the view describes the data that gets presented to the user; its not necessarily just how the data looks, but which data is presented. In contrast, Ruby on Rails and similar frameworks suggest that the controllers job includes deciding which data gets presented to the user, whereas the view is strictly how the data looks, not which data is presented.

如果你熟悉其它的 MVC Web开�框架，比方说 Ruby on Rails，你�能会认为 Django 视图是控制器，而 Django 模�是视图。很�幸，这是对 MVC ��诠释所引起的错误认识。在 Django 对 MVC 的诠释中，视图用��述�展现给用户的数�；�是数�看起� 怎么样 ,而是�呈现 哪些 数�。相比之下，Ruby on Rails �一些�类框架�倡控制器负责决定�用户展现哪些数�，而视图则仅决定 如何 展现数�，而�是展现 哪些 数�。

Neither interpretation is more correct than the other. The important thing is to understand the underlying concepts.

两�诠释中没有哪个更加正确一些。��的是��解底层概念。

Configuring the Database

数�库�置

With all of that philosophy in mind, lets start exploring Djangos database layer. First, we need to take care of some initial configuration: we need to tell Django which database server to use and how to connect to it.

记�这些�念之�，让我们�开始 Django 数�库层的探索。首先，我们需��定一些�始化设置：我们必须告诉 Django �用哪个数�库�务器�如何连接上它。

Well assume youve set up a database server, activated it, and created a database within it (e.g., using a CREATE DATABASE statement). SQLite is a special case; in that case, theres no database to create, because SQLite uses standalone files on the filesystem to store its data.

我们将�定你已�完�了数�库�务器的安装和激活，并且已�在其中创建了数�库（例如，用 CREATE DATABASE 语�）。SQLite 数�库有点特别，用它的��需�创建数�库，因为 SQLite 使用文件系统中的�个文件��存数�。

As with TEMPLATE_DIRS in the previous chapter, database configuration lives in the Django settings file, called settings.py by default. Edit that file and look for the database settings:

象��章节�到的 TEMPLATE_DIRS 一样，数�库�置也是在Django的�置文件里，缺� 是 settings.py 。编辑打开这个文件并查找数�库�置：

DATABASE_ENGINE = ''
DATABASE_NAME = ''
DATABASE_USER = ''
DATABASE_PASSWORD = ''
DATABASE_HOST = ''
DATABASE_PORT = ''

Heres a rundown of each setting.

�置纲�如下。

DATABASE_ENGINE tells Django which database engine to use. If youre using a database with Django, DATABASE_ENGINE must be set to one of the strings shown in Table 5-1.

DATABASE_ENGINE 告诉Django使用哪个数�库引擎。如果你在 Django 中使用数�库， DATABASE_ENGINE 必须是 Table 5-1 中所列出的值。

Table 5-1. Database Engine Settings

Setting	Database	Required Adapter
postgresql	PostgreSQL	psycopg version 1.x, http://www.djangoproject.com/r/python-pgsql/1/.
postgresql_psycopg2	PostgreSQL	psycopg version 2.x, http://www.djangoproject.com/r/python-pgsql/.
mysql	MySQL	MySQLdb , http://www.djangoproject.com/r/python-mysql/.
sqlite3	SQLite	No adapter needed if using Python 2.5+. Otherwise, pysqlite , http://www.djangoproject.com/r/python-sqlite/.
ado_mssql	Microsoft SQL Server	adodbapi version 2.0.1+, http://www.djangoproject.com/r/python-ado/.
oracle	Oracle	cx_Oracle , http://www.djangoproject.com/r/python-oracle/.

表 5-1. 数�库引擎设置

设置	数�库	适�器
postgresql	PostgreSQL	psycopg 版本 1.x, http://www.djangoproject.com/r/python-pgsql/1/.
postgresql_psycopg2	PostgreSQL	psycopg 版本 2.x, http://www.djangoproject.com/r/python-pgsql/.
mysql	MySQL	MySQLdb , http://www.djangoproject.com/r/python-mysql/.
sqlite3	SQLite	Python 2.5+ 内建。 其他, pysqlite , http://www.djangoproject.com/r/python-sqlite/.
ado_mssql	Microsoft SQL Server	adodbapi 版本 2.0.1+, http://www.djangoproject.com/r/python-ado/.
oracle	Oracle	cx_Oracle , http://www.djangoproject.com/r/python-oracle/.

Note that for whichever database back-end you use, youll need to download and install the appropriate database adapter. Each one is available for free on the Web; just follow the links in the Required Adapter column in Table 5-1.

�注�的是无论选择使用哪个数�库�务器，都必须下载和安装对应的数�库适�器。访问表 5-1 中“所需适�器�一�中的链接，�通过互�网�费获�这些适�器。

DATABASE_NAME tells Django the name of your database. If youre using SQLite, specify the full filesystem path to the database file on your filesystem (e.g., '/home/django/mydata.db' ).

DATABASE_NAME 将数�库�称告知 Django 。如果使用 SQLite，请对数�库文件指定完整的文件系统路径。（例如 '/home/django/mydata.db' ）。

DATABASE_USER tells Django which username to use when connecting to your database. If youre using SQLite, leave this blank.

DATABASE_USER 告诉 Django 用哪个用户连接数�库。如果用SQLite，空白��。

DATABASE_PASSWORD tells Django which password to use when connecting to your database. If youre using SQLite or have an empty password, leave this blank.

DATABASE_PASSWORD 告诉Django连接用户的密�。SQLite 用空密���。

DATABASE_HOST tells Django which host to use when connecting to your database. If your database is on the same computer as your Django installation (i.e., localhost), leave this blank. If youre using SQLite, leave this blank.

DATABASE_HOST 告诉 Django 连接哪一�主机的数�库�务器。如果数�库与 Django 安装于�一�计算机（�本机），�将此项�留空白。使用 SQLite ，也��留空白。

MySQL is a special case here. If this value starts with a forward slash ('/' ) and youre using MySQL, MySQL will connect via a Unix socket to the specified socket, for example:

此处的 MySQL 是一个特例。如果使用的是 MySQL 且该项设置值由斜�（ '/' ）开头，MySQL 将通过 Unix socket �连接指定的套接字，例如：

DATABASE_HOST = '/var/run/mysql'

If youre using MySQL and this value doesnt start with a forward slash, then this value is assumed to be the host.

如果用 MySQL 而该项设置的值 �是 以正斜线开始的，系统将�定该项值是主机�。

DATABASE_PORT tells Django which port to use when connecting to your database. If youre using SQLite, leave this blank. Otherwise, if you leave this blank, the underlying database adapter will use whichever port is default for your given database server. In most cases, the default port is fine, so you can leave this blank.

DATABASE_PORT 告诉 Django 连接数�库时使用哪个端�。如果用SQLite，空白��。其他情况下，如果将该项设置�留空白，底层数�库适�器将会连接所给定数�库�务器的缺�端�。在多数情况下，使用缺�端�就�以了，因此你�以将该项设置�留空白。

Once youve entered those settings, test your configuration. First, from within the mysite project directory you created in Chapter 2, run the command python manage.py shell .

输入完设置�，测试一下�置情况。首先，转到在第二章创建的 mysite 项目目录，�行 python manage.py shell 命令。

Youll notice this starts a Python interactive interpreter. Looks can be deceiving, though! Theres an important difference between running the command python manage.py shell within your Django project directory and the more generic python . The latter is the basic Python shell, but the former tells Django which settings file to use before it starts the shell. This is a key requirement for doing database queries: Django needs to know which settings file to use in order to get your database connection information.

你会看到该命令�动了一个 Python 交互界�。�行命令 python manage.py shell �动的交互界�和 标准的 python 交互界�有很大的区别。看起�都是基本的python外壳（shell）， 但是�者告诉Django使用哪个�置文件�动。这对数�库�作�说很关键：Django需� 知�使用哪个�置文件�获得数�库连接信�。

Behind the scenes, python manage.py shell simply assumes that your settings file is in the same directory as manage.py . There are other ways to tell Django which settings module to use, but these subtleties will be covered later. For now, use python manage.py shell whenever you need to drop into the Python interpreter to do Django-specific tinkering.

python manage.py shell �定你的�置文件就在和 manage.py 一样的目录中。 以�将会讲到使用其他的方��告诉Django使用其他的�置文件。

Once youve entered the shell, type these commands to test your database configuration:

输入下�这些命令�测试你的数�库�置：

>>> from django.db import connection
>>> cursor = connection.cursor()

If nothing happens, then your database is configured properly. Otherwise, check the error message for clues about whats wrong. Table 5-2 shows some common errors.

如果没有显示什么错误信�，那么你的数�库�置是正确的。�则，你就得 查看错误信��纠正错误。表 5-2 是一些常�错误。

Your First App

你的第一个应用程�

Now that youve verified the connection is working, its time to create a Django app a bundle of Django code, including models and views, that lives together in a single Python package and represents a full Django application.

你现在已�确认数�库连接正常工作了，让我们�创建一个 Django app ，开始编�模型和视图。这些文件放置在�一个包中并且形�为一个完整的Django应用程�。

Its worth explaining the terminology here, because this tends to trip up beginners. Wed already created a project , in Chapter 2, so whats the difference between a project and an app ? The difference is that of configuration vs. code:

在这里�先解释一些术语，�学者�能会混淆它们。在第二章我们已�创建了 project , 那么 project 和 app 之间到底有什么��呢？ 它们的区别就是一个是�置�一个是代�：

A project is an instance of a certain set of Django apps, plus the configuration for those apps.

一个project包�很多个Django app以�对它们的�置。

Technically, the only requirement of a project is that it supplies a settings file, which defines the database connection information, the list of installed apps, the TEMPLATE_DIRS , and so forth.

技术上，project的作用是�供�置文件，比方说哪里定义数�库连接信�, 安装的app列表， TEMPLATE_DIRS ，等等。

An app is a portable set of Django functionality, usually including models and views, that lives together in a single Python package.

一个app是一套Django功能的集�，通常包括模型和视图，按Python的包结构的方�存在。

For example, Django comes with a number of apps, such as a commenting system and an automatic admin interface. A key thing to note about these apps is that theyre portable and reusable across multiple projects.

例如，Django本身内建有一些app，例如注释系统和自动管�界�。 app的一个关键点是它们是很容易移�到其他project和被多个project�用。

There are very few hard-and-fast rules about how you fit your Django code into this scheme; its flexible. If youre building a simple Web site, you may use only a single app. If youre building a complex Web site with several unrelated pieces such as an e-commerce system and a message board, youll probably want to split those into separate apps so that youll be able to reuse them individually in the future.

如果你�是建造一个简�的web站点，那么�能你�需�一个app就�以了。如果是��的象 电�商务之类的Web站点，你�能需�把这些功能划分���的app，以便以��用。

Indeed, you dont necessarily need to create apps at all, as evidenced by the example view functions weve created so far in this book. In those cases, we simply created a file called views.py , filled it with view functions, and pointed our URLconf at those functions. No apps were needed.

确实，你还�以�用创建app，例如以�写的视图，�是简�的放在 views.py ，�需�app。

However, theres one requirement regarding the app convention: if youre using Djangos database layer (models), you must create a Django app. Models must live within apps. Thus, in order to start writing our models, well need to create a new app.

当然，系统对app有一个约定：如果你使用了Django的数�库层（模型），你 必须创建一个django app。模型必须在这个app中存在。因此，为了开始建造 我们的模型，我们必须创建一个新的app。

Within the mysite project directory you created in Chapter 2, type this command to create a new app named books:

转到 mysite 项目目录，执行下�的命令�创建一个新app��books：

python manage.py startapp books

This command does not produce any output, but it does create a books directory within the mysite directory. Lets look at the contents of that directory:

这个命令没有输出什么，它在 mysite 的目录里创建了一个 books 目录。 让我们�看看这个目录的内容：

books/
    __init__.py
    models.py
    views.py

These files will contain the models and views for this app.

这些文件里�就包�了这个app的模型和视图。

Have a look at models.py and views.py in your favorite text editor. Both files are empty, except for an import in models.py . This is the blank slate for your Django app.

看一下 models.py 和 views.py 文件。它们都是空的，除了 models.py 里有一个 import。

Defining Models in Python

在Python代�里定义模型

As we discussed earlier in this chapter, the M in MTV stands for Model. A Django model is a description of the data in your database, represented as Python code. Its your data layout the equivalent of your SQL CREATE TABLE statements except its in Python instead of SQL, and it includes more than just database column definitions. Django uses a model to execute SQL code behind the scenes and return convenient Python data structures representing the rows in your database tables. Django also uses models to represent higher-level concepts that SQL cant necessarily handle.

我们早些时候谈到。MTV里的M代表模型。Django模型是用Python代�形�表述的数�在数�库 中的定义。对数�层�说它等�于 CREATE TABLE 语�，��过执行的是Python代�而�是 SQL，而且还包�了比数�库字段定义更多的�义。Django用模型在��执行SQL代�并把结果 用Python的数�结构��述，这样你�以很方便的使用这些数�。Django还用模型��述SQL�能 处�的高级概念。

If youre familiar with databases, your immediate thought might be, Isnt it redundant to define data models in Python and in SQL? Django works the way it does for several reasons:

如果你对数�库很熟悉，你�能马上就会想到，用Python 和 SQL�定义数�模型是�是有点多余？ Django这样�是有下�几个原因的：

Introspection requires overhead and is imperfect. In order to provide convenient data-access APIs, Django needs to know the database layout somehow , and there are two ways of accomplishing this. The first way would be to explicitly describe the data in Python, and the second way would be to introspect the database at runtime to determine the data models.

自�（�行时自动识别数�库）会导致过载和有数�完整性问题。为了�供方便的数�访问API， Django需�以 ��方� 知�数�库层内部信�，有两�实现方�。 第一�方�是用Python明确的定义数�模型，第二�方�是通过�行时扫�数�库�自动侦测识别数�模型。

This second way seems cleaner, because the metadata about your tables lives in only one place, but it introduces a few problems. First, introspecting a database at runtime obviously requires overhead. If the framework had to introspect the database each time it processed a request, or even when the Web server was initialized, this would incur an unacceptable level of overhead. (While some believe that level of overhead is acceptable, Djangos developers aim to trim as much framework overhead as possible, and this approach has succeeded in making Django faster than its high-level framework competitors in benchmarks.) Second, some databases, notably older versions of MySQL, do not store sufficient metadata for accurate and complete introspection.

第二�方�看起�更清晰，因为数�表信��存放在一个地方-数�库里，但是会带�一些问题。 首先，�行时扫�数�库会带�严�的系统过载。如果�个请求都�扫�数�库的表结构，或者�便是 �务�动时�一次都是会带��能接�的系统过载。（Django尽力��过载，而且�功�到了这一点） 其次，有些数�库，例如�版本的MySQL，没有�供足够的元数��完整地�构数�表。

Writing Python is fun, and keeping everything in Python limits the number of times your brain has to do a context switch. It helps productivity if you keep yourself in a single programming environment/mentality for as long as possible. Having to write SQL, then Python, and then SQL again is disruptive.

编写Python代ç �是é�žå¸¸æœ‰è¶£çš„，ä¿�æŒ�用Pythonçš„æ–¹å¼�æ€�考会é�¿å…�你的大脑在ä¸�å�Œé¢†åŸŸæ�¥å›žåˆ‡æ�¢ã€‚ è¿™å�¯ä»¥å¸®åŠ©ä½ æ��高生产率。ä¸�å¾—ä¸�去é‡�å¤�写SQL，å†�写Python代ç �，å†�写SQL，…，会让你头都è¦�裂了。

Having data models stored as code rather than in your database makes it easier to keep your models under version control. This way, you can easily keep track of changes to your data layouts.

把数�模型用代�的方�表述�让你�以容易对它们进行版本控制。这样，你�以很容易了解数�层 的�动情况。

SQL allows for only a certain level of metadata about a data layout. Most database systems, for example, do not provide a specialized data type for representing email addresses or URLs. Django models do. The advantage of higher-level data types is higher productivity and more reusable code.

SQL�能�述特定类型的数�字段。例如，大多数数�库都没有数�字段类型�述Email地��URL。 而用Django的模型�以�到这一点。好处就是高级的数�类型带�高生产力和更好的代��用。

SQL is inconsistent across database platforms. If youre distributing a Web application, for example, its much more pragmatic to distribute a Python module that describes your data layout than separate sets of CREATE TABLE statements for MySQL, PostgreSQL, and SQLite.

SQL还有在��数�库平�的兼容性问题。你必须为��的数�库编写��的SQL脚本， 而Python的模�就�会有这个问题。

A drawback of this approach, however, is that its possible for the Python code to get out of sync with whats actually in the database. If you make changes to a Django model, youll need to make the same changes inside your database to keep your database consistent with the model. Well detail some strategies for handling this problem later in this chapter.

当然，这个方法也有一个缺点，就是Python代�和数�库表的�步问题。如果你修改了一个Django模型， 你�自己�工作���数�库和模型�步。我们将在��讲解解决这个问题的几�策略。

Finally, we should note that Django includes a utility that can generate models by introspecting an existing database. This is useful for quickly getting up and running with legacy data.

最�,我们��醒你Django�供了实用工具�从现有的数�库表中自动扫�生�模型。 这对已有的数�库�说是�常快�有用的。

Your First Model

你的第一个模型

As an ongoing example in this chapter and the next chapter, well focus on a basic book/author/publisher data layout. We use this as our example because the conceptual relationships between books, authors, and publishers are well known, and this is a common data layout used in introductory SQL textbooks. Youre also reading a book that was written by authors and produced by a publisher!

在本章和�续章节里，我们将集中到一个基本的 书�/作者/出版商 数�层上。我们这样�是因为 这是一个众所周知的例�，很多SQL有关的书�也常用这个举例。你现在看的这本书也是由作者 创作�由出版商出版的哦�

Well suppose the following concepts, fields, and relationships:

我们��定下�的这些概念�字段和关系：

• An author has a salutation (e.g., Mr. or Mrs.), a first name, a last name, an email address, and a headshot photo.

• 作者有尊称（例如，先生或者女士），姓，å��，还有Email地å�€ï¼Œå¤´åƒ�。

• A publisher has a name, a street address, a city, a state/province, a country, and a Web site.

• 出版商有å��称，地å�€ï¼Œæ‰€åœ¨åŸŽå¸‚ã€�çœ�，国家，网站。

• A book has a title and a publication date. It also has one or more authors (a many-to-many relationship with authors) and a single publisher (a one-to-many relationship aka foreign key to publishers).

• 书ç±�有书å��和出版日期。它有一个或多个作者（和作者是多对多的关è�”关系[many-to-many]）， å�ªæœ‰ä¸€ä¸ªå‡ºç‰ˆå•†ï¼ˆå’Œå‡ºç‰ˆå•†æ˜¯ä¸€å¯¹å¤šçš„å…³è�”关系[one-to-many]，也被称作外键[foreign key]）

The first step in using this database layout with Django is to express it as Python code. In the models.py file that was created by the startapp command, enter the following:

第一步是用Python代���述它们。打开 models.py 并输入下�的内容：

from django.db import models

class Publisher(models.Model):
    name = models.CharField(maxlength=30)
    address = models.CharField(maxlength=50)
    city = models.CharField(maxlength=60)
    state_province = models.CharField(maxlength=30)
    country = models.CharField(maxlength=50)
    website = models.URLField()

class Author(models.Model):
    salutation = models.CharField(maxlength=10)
    first_name = models.CharField(maxlength=30)
    last_name = models.CharField(maxlength=40)
    email = models.EmailField()
    headshot = models.ImageField(upload_to='/tmp')

class Book(models.Model):
    title = models.CharField(maxlength=100)
    authors = models.ManyToManyField(Author)
    publisher = models.ForeignKey(Publisher)
    publication_date = models.DateField()

Lets quickly examine this code to cover the basics. The first thing to notice is that each model is represented by a Python class that is a subclass of django.db.models.Model . The parent class, Model , contains all the machinery necessary to make these objects capable of interacting with a database and that leaves our models responsible solely for defining their fields, in a nice and compact syntax. Believe it or not, this is all the code we need to write to have basic data access with Django.

让我们�快速讲解一下这些代�的�义。首先�注�的事是�个数�模型都是 django.db.models.Model 的�类。它的父类 Model 包�了所有和数�库 打交�的方法，并�供了一个简�漂亮的定义语法。�管你相信还是�相信， 这就是我们用Django写的数�基本存�功能的全部代�。

Each model generally corresponds to a single database table, and each attribute on a model generally corresponds to a column in that database table. The attribute name corresponds to the columns name, and the type of field (e.g., CharField ) corresponds to the database column type (e.g., varchar ). For example, the Publisher model is equivalent to the following table (assuming PostgreSQL CREATE TABLE syntax):

�个模型相当于�个数�库表，�个属性也是这个表中的一个字段。 属性�就是字段�，它的类型（例如 CharField ）相当于数�库的字段类型 （例如 varchar ）。例如， Publisher 模�等�于下�这张表（用Postgresql 的 CREATE TABLE 语法�述）：

CREATE TABLE "books_publisher" (
    "id" serial NOT NULL PRIMARY KEY,
    "name" varchar(30) NOT NULL,
    "address" varchar(50) NOT NULL,
    "city" varchar(60) NOT NULL,
    "state_province" varchar(30) NOT NULL,
    "country" varchar(50) NOT NULL,
    "website" varchar(200) NOT NULL
);

Indeed, Django can generate that CREATE TABLE statement automatically, as well show in a moment.

事实上，正如过一会儿我们所�展示的，Django �以自动生�这些 CREATE TABLE 语�。

The exception to the one-class-per-database-table rule is the case of many-to-many relationships. In our example models, Book has a ManyToManyField called authors . This designates that a book has one or many authors, but the Book database table doesnt get an authors column. Rather, Django creates an additional table a many-to-many join table that handles the mapping of books to authors.

“�个数�库表对应一个类�这�规则的例外情况是多对多关系。在我们的范例模型中， Book 有一个 多对多字段 �� authors 。 该字段表明一本书�有一个或多个作者，但 Book 数�库表�并没有 authors 字段。相�，Django创建了一个�外的表（多对多连接表）�处�书�和作者之间的映射关系。

For a full list of field types and model syntax options, see Appendix B.

请查看附录 B 了解所有的字段类型和模型语法选项。

Finally, note we havent explicitly defined a primary key in any of these models. Unless you instruct it otherwise, Django automatically gives every model an integer primary key field called id . Each Django model is required to have a single-column primary key.

最�需�注�的是：我们并没有显�地为这些模型定义任何主键。除�你指定，�则 Django 会自动为�个模型创建一个�� id 的主键。�个 Django 模型必须�有一个�列主键。

Installing the Model

模型安装

Weve written the code; now lets create the tables in our database. In order to do that, the first step is to activate these models in our Django project. We do that by adding the books app to the list of installed apps in the settings file.

完�这些代�之�，现在让我们�在数�库中创建这些表。�完�该项工作，第一步是在 Django 项目中 激活 这些模型。将 books app 添加到�置文件的已 installed apps 列表中��完�此步骤。

Edit the settings.py file again, and look for the INSTALLED_APPS setting. INSTALLED_APPS tells Django which apps are activated for a given project. By default, it looks something like this:

�次编辑 settings.py 文件， 找到 INSTALLED_APPS 设置。 INSTALLED_APPS 告诉 Django 项目哪些 app 处于激活状�。缺�情况下如下所示：

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
)

Temporarily comment out all four of those strings by putting a hash character (# ) in front of them. (Theyre included by default as a common-case convenience, but well activate and discuss them later.) While youre at it, modify the default MIDDLEWARE_CLASSES and TEMPLATE_CONTEXT_PROCESSORS settings. These depend on some of the apps we just commented out. Then, add 'mysite.books' to the INSTALLED_APPS list, so the setting ends up looking like this:

把这四个设置��加#临时注释起�。（它们是一些缺�的公用设置，现在先�管 它们，以���讨论）�样的，修改缺�的 MIDDLEWARE_CLASSES 和 TEMPLATE_CONTEXT_PROCESSORS 设置，都注释起�。 然�添加 'mysite.books' 到 INSTALLED_APPS 列表，现在看起�是这样：

MIDDLEWARE_CLASSES = (
#    'django.middleware.common.CommonMiddleware',
#    'django.contrib.sessions.middleware.SessionMiddleware',
#    'django.contrib.auth.middleware.AuthenticationMiddleware',
#    'django.middleware.doc.XViewMiddleware',
)

TEMPLATE_CONTEXT_PROCESSORS = ()
#...

INSTALLED_APPS = (
    #'django.contrib.auth',
    #'django.contrib.contenttypes',
    #'django.contrib.sessions',
    #'django.contrib.sites',
    'mysite.books',
)

(As were dealing with a single-element tuple here, dont forget the trailing comma. By the way, this books authors prefer to put a comma after every element of a tuple, regardless of whether the tuple has only a single element. This avoids the issue of forgetting commas, and theres no penalty for using that extra comma.)

（尽管这是�个tuple元素，我们也��忘了结尾的逗�[,]。 �外，本书的作者喜欢在 �一个 tuple元素��加一个逗�，�管它是�是 �有一个元素。这是为了��忘了加逗�)

'mysite.books' refers to the books app were working on. Each app in INSTALLED_APPS is represented by its full Python path that is, the path of packages, separated by dots, leading to the app package.

'mysite.books' 标识 books app。 INSTALLED_APPS 中的�个app都用 Python的路径�述，包的路径，用�数点(.)区分。

Now that the Django app has been activated in the settings file, we can create the database tables in our database. First, lets validate the models by running this command:

现在我们�以创建数�库表了。首先，用下�的命令对校验模型的有效性：

python manage.py validate

The validate command checks whether your models syntax and logic are correct. If all is well, youll see the message 0 errors found . If you dont, make sure you typed in the model code correctly. The error output should give you helpful information about what was wrong with the code.

validate 命令检查你的模型的语法和逻辑是�正确。如果一切正常，你会看到 0 errors found 消�。如果有问题，它会给出�常有用的错误信��帮助你 修正你的模型。

Any time you think you have problems with your models, run python manage.py validate . It tends to catch all the common model problems.

一旦你觉得你的模型�能有问题，�行 python manage.py validate 。 它�以帮助你�获一些常�的模型定义错误。

If your models are valid, run the following command for Django to generate CREATE TABLE statements for your models in the books app (with colorful syntax highlighting available if youre using Unix):

模型确认没问题了，�行下�的命令�生� CREATE TABLE 语�：

python manage.py sqlall books

In this command, books is the name of the app. Its what you specified when you ran the command manage.py startapp . When you run the command, you should see something like this:

在这个命令行中， books 是app的�称。和你�行 manage.py startapp 中的一样。 �行命令的结果是这样的：

BEGIN;
CREATE TABLE "books_publisher" (
    "id" serial NOT NULL PRIMARY KEY,
    "name" varchar(30) NOT NULL,
    "address" varchar(50) NOT NULL,
    "city" varchar(60) NOT NULL,
    "state_province" varchar(30) NOT NULL,
    "country" varchar(50) NOT NULL,
    "website" varchar(200) NOT NULL
);
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
);
CREATE TABLE "books_author" (
    "id" serial NOT NULL PRIMARY KEY,
    "salutation" varchar(10) NOT NULL,
    "first_name" varchar(30) NOT NULL,
    "last_name" varchar(40) NOT NULL,
    "email" varchar(75) NOT NULL,
    "headshot" varchar(100) NOT NULL
);
CREATE TABLE "books_book_authors" (
    "id" serial NOT NULL PRIMARY KEY,
    "book_id" integer NOT NULL REFERENCES "books_book" ("id"),
    "author_id" integer NOT NULL REFERENCES "books_author" ("id"),
    UNIQUE ("book_id", "author_id")
);
CREATE INDEX books_book_publisher_id ON "books_book" ("publisher_id");
COMMIT;

Note the following:

注�：

• Table names are automatically generated by combining the name of the app (books ) and the lowercase name of the model (publisher , book , and author ). You can override this behavior, as detailed in Appendix B.

• 自动生æˆ�的表å��是appå��称（ books ）和模型的å°�写å��称 （ publisher , book , author )的组å�ˆã€‚ ä½ å�¯ä»¥æŒ‡å®šä¸�å�Œçš„表å��，详情请看附录 B。

• As we mentioned earlier, Django adds a primary key for each table automatically the id fields. You can override this, too.

• 我们å‰�é�¢å·²ç»�æ��到，Django为自动加了一个 id 主键，你一样å�¯ä»¥ä¿®æ”¹å®ƒã€‚

• By convention, Django appends "_id" to the foreign key field name. As you might have guessed, you can override this behavior, too.

• 按约定，Django添加 "_id" å�Žç¼€åˆ°å¤–键字段å��。这个å�Œæ ·ä¹Ÿæ˜¯å�¯è‡ªå®šä¹‰çš„。

• The foreign key relationship is made explicit by a REFERENCES statement.

• 外键是用 REFERENCES 语å�¥æ˜Žç¡®å®šä¹‰çš„。

• These CREATE TABLE statements are tailored to the database youre using, so database-specific field types such as auto_increment (MySQL), serial (PostgreSQL), or integer primary key (SQLite) are handled for you automatically. The same goes for quoting of column names (e.g., using double quotes or single quotes). This example output is in PostgreSQL syntax.

• 这些 CREATE TABLE 语å�¥ä¼šæ ¹æ�®ä½ çš„æ•°æ�®åº“而作调整，这样象数æ�®åº“特定的一些字段例如： auto_increment (MySQL), serial (PostgreSQL), integer primary key (SQLite) å�¯ä»¥è‡ªåŠ¨å¤„ç�†ã€‚ å�Œæ ·çš„，字段å��称的引å�·ä¹Ÿæ˜¯è‡ªåŠ¨å¤„ç�†ï¼ˆä¾‹å¦‚å�•å¼•å�·è¿˜æ˜¯å�Œå¼•å�·ï¼‰ã€‚ 这个给出的例å­�是Postgresql的语法。

The sqlall command doesnt actually create the tables or otherwise touch your database it just prints output to the screen so you can see what SQL Django would execute if you asked it. If you wanted to, you could copy and paste this SQL into your database client, or use Unix pipes to pass it directly. However, Django provides an easier way of committing the SQL to the database. Run the syncdb command, like so:

sqlall 命令并没有在数�库中真正创建数�表，�是把SQL语�段打�出�。 你�以把这些语�段拷�到你的SQL客户端去执行它。当然，Django�供了更简�的 方法�执行这些SQL语�。�行 syncdb 命令：

python manage.py syncdb

Youll see something like this:

你将会看到这样的内容：

Creating table books_publisher
Creating table books_book
Creating table books_author
Installing index for books.Book model

The syncdb command is a simple sync of your models to your database. It looks at all of the models in each app in your INSTALLED_APPS setting, checks the database to see whether the appropriate tables exist yet, and creates the tables if they dont yet exist. Note that syncdb does not sync changes in models or deletions of models; if you make a change to a model or delete a model, and you want to update the database, syncdb will not handle that. (More on this later.)

syncdb 命令是�步你的模型到数�库的一个简�方法。它会根� INSTALLED_APPS 里设置的app�检查数�库， 如果表�存在，它就会创建它。 需�注�的是， syncdb 并 �能 �步模型的修改到数�库。如果你修改了模型，然�你想更新 数�库， syncdb 是帮�了你的。（��我们�讲这些。）

If you run python manage.py syncdb again, nothing happens, because you havent added any models to the books app or added any apps to INSTALLED_APPS . Ergo, its always safe to run python manage.py syncdb it wont clobber things.

如果你�次�行 python manage.py syncdb ，什么也没�生，因为你没有添加新的模型或者 添加新的app。所以，�行 python manage.py syncdb 总是安全的，它�会把事情�砸。

If youre interested, take a moment to dive into your database servers command-line client and see the database tables Django created. You can manually run the command-line client (e.g., psql for PostgreSQL) or you can run the command python manage.py dbshell , which will figure out which command-line client to run, depending on your DATABASE_SERVER setting. The latter is almost always more convenient.

如果你有兴趣，花点时间用你的SQL客户端登录进数�库�务器看看刚�Django创建的数�表。 Django带有一个命令行工具， python manage.py dbshell 。

Basic Data Access

基本数�访问

Once youve created a model, Django automatically provides a high-level Python API for working with those models. Try it out by running python manage.py shell and typing the following:

一旦你创建了模型，Django自动为这些模型�供了高级的Pyhton API。 �行 python manage.py shell 并输入下�的内容试试看：

>>> from books.models import Publisher
>>> p1 = Publisher(name='Addison-Wesley', address='75 Arlington Street',
...     city='Boston', state_province='MA', country='U.S.A.',
...     website='http://www.apress.com/')
>>> p1.save()
>>> p2 = Publisher(name="O'Reilly", address='10 Fawcett St.',
...     city='Cambridge', state_province='MA', country='U.S.A.',
...     website='http://www.oreilly.com/')
>>> p2.save()
>>> publisher_list = Publisher.objects.all()
>>> publisher_list
[<Publisher: Publisher object>, <Publisher: Publisher object>]

These few lines of code accomplish quite a bit. Here are the highlights:

这短短几行代�干了�少的事。这里简�的说一下：

• To create an object, just import the appropriate model class and instantiate it by passing in values for each field.

• è¦�创建对象，å�ªéœ€ import 相应模型类，并传入æ¯�个字段值将其实例化。

• To save the object to the database, call the save() method on the object. Behind the scenes, Django executes an SQL INSERT statement here.

• 调用该对象的 save() 方法，将对象ä¿�存到数æ�®åº“中。Django 会在å�Žå�°æ‰§è¡Œä¸€æ�¡ INSERT 语å�¥ã€‚

• To retrieve objects from the database, use the attribute Publisher.objects . Fetch a list of all Publisher objects in the database with the statement Publisher.objects.all() . Behind the scenes, Django executes an SQL SELECT statement here.

• 使用属性 Publisher.objects 从数æ�®åº“中获å�–对象。调用 Publisher.objects.all() 获å�–æ•°æ�®åº“中所有的 Publisher 对象。此时，Django 在å�Žå�°æ‰§è¡Œä¸€æ�¡ SELECT SQL语å�¥ã€‚

Naturally, you can do quite a lot with the Django database API but first, lets take care of a small annoyance.

自然，你肯定想执行更多的Django数�库API试试看，�过，还是让我们先解决一点烦人的�问题。

Adding Model String Representations

添加模�的字符串表现

When we printed out the list of publishers, all we got was this unhelpful display that makes it difficult to tell the Publisher objects apart:

当我们打�整个publisher列表时，我们没有得到想�的有用的信�：

[<Publisher: Publisher object>, <Publisher: Publisher object>]

We can fix this easily by adding a method called __str__() to our Publisher object. A __str__() method tells Python how to display the string representation of an object. You can see this in action by adding a __str__() method to the three models:

我们�以简�解决这个问题，�需�添加一个方法 __str__() 到 Publisher 对象。 __str__() 方法告诉Python�怎样把对象当作字符串�使用。 请看下�：

from django.db import models

class Publisher(models.Model):
    name = models.CharField(maxlength=30)
    address = models.CharField(maxlength=50)
    city = models.CharField(maxlength=60)
    state_province = models.CharField(maxlength=30)
    country = models.CharField(maxlength=50)
    website = models.URLField()

    **def __str__(self):**
        **return self.name**

class Author(models.Model):
    salutation = models.CharField(maxlength=10)
    first_name = models.CharField(maxlength=30)
    last_name = models.CharField(maxlength=40)
    email = models.EmailField()
    headshot = models.ImageField(upload_to='/tmp')

    **def __str__(self):**
        **return '%s %s' % (self.first_name, self.last_name)**

class Book(models.Model):
    title = models.CharField(maxlength=100)
    authors = models.ManyToManyField(Author)
    publisher = models.ForeignKey(Publisher)
    publication_date = models.DateField()

    **def __str__(self):**
        **return self.title**

As you can see, a __str__() method can do whatever it needs to do in order to return a string representation. Here, the __str__() methods for Publisher and Book simply return the objects name and title, respectively, but the __str__() for Author is slightly more complex it pieces together the first_name and last_name fields. The only requirement for __str__() is that it return a string. If __str__() doesnt return a string if it returns, say, an integer then Python will raise a TypeError with a message like "__str__ returned non-string" .

就象你看到的一样， __str__() 方法返回一个字符串。 __str__() 必须返回字符串， 如果是其他类型，Python将会抛出 TypeError 错误消� "__str__ returned non-string" 出�。

For the changes to take effect, exit out of the Python shell and enter it again with python manage.py shell . (This is the simplest way to make code changes take effect.) Now the list of Publisher objects is much easier to understand:

为了让我们的修改生效，先退出Python Shell，然��次�行 python manage.py shell 进入。 现在列出 Publisher 对象就很容易�解了：

>>> from books.models import Publisher
>>> publisher_list = Publisher.objects.all()
>>> publisher_list
[<Publisher: Addison-Wesley>, <Publisher: O'Reilly>]

Make sure any model you define has a __str__() method not only for your own convenience when using the interactive interpreter, but also because Django uses the output of __str__() in several places when it needs to display objects.

请确�你的�一个模型里都包� __str__() 方法，这��是为了交互时方便，也是因为 Django会在其他一些地方用 __str__() �显示对象。

Finally, note that __str__() is a good example of adding behavior to models. A Django model describes more than the database table layout for an object; it also describes any functionality that object knows how to do. __str__() is one example of such functionality a model knows how to display itself.

最�， __str()__ 也是一个很好的例��演示我们怎么添加 行为 到模型里。 Django的模型��是为对象定义了数�库表的结构，还定义了对象的行为。 __str__() 就是一个例��演示模型知�怎么显示它们自己。

Inserting and Updating Data

�入和更新数�

Youve already seen this done: to insert a row into your database, first create an instance of your model using keyword arguments, like so:

你已�知�怎么�了：先使用一些关键�数创建对象实例，如下：

>>> p = Publisher(name='Apress',
...         address='2855 Telegraph Ave.',
...         city='Berkeley',
...         state_province='CA',
...         country='U.S.A.',
...         website='http://www.apress.com/')

This act of instantiating a model class does not touch the database.

这个对象实例并 没有 对数�库�修改。

To save the record into the database (i.e., to perform the SQL INSERT statement), call the objects save() method:

��存这个记录到数�库里（也就是执行 INSERT SQL 语�），调用对象的 save() 方法：

>>> p.save()

In SQL, this can roughly be translated into the following:

在SQL里，这大致�以转��这样：

INSERT INTO book_publisher
    (name, address, city, state_province, country, website)
VALUES
    ('Apress', '2855 Telegraph Ave.', 'Berkeley', 'CA',
     'U.S.A.', 'http://www.apress.com/');

Because the Publisher model uses an autoincrementing primary key id , the initial call to save() does one more thing: it calculates the primary key value for the record and sets it to the id attribute on the instance:

因为 Publisher 模型有一个自动增加的主键 id ，所以第一次调用 save() 还多�了一件事： 计算这个主键的值并把它赋值给这个对象实例：

>>> p.id
52    # this will differ based on your own data

Subsequent calls to save() will save the record in place, without creating a new record (i.e., performing an SQL UPDATE statement instead of an INSERT ):

接下��调用 save() 将�会创建新的记录，而�是修改记录内容（也就是 执行 UPDATE SQL语�，而�是 INSERT 语�）：

>>> p.name = 'Apress Publishing'
>>> p.save()

The preceding save() statement will result in roughly the following SQL:

��执行的 save() 相当于下�的SQL语�：

UPDATE book_publisher SET
    name = 'Apress Publishing',
    address = '2855 Telegraph Ave.',
    city = 'Berkeley',
    state_province = 'CA',
    country = 'U.S.A.',
    website = 'http://www.apress.com'
WHERE id = 52;

Selecting Objects

选择对象

Creating and updating data sure is fun, but it is also useless without a way to sift through that data. Weve already seen a way to look up all the data for a certain model:

我们已�知�查找所有数�的方法了：

>>> Publisher.objects.all()
[<Publisher: Addison-Wesley>, <Publisher: O'Reilly>, <Publisher: Apress Publishing>]

This roughly translates to this SQL:

这相当于这个SQL语�：

SELECT
    id, name, address, city, state_province, country, website
FROM book_publisher;

Note

注�

Notice that Django doesnt use SELECT * when looking up data and instead lists all fields explicitly. This is by design: in certain circumstances SELECT * can be slower, and (more important) listing fields more closely follows one tenet of the Zen of Python: Explicit is better than implicit.

注�到Django在选择所有数�时并没有使用 SELECT* ，而是显�列出了所有字段。 就是这样设计的： SELECT* 会更慢，而且最��的是列出所有字段�循了Python 界的一个信�：明确比�明确好。

For more on the Zen of Python, try typing import this at a Python prompt.

有关Python之禅(戒律) :-），在Python�示行输入 import this 试试看。

Lets take a close look at each part of this Publisher.objects.all() line:

让我们�仔细看看 Publisher.objects.all() 这行的�个部分：

First, we have the model we defined, Publisher . No surprise here: when you want to look up data, you use the model for that data.

首先，我们有一个已定义的模型 Publisher 。没什么好奇怪的：你想�查找数�， 你就用模型�获得数�。

Next, we have this objects business. Technically, this is a manager . Managers are discussed in detail in Appendix B. For now, all you need to know is that managers take care of all table-level operations on data including, most important, data lookup.

其次， objects 是干什么的？技术上，它是一个 管�器（manager） 。 管�器 将在附录B详细�述，在这里你��知�它处�有关数�表的�作，特别是数�查找。

All models automatically get a objects manager; youll use it any time you want to look up model instances.

所有的模型都自动拥有一个 objects 管�器；你�以在想�查找数�时是使用它。

Finally, we have all() . This is a method on the objects manager that returns all the rows in the database. Though this object looks like a list, its actually a QuerySet an object that represents some set of rows from the database. Appendix C deals with QuerySets in detail. For the rest of this chapter, well just treat them like the lists they emulate.

最�，还有 all() 方法。这是 objects 管�器返回所有记录的一个方法。 尽管这个对象 看起� 象一个列表（list），它实际是一个 QuerySet 对象， 这个对象是数�库中一些记录的集�。附录C将详细�述QuerySet，现在，我们 就先当它是一个仿真列表对象好了。

Any database lookup is going to follow this general pattern well call methods on the manager attached to the model we want to query against.

所有的数�库查找都�循一个通用模�：调用模型的管�器�查找数�。

>>> Publisher.objects.filter(name="Apress Publishing")
[<Publisher: Apress Publishing>]

SELECT
    id, name, address, city, state_province, country, website
FROM book_publisher
WHERE name = 'Apress Publishing';

>>> Publisher.objects.filter(country="U.S.A.", state_province="CA")
[<Publisher: Apress Publishing>]

SELECT
    id, name, address, city, state_province, country, website
FROM book_publisher
WHERE country = 'U.S.A.' AND state_province = 'CA';

>>> Publisher.objects.filter(name__contains="press")
[<Publisher: Apress Publishing>]

SELECT
    id, name, address, city, state_province, country, website
FROM book_publisher
WHERE name LIKE '%press%';

>>> Publisher.objects.get(name="Apress Publishing")
<Publisher: Apress Publishing>

>>> Publisher.objects.get(country="U.S.A.")
Traceback (most recent call last):
    ...
AssertionError: get() returned more than one Publisher -- it returned 2!

>>> Publisher.objects.get(name="Penguin")
Traceback (most recent call last):
    ...
DoesNotExist: Publisher matching query does not exist.

>>> Publisher.objects.order_by("name")
[<Publisher: Apress Publishing>, <Publisher: Addison-Wesley>, <Publisher: O'Reilly>]

SELECT
    id, name, address, city, state_province, country, website
FROM book_publisher
ORDER BY name;

>>> Publisher.objects.order_by("address")
[<Publisher: O'Reilly>, <Publisher: Apress Publishing>, <Publisher: Addison-Wesley>]

>>> Publisher.objects.order_by("state_province")
[<Publisher: Apress Publishing>, <Publisher: Addison-Wesley>, <Publisher: O'Reilly>]

>>> Publisher.objects.order_by("state_provice", "address")
 [<Publisher: Apress Publishing>, <Publisher: O'Reilly>, <Publisher: Addison-Wesley>]

>>> Publisher.objects.order_by("-name")
[<Publisher: O'Reilly>, <Publisher: Apress Publishing>, <Publisher: Addison-Wesley>]

class Publisher(models.Model):
    name = models.CharField(maxlength=30)
    address = models.CharField(maxlength=50)
    city = models.CharField(maxlength=60)
    state_province = models.CharField(maxlength=30)
    country = models.CharField(maxlength=50)
    website = models.URLField()

    def __str__(self):
        return self.name

    **class Meta:**
        **ordering = ["name"]**

>>> Publisher.objects.filter(country="U.S.A.").order_by("-name")
[<Publisher: O'Reilly>, <Publisher: Apress Publishing>, <Publisher: Addison-Wesley>]

SELECT
    id, name, address, city, state_province, country, website
FROM book_publisher
WHERE country = 'U.S.A'
ORDER BY name DESC;

>>> Publisher.objects.all()[0]
<Publisher: Addison-Wesley>

SELECT
    id, name, address, city, state_province, country, website
FROM book_publisher
ORDER BY name
LIMIT 1;

Deleting Objects

删除对象

To delete objects, simply call the delete() method on your object:

�删除对象，�需简�的调用对象的 delete() 方法：

>>> p = Publisher.objects.get(name="Addison-Wesley")
>>> p.delete()
>>> Publisher.objects.all()
[<Publisher: Apress Publishing>, <Publisher: O'Reilly>]

You can also delete objects in bulk by calling delete() on the result of some lookup:

你还�以批�删除对象，通过对查询的结果调用 delete() 方法：

>>> publishers = Publisher.objects.all()
>>> publishers.delete()
>>> Publisher.objects.all()
[]

Note

注�

Deletions are permanent , so be careful! In fact, its usually a good idea to avoid deleting objects unless you absolutely have to relational databases dont do undo so well, and restoring from backups is painful.

删除是 ���� 的，所以��心�作�事实上，应该尽���删除对象，除�你 确实需�删除它。数�库的数���的功能通常�太好，而从备份数���是很痛苦的。

Its often a good idea to add active flags to your data models. You can look up only active objects, and simply set the active field to False instead of deleting the object. Then, if you realize youve made a mistake, you can simply flip the flag back.

通常更好的方法是给你的数�模型添加激活标志。你�以�在激活的对象中查找， 对于�需�的对象，将激活字段值设为 False , 而�是删除对象。这样， 如果一旦你认为�错了的�，�需把标志�设回�就�以了。

Making Changes to a Database Schema

修改数�库表结构

When we introduced the syncdb command earlier in this chapter, we noted that syncdb merely creates tables that dont yet exist in your database it does not sync changes in models or perform deletions of models. If you add or change a models field, or if you delete a model, youll need to make the change in your database manually. This section explains how to do that.

当我们在这一章的��介� syncdb 命令的时候，我们强调 syncdb 仅仅创建数�库中�存在的表，而�会�步模型的修改或者删除到数�库。如果你添加或者修改了模型的一个字段，或者删除一个模型，你必须手动改�你的数�库。下�我们看看怎么��。

When dealing with schema changes, its important to keep a few things in mind about how Djangos database layer works:

当我们处�表结构的修改时，�时刻想� Django 的数�库层是如何工作的：

• Django will complain loudly if a model contains a field that has not yet been created in the database table. This will cause an error the first time you use the Django database API to query the given table (i.e., it will happen at code execution time, not at compilation time).

• 如果模型中包å�«ä¸€ä¸ªåœ¨æ•°æ�®åº“中并ä¸�存在的字段，Django会大声抱怨的。这样当你第一次调用Djangoçš„æ•°æ�®åº“APIæ�¥æŸ¥è¯¢ç»™å®šçš„表时就会出错（也就是说，它会在执行的时候出错，而ä¸�是编译的时候）

• Django does not care if a database table contains columns that are not defined in the model.

• Django并ä¸�关心数æ�®åº“表中是å�¦å­˜åœ¨æ²¡æœ‰åœ¨æ¨¡åž‹ä¸­å®šä¹‰çš„列

• Django does not care if a database contains a table that is not represented by a model.

• Django并ä¸�关心数æ�®åº“中是å�¦åŒ…å�«æ²¡æœ‰è¢«æ¨¡åž‹æ��述的表

Making schema changes is a matter of changing the various pieces the Python code and the database itself in the right order.

修改表结构也就是按照正确的顺�修改��Python代�和数�库本身

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

    def __str__(self):
        return self.title

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
);

"num_pages" integer NULL

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;

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

ALTER TABLE books_book DROP COLUMN num_pages;

DROP TABLE books_books_publishers;

DROP TABLE books_book;

Whats Next?

下一步？

Once youve defined your models, the next step is to populate your database with data. You might have legacy data, in which case Chapter 16 will give you advice about integrating with legacy databases. You might rely on site users to supply your data, in which case Chapter 7 will teach you how to process user-submitted form data.

一旦你定义了你的模型，接下�就是�把数�导入数�库里了。你�能已�有现�的数�了，请看第�六章，如何集�现有的数�库。也�能数�是用户�供的，第七章中还会教你怎么处�用户�交的数�。

But in some cases, you or your team might need to enter data manually, in which case it would be helpful to have a Web-based interface for entering and managing data. The next chapter covers Djangos admin interface, which exists precisely for that reason.

有时候，你和你的团队�员也需�手工输入数�，这时候如果能有一个基于Web的数�输入和管�的界� 就很有帮助。下一章将讲述Django的管�界�，它就是专门干这个活的。