Project Overview & Django Project Setup

Personal Catalogue: Django & PostgreSQL

Chapter 1 · Project Overview & Django Project Setup

This is one of four courses building the exact same personal cataloguing tool in four genuinely different architectures — Personal Catalogue (PHP & MySQL, complete — see catalog-php1), Personal Catalogue (React + Express + MongoDB), and Personal Catalogue (React & Firebase) are its siblings. This course's own answer leans into a real, normalized relational schema and Django's own ready-made admin interface — a genuinely different tradeoff from the PHP variant's own bare-metal speed.

What the App Actually Does

The shared spec every course in the quartet builds toward:

Catalogue four kinds of item — books, CDs, DVDs, and Blu-rays — so it's possible to quickly check "do I already own this CD?" or "what Python books do I have?"
Tag books with free-form labels (a FastAPI book might get Python, Web Development, Programming, Web Frameworks) so related books can be found by topic later.
Add items manually for the first release — title, author/artist, format-specific details, tags where relevant.
Search and browse the collection to answer the "do I have this?" question quickly.

Barcode scanning is explicitly out of scope for this first release — a real, obvious way to add items even faster, but deliberately deferred rather than allowed to hold up a release that needs to ship quickly. This course closes with a real, concrete plan for adding it later (Chapter 9), rather than pretending it isn't wanted at all.

Why Django + PostgreSQL for This One

Of the four variants in this set, Django + PostgreSQL is the one built around genuine data integrity and a real, ready-made tool for fast manual entry. Books, CDs, DVDs, and Blu-rays share several real fields (title, format, year) while differing in others, and tags need a genuine many-to-many relationship against books specifically — exactly the shape a normalized relational schema, and PostgreSQL's own real foreign-key enforcement, is built to express cleanly, covered in full in Chapter 2. Django's own built-in admin interface — generated automatically from the models this course defines — does real double duty here: it's a genuinely fast, already-built manual data-entry tool, directly useful given this project's own real time pressure, covered in Chapter 3.

This Course Assumes Real Django/PostgreSQL Groundwork Already Covered Elsewhere

This site's own Django Fundamentals course already covers models, migrations, and the Django ORM in real depth, and the PostgreSQL course covers real relational schema design and query fundamentals. This course doesn't re-teach either — it assumes both, and moves straight into this catalogue's own real schema and features.

A Real Deadline, Not Just a Framing Device

This project genuinely needs a working first release quickly. That constraint shapes real decisions throughout this course — leaning on Django's own built-in admin instead of hand-building a data-entry UI first, and a deliberately un-fancy set of public-facing views before any polish — not because those are always the "correct" choices, but because they're the right choices given this specific, real time pressure. Chapter 8 covers styling and templates once the functional core is genuinely working.

Setting Up: Django, PostgreSQL & a Working Connection

A local Python install with pip, and a working local PostgreSQL server, are assumed from here on. Install Django and the PostgreSQL adapter into a virtual environment:

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # venv\Scripts\activate on Windows

# Install Django and the PostgreSQL adapter
pip install django psycopg2-binary

Create the PostgreSQL database this whole course builds on, using psql or your own preferred client:

CREATE DATABASE catalogue WITH ENCODING 'UTF8';

Starting the Django Project

Unlike the PHP variant, there's genuine project scaffolding here — Django generates a real, structured project layout rather than starting from a single connected file:

# Start the Django project and the catalogue app
django-admin startproject catalogue_site .
python manage.py startapp catalogue

Point the new project at the real PostgreSQL database in catalogue_site/settings.py:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'catalogue',
        'USER': 'postgres',
        'PASSWORD': '',  # set a real password in production
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

Add 'catalogue' to INSTALLED_APPS, then confirm the connection works by running Django's own initial migrations against the real database:

python manage.py migrate
python manage.py runserver

Real scaffolding to build before the first page loads

Unlike the PHP variant in this set — where a single config.php plus a working MySQL connection was the entire "setup" — Django genuinely generates a real project structure (settings, URL routing, an app skeleton) before any catalogue-specific code exists at all. That structure is exactly what pays off from Chapter 3 onward, once Django's own admin interface and ORM start doing real work on top of it.

psycopg2-binary is for development, not production

psycopg2-binary bundles its own compiled PostgreSQL client libraries specifically to make local setup fast — genuinely useful for exactly the kind of quick first release this project needs. The real, documented tradeoff is that it isn't recommended for production use, where the plain psycopg2 package, built against the system's own PostgreSQL client libraries, is the correct choice instead. Chapter 9's own deployment coverage returns to this distinction directly.

Where This Course Is Headed

A real normalized schema for items, item types, and a tags many-to-many (Chapter 2); the Django admin as a fast, ready-made manual entry tool (Chapter 3); the public-facing list and detail views (Chapter 4); a real Django form for adding items outside the admin, handling several genuinely different item shapes (Chapter 5); tags — filtering the catalogue by tag (Chapter 6); real search across the whole catalogue using the Django ORM (Chapter 7); styling and templates (Chapter 8); deployment (Chapter 9); and a capstone on integrating this catalogue into the existing Astro-based site, plus a real, concrete plan for barcode scanning as the next phase (Chapter 10).

Hands-On Exercises

Exercise 1

Explain why barcode scanning was deliberately deferred rather than built into this first release, and what real project constraint drove that decision.

📄 View solution

Exercise 2

Explain the real, documented difference between psycopg2-binary and plain psycopg2, and why this project's own deadline makes the binary package the right choice for now.

📄 View solution

Exercise 3

Set up the catalogue PostgreSQL database and a working Django project connected to it yourself, then write a one-sentence explanation of what python manage.py migrate actually confirmed by running successfully.

📄 View solution

Chapter 1 Quick Reference

The shared app — a personal catalogue for books/CDs/DVDs/Blu-rays, tags on books, manual entry first, barcode scanning deferred
Why this variant — a real normalized relational schema plus Django's own ready-made admin interface for fast manual entry
Database — PostgreSQL, created with explicit UTF8 encoding
Project — a real Django project (catalogue_site) with a catalogue app, connected via settings.py's DATABASES dict
Assumed groundwork — Django models/migrations/ORM and PostgreSQL fundamentals, both covered in their own dedicated courses on this site
Next chapter: Data Modeling — a real normalized schema for items, item types, and a tags many-to-many