Registry / database / django-postgres-extra

django-postgres-extra

library2.0.9pypiunverified

django-postgres-extra brings advanced PostgreSQL features like HStore fields, partitioned models, and enhanced querying capabilities directly into Django's ORM. It seamlessly integrates with Django models and querysets, allowing developers to leverage PostgreSQL-specific functionality without writing raw SQL. The current stable version is 2.0.9, with a 3.0.0 release candidate recently published, indicating an active development and release cadence.

database web-framework aws

pip install django-postgres-extra

homepage ↗

INSTALL

IMPORT

SIG · DJANGO-POSTGRES-EX

django-postgres-extra

databaseenv2.0.9

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.9 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

2/4 runs

py 3.11

2/4 runs

py 3.12

2/4 runs

py 3.13

2/4 runs

py 3.9

2/4 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HStoreField

✓ from pg_extra.fields import HStoreField

PostgreSQLPartitionedModel

✓ from pg_extra.models import PostgreSQLPartitionedModel

✗ from pg_extra.partitioned_models import PostgreSQLPartitionedModel

Partitioned models moved under pg_extra.models for Django 3.0+

PostgreSQLQuerySet

✓ from pg_extra.query import PostgreSQLQuerySet

To use `django-postgres-extra`, you must add 'pg_extra' to your `INSTALLED_APPS` in `settings.py`. This example demonstrates defining a model with an `HStoreField`, allowing flexible key-value storage. After adding the app and defining the model, run `python manage.py makemigrations` and `python manage.py migrate`.

import os from django.conf import settings from django.db import models # Minimal Django setup (for demonstration only) if not settings.configured: settings.configure( INSTALLED_APPS=['pg_extra', __name__], DATABASES={ 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': os.environ.get('PG_DB_NAME', 'test_db'), 'USER': os.environ.get('PG_DB_USER', 'user'), 'PASSWORD': os.environ.get('PG_DB_PASSWORD', 'password'), 'HOST': os.environ.get('PG_DB_HOST', 'localhost'), 'PORT': os.environ.get('PG_DB_PORT', '5432') } }, DEFAULT_AUTO_FIELD='django.db.models.BigAutoField' ) from pg_extra.fields import HStoreField class Product(models.Model): name = models.CharField(max_length=255) properties = HStoreField(blank=True, null=True, default=dict) def __str__(self): return self.name class Meta: app_label = 'my_app' # Required for this minimal setup # Example usage (requires a configured Django project and migrations applied) # print('Ensure pg_extra is in INSTALLED_APPS and run migrations.') # try: # p = Product.objects.create(name='Smartphone', properties={'color': 'black', 'storage_gb': '128'}) # print(f"Created product: {p.name} with properties {p.properties}") # retrieved_p = Product.objects.get(name='Smartphone') # print(f"Retrieved product color: {retrieved_p.properties['color']}") # except Exception as e: # print(f"Error during quickstart: {e}")

Debug

Known issues

breakingVersion 3.0.0rc1 (and likely future 3.0.0 stable) introduces significant changes, including support for Django 5.2+ and Python 3.13, and integrates with Django 5.2's `CompositePrimaryKey` for partitioned models. Users upgrading from 2.x to 3.x, especially those using partitioned models, should review the changelog carefully for potential breaking changes in model definitions and behavior.

fix

Consult the official release notes and documentation for version 3.x upon its stable release. Test thoroughly before upgrading in production environments, particularly if leveraging partitioned models or custom primary keys.

affects: 3.0.0rc1+

gotchaAutomatic `hstore` extension creation was broken for Django 4.2 or newer in `django-postgres-extra` versions prior to `2.0.9rc11` (and thus prior to `2.0.9`). If you are on an older version of `django-postgres-extra` (e.g., 2.0.8 or earlier) and using Django 4.2+, you might encounter issues with HStoreField functionality.

fix

Upgrade to `django-postgres-extra` version `2.0.9` or newer. Alternatively, if upgrading is not immediately possible, manually create the `hstore` extension in your PostgreSQL database: `CREATE EXTENSION IF NOT EXISTS hstore;`.

affects: <2.0.9

gotchaLike most Django apps, `django-postgres-extra` must be added to your `INSTALLED_APPS` setting in `settings.py`. Failing to do so will prevent its features from being registered with Django and migrations from being generated or applied correctly.

fix

Add `'pg_extra'` to your `INSTALLED_APPS` list in `settings.py`.

affects: All versions

gotchaUtilizing advanced PostgreSQL features like partitioned models, especially with custom primary keys or complex partitioning strategies, adds complexity to your application's architecture. Schema changes, migrations, and ensuring data integrity require careful planning and understanding of PostgreSQL's partitioning mechanics.

fix

Thoroughly read the `django-postgres-extra` documentation on partitioned models and PostgreSQL's native partitioning features. Plan your partitioning strategy carefully, test migrations extensively, and monitor performance after implementation.

affects: All versions

Upgrade

Version history

2.0.9latest on PyPI · released Jul 11, 2025

Audit

Dependencies

DjangorequiredCore dependency for any Django-based library, supports Django >=3.2

Agent activity

9 hits · last 30 days

node

Resources

homepagehttps://django-postgres-extra.readthedocs.io ↗