xdjango-postgres-extra

xdjango-postgres-extra is a maintained fork of django-postgres-extra. It extends Django's PostgreSQL backend with features such as atomic upserts, table partitioning, views, materialized views, schema management, and explicit table locking.

The PyPI distribution is named xdjango-postgres-extra. The Python package and existing imports remain named psqlextra.

Compatibility

• Django: 2.0 through 6.x (Django>=2.0,<7.0)
• Python: 3.6 through 3.14
• PostgreSQL: 11 or newer
• Psycopg: 2 and 3

Django 6 requires Python 3.12 or newer. The 2.1.x release line was verified with Django 6.0.6 and Python 3.14.

Installation

python -m pip install xdjango-postgres-extra

Use the psqlextra database backend in your Django settings:

DATABASES = {
    "default": {
        "ENGINE": "psqlextra.backend",
        "NAME": "my_database",
        "USER": "my_user",
        "PASSWORD": "my_password",
        "HOST": "localhost",
        "PORT": "5432",
    }
}

Add the application when using features that require app registration:

INSTALLED_APPS = [
    # ...
    "django.contrib.postgres",
    "psqlextra",
]

Existing application code continues to use psqlextra imports:

from psqlextra.models import PostgresModel

Features

• Atomic INSERT ... ON CONFLICT handling with DO UPDATE and DO NOTHING
• Bulk inserts and upserts
• PostgreSQL range, list, hash, and default table partitions
• Time-based partition management
• Database views and materialized views integrated with migrations
• PostgreSQL schema creation, deletion, and temporary schemas
• Explicit model and table locks
• TRUNCATE TABLE, including cascading truncation
• HStore constraints and expressions
• PostgreSQL-specific indexes and introspection

The upstream documentation remains the primary API reference:

• Documentation
• Installation guide
• Feature reference

When following upstream installation instructions, install xdjango-postgres-extra instead of django-postgres-extra.

Development

Create a virtual environment and install the development extras:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,test]"

Set a PostgreSQL test database URL:

export DATABASE_URL="postgres://psqlextra:password@localhost/psqlextra"

Run the available Poe tasks:

poe test
poe verify

License

MIT. See LICENSE.