How to Set Up PostgreSQL Database with a Django Application

When building production-ready Django applications, PostgreSQL is often the go-to database due to its robustness, scalability, and advanced feature set. While Django comes with SQLite as the default database, switching to PostgreSQL is a common and essential step for real-world applications.

This guide walks you through setting up PostgreSQL with your Django project from start to finish.

Prerequisites

Make sure you have the following installed:

• Python (3.7+ recommended)
• PostgreSQL
• pip
• Virtualenv (optional, but recommended)
• A Django project (or be ready to create one)

Step 1: Install PostgreSQL

If PostgreSQL isn’t installed yet:

On Windows:

Download and install PostgreSQL from the official site:
https://www.postgresql.org/download/windows/

Remember your PostgreSQL username (postgres by default) and password during setup.

On Linux:

sudo apt update
sudo apt install postgresql postgresql-contrib

On macOS:

brew install postgresql

Step 2: Create a PostgreSQL Database and User

1. Open your terminal or use pgAdmin.
2. Log into PostgreSQL shell:

   psql -U postgres

1. Create a database:

   CREATE DATABASE myprojectdb;

1. Create a user with password:

   CREATE USER myuser WITH PASSWORD 'mypassword';

1. Give the user access to the database:

   ALTER ROLE myuser SET client_encoding TO 'utf8';
   ALTER ROLE myuser SET default_transaction_isolation TO 'read committed';
   ALTER ROLE myuser SET timezone TO 'UTC';
   GRANT ALL PRIVILEGES ON DATABASE myprojectdb TO myuser;

Exit with \q.

Step 3: Set Up Django Project (if not yet created)

django-admin startproject myproject
cd myproject
python manage.py migrate  # Runs initial migrations

Step 4: Install PostgreSQL Driver

Inside your project’s virtual environment, install the required driver:

pip install psycopg2-binary

This package lets Django communicate with PostgreSQL.

Step 5: Update Django Settings

Open myproject/settings.py and find the DATABASES section. Replace the default SQLite configuration with:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'myprojectdb',
        'USER': 'myuser',
        'PASSWORD': 'mypassword',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

Ensure the credentials match what you created in Step 2.

Step 6: Run Migrations

Now apply Django's built-in models to the PostgreSQL database:

python manage.py migrate

If everything is correctly configured, the command will run without errors and set up your schema in PostgreSQL.

Step 7: Test the Setup

Create a superuser to access Django admin:

python manage.py createsuperuser

Run the server:

python manage.py runserver

Navigate to http://localhost:8000/admin and log in with your new superuser credentials.

Final Tips

• Add 'psycopg2-binary' to your requirements.txt for deployment.
• Use environment variables or Django's decouple package to avoid hardcoding DB credentials in settings.py.
• Always back up your PostgreSQL databases in production environments.

Conclusion

Setting up PostgreSQL with Django is a one-time configuration that pays off in scalability and advanced features. Whether you're preparing for production deployment or just learning, PostgreSQL helps you grow your Django application the right way.