As an ongoing example in this chapter and the next chapter, I'll focus on a basic book/author/publisher data layout. I 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. You're also reading a book that was written by authors and produced by a publisher!

I'll suppose the following concepts, fields, and relationships:

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:

from django.db import models 
 
class Publisher(models.Model): 
    name = models.CharField(max_length=30) 
    address = models.CharField(max_length=50) 
    city = models.CharField(max_length=60) 
    state_province = models.CharField(max_length=30) 
    country = models.CharField(max_length=50) 
    website = models.URLField() 
 
class Author(models.Model): 
    first_name = models.CharField(max_length=30) 
    last_name = models.CharField(max_length=40) 
    email = models.EmailField() 
 
class Book(models.Model): 
    title = models.CharField(max_length=100) 
    authors = models.ManyToManyField(Author) 
    publisher = models.ForeignKey(Publisher) 
    publication_date = models.DateField() 

Let's 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. 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 column's name, and the type of field (example, CharField) corresponds to the database column type (example, varchar). For example, the Publisher model is equivalent to the following table (assuming PostgreSQL CREATE TABLE syntax):

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 we'll show you in a moment. 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 doesn't get an authors column. Rather, Django creates an additional table-a many-to-many join table-that handles the mapping of books to authors.

For a full list of field types and model syntax options, see Appendix B, Database API Reference. Finally, note we haven't explicitly defined a primary key in any of these models. Unless you instruct it otherwise, Django automatically gives every model an auto-incrementing integer primary key field called id. Each Django model is required to have a single-column primary key.

We've written the code; now let's 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. 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:

INSTALLED_APPS = ( 
'django.contrib.admin', 
'django.contrib.auth', 
'django.contrib.contenttypes', 
'django.contrib.sessions', 
'django.contrib.messages', 
'django.contrib.staticfiles', 
) 

To register our books app, add 'books' to INSTALLED_APPS, so the setting ends up looking like this ('books' refers to the "books" app we're working on):

INSTALLED_APPS = ( 
'django.contrib.admin', 
'django.contrib.auth', 
'django.contrib.contenttypes', 
'django.contrib.sessions', 
'django.contrib.messages', 
'django.contrib.staticfiles', 
'books', 
) 

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. Now that the Django app has been activated in the settings file, we can create the database tables in our database. First, let's validate the models by running this command:

python manage.py check

The check command runs the Django system check framework-a set of static checks for validating Django projects. If all is well, you'll see the message System check identified no issues (0 silenced). If you don't, make sure you typed in the model code correctly. The error output should give you helpful information about what was wrong with the code. Anytime you think you have problems with your models, run python manage.py check. It tends to catch all the common model problems.

If your models are valid, run the following command to tell Django that you have made some changes to your models (in this case, you have made a new one):

python manage.py makemigrations books 

You should see something similar to the following:

Migrations for 'books': 
  0001_initial.py: 
   -Create model Author 
   -Create model Book 
   -Create model Publisher 
   -Add field publisher to book 

Migrations are how Django stores changes to your models (and thus your database schema)-they're just files on disk. In this instance, you will find  file names 0001_initial.py in the 'migrations' folder of the books app. The migrate command will take your latest migration file and update your database schema automatically, but first, let's see what SQL that migration would run. The sqlmigrate command takes migration names and returns their SQL:

python manage.py sqlmigrate books 0001

You should see something similar to the following (reformatted for readability):

BEGIN; 
 
CREATE TABLE "books_author" ( 
    "id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
    "first_name" varchar(30) NOT NULL, 
    "last_name" varchar(40) NOT NULL, 
    "email" varchar(254) NOT NULL 
); 
CREATE TABLE "books_book" ( 
    "id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
    "title" varchar(100) NOT NULL, 
    "publication_date" date NOT NULL 
); 
CREATE TABLE "books_book_authors" ( 
    "id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
    "book_id" integer NOT NULL REFERENCES "books_book" ("id"), 
    "author_id" integer NOT NULL REFERENCES "books_author" ("id"), 
    UNIQUE ("book_id", "author_id") 
); 
CREATE TABLE "books_publisher" ( 
    "id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
    "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__new" ( 
    "id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, 
    "title" varchar(100) NOT NULL, 
    "publication_date" date NOT NULL, 
    "publisher_id" integer NOT NULL REFERENCES 
    "books_publisher" ("id") 
); 
 
INSERT INTO "books_book__new" ("id", "publisher_id", "title", 
"publication_date") SELECT "id", NULL, "title", "publication_date" FROM 
"books_book"; 
 
DROP TABLE "books_book"; 
 
ALTER TABLE "books_book__new" RENAME TO "books_book"; 
 
CREATE INDEX "books_book_2604cbea" ON "books_book" ("publisher_id"); 
 
COMMIT; 

Note the following:

These CREATE TABLE statements are tailored to the database you're 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 (example, using double quotes or single quotes). This example output is in PostgreSQL syntax.

The sqlmigrate command doesn't 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, however, Django provides an easier way of committing the SQL to the database: the migrate command:

python manage.py migrate

Run that command, and you'll see something like this:

Operations to perform:
  Apply all migrations: books
Running migrations:
  Rendering model states... DONE
  # ...
  Applying books.0001_initial... OK
  # ...

In case you were wondering what all the extras are (commented out above), the first time you run migrate, Django will also create all the system tables that Django needs for the inbuilt apps. Migrations are Django's way of propagating changes you make to your models (adding a field, deleting a model, and so on.) into your database schema. They're designed to be mostly automatic, however, there are some caveats. For more information on migrations, see Chapter 21, Advanced Database Management.