Django Models Overview

1. Introduction

A Django model is a Python class that represents a database table. Each attribute of the class maps to a column in that table. When you define a model and run migrations, Django creates the table for you — no SQL required.

Models are the foundation of every Django project. Everything that involves storing or retrieving data goes through them — admin, forms, views, and the ORM all depend on your models being defined correctly.

• You should already have myproject set up with the pages app registered in INSTALLED_APPS.
• Your .venv must be active and Django 5.2 installed.

2. Your first model

Open pages/models.py and add this:

# pages/models.py

from django.db import models


class Page(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    created = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)

    def __str__(self):
        return self.title

Here is what each part does:

• class Page(models.Model) — every model inherits from models.Model. This gives it all the ORM functionality.
• title — a short text field with a maximum of 200 characters.
• content — a long text field with no length limit.
• created — automatically set to the current date and time when the record is first created.
• updated — automatically updated to the current date and time every time the record is saved.
• __str__ — returns a human-readable string for the object. Django uses this in the admin panel and shell.

3. How a model maps to a database table

Django translates your model class into a database table automatically. The Page model above becomes a table that looks like this:

Table: pages_page

| id  | title        | content    | created              | updated              |
|-----|--------------|------------|----------------------|----------------------|
| 1   | Hello World  | Some text  | 2026-01-01 10:00:00  | 2026-01-01 10:00:00  |
| 2   | About Us     | More text  | 2026-01-02 09:00:00  | 2026-01-03 11:00:00  |

• Table name — Django names the table using the pattern appname_modelname in lowercase. So Page in the pages app becomes pages_page. You can override this in the model's Meta class.
• id column — Django adds a primary key column called id automatically. It is an auto-incrementing integer. You do not need to define it yourself.
• Each field — becomes a column with the appropriate database type. CharField becomes VARCHAR, TextField becomes TEXT, and so on.

4. The migrations workflow

Defining a model in Python does not create the database table immediately. You need to run two commands:

# Step 1 — generate a migration file based on your model changes
python manage.py makemigrations

# Step 2 — apply the migration to create the table in the database
python manage.py migrate

After running these, Django creates the pages_page table in your database. Every time you change a model — add a field, remove a field, change a field type — you repeat these two commands.

5. Querying data with the ORM

Once the table exists, you use Django's ORM to create, read, update, and delete records — all in Python, no SQL needed.

# Create a record
page = Page.objects.create(title='Hello World', content='Some text')

# Get all records
pages = Page.objects.all()

# Get a single record
page = Page.objects.get(id=1)

# Filter records
pages = Page.objects.filter(title='Hello World')

# Update a record
page.title = 'Updated Title'
page.save()

# Delete a record
page.delete()

The objects attribute is the model's manager — the interface between your Python code and the database. We cover the ORM in full in the ORM and QuerySets section.

6. Where models fit in the project

Models sit at the center of a Django project. Almost everything else depends on them:

• Admin — registers models to give you a ready-to-use interface for managing records.
• Forms — ModelForm generates a form directly from a model's fields.
• Views — query models to fetch data and pass it to templates.
• Migrations — track every change you make to your models and apply them to the database.
• ORM — the query layer that sits between your models and the database.

7. Next steps

You now understand what a model is and how it maps to a database table. The next step is a full tour of the most common field types — so you know exactly which field to use for each kind of data in your models.