django-postgres-extra

Warnings

• breaking Version 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.
• gotcha Automatic `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;`.
• gotcha Like 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`.
• gotcha Utilizing 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.

Install

• pip install django-postgres-extra Install stable version
• pip install django-postgres-extra==3.0.0rc1 Install release candidate (Django 5.2+)

Imports

• HStoreField

  from pg_extra.fields import HStoreField

• PostgreSQLPartitionedModel
  wrong:

  from pg_extra.partitioned_models import PostgreSQLPartitionedModel

  correct:

  from pg_extra.models import PostgreSQLPartitionedModel

  Partitioned models moved under pg_extra.models for Django 3.0+
• PostgreSQLQuerySet

  from pg_extra.query import PostgreSQLQuerySet

Quickstart

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}")