SectorLabs/django-postgres-extra

README


✅	Tests
📝	License
📦	PyPi
🍀	Code coverage
	Django Versions	2.0, 2.1, 2.2, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2
	Python Versions	3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13
	Psycopg Versions	2, 3
📖	Documentation	Read The Docs
⚠️	Upgrade	Upgrade from v1.x
🏁	Installation	Installation Guide
🔥	Features	Features & Documentation
💧	Future enhancements	Potential features

django-postgres-extra aims to make all of PostgreSQL's awesome features available through the Django ORM. We do this by taking care of all the hassle. As opposed to the many small packages that are available to try to bring a single feature to Django with minimal effort. django-postgres-extra goes the extra mile, with well tested implementations, seamless migrations and much more.

With seamless we mean that any features we add will work truly seamlessly. You should not have to manually modify your migrations to work with fields and objects provided by this package.

⚠️ This README is for v2. See the v1 branch for v1.x.

Major features

See the full list

Conflict handling (atomic upsert)

Adds support for PostgreSQL's ON CONFLICT syntax for inserts. Supports DO UPDATE and DO NOTHING. Single statement, atomic and concurrency safe upserts. Supports conditional updates as well.
Table partitioning

Adds support for PostgreSQL 11.x declarative table partitioning. Integrated into Django migrations. Supports all types of partitioning. Includes a command to automatically create time-based partitions.
Views & materialized views

Adds support for creating views & materialized views as any other model. Integrated into Django migrations.
Locking models & tables

Support for explicit table-level locks.
Creating/dropping schemas

Support for managing PostgreSQL schemas.
Truncating tables

Support for TRUNCATE TABLE statements (including cascading).

For Django 3.1 and older:

Conditional unique index
Case insensitive index

For Django 2.2 and older:

Unique index
HStore unique and required constraints on specific HStore keys

Working with the code

Prerequisites

PostgreSQL 14 or newer.
Django 5.x or newer.
Python 3.11 or newer.

These are just for local development. CI for code analysis etc runs against these. Tests will pass on all Python, Django and PostgreSQL versions documented. Linting, formatting and type-checking the code might not work on other Python and/or Django versions.

Getting started

Clone the repository:

 λ git clone https://github.com/SectorLabs/django-postgres-extra.git

Install uv if you don't have it:

λ curl -LsSf https://astral.sh/uv/install.sh | sh

Sync the development/test dependencies (creates .venv and installs from uv.lock):
```
λ cd django-postgres-extra
λ uv sync --extra dev --extra test
λ source .venv/bin/activate
```
uv.lock enforces a 3-day dependency cooldown via [tool.uv] exclude-newer in pyproject.toml, so newly-published versions cannot enter your environment until the community has had time to flag malicious releases.
Create a postgres user for use in tests (skip if your default user is a postgres superuser):
```
λ createuser --superuser psqlextra --pwprompt
λ export DATABASE_URL=postgres://psqlextra:<password>@localhost/psqlextra
```
Hint: if you're using virtualenvwrapper, you might find it beneficial to put the export line in $VIRTUAL_ENV/bin/postactivate so that it's always available when using this virtualenv.
Run the tests:
```
λ poe test
```
Run the benchmarks:
```
λ poe benchmark
```
Auto-format code, sort imports and auto-fix linting errors:
```
λ poe fix
```