django-pg-returning

What it is and what it does

django-pg-returning bridges a gap in Django's ORM: it exposes PostgreSQL's RETURNING clause for UPDATE, DELETE, and bulk CREATE operations. Normally, Django's update() and delete() methods don't return the modified rows, and bulk_create() doesn't refresh fields with database-computed defaults or trigger-set values. This library adds QuerySet methods (update_returning, delete_returning, create_returning, bulk_create_returning) and model methods (save_returning) that execute the DML statement and immediately fetch back the affected rows, including any values computed by the database.

The result is a ReturningQuerySet—a cached, in-memory collection similar to Django's RawQuerySet but with convenience methods like count(), first(), last(), values(), and values_list(). This is especially useful when you rely on database defaults, triggers, or F() expressions to compute field values and need to know what was actually stored without issuing a separate SELECT.

Use it for:

• Retrieve auto-generated or trigger-computed values after bulk inserts without a follow-up query.
• Update records with F() expressions and immediately see the evaluated result without reloading the instance.
• Delete rows and capture their final state (e.g., for audit logging) in a single round-trip.
• Bulk operations that depend on database defaults or computed columns to populate fields.
• Workflows where you need to confirm what the database actually stored after a DML operation.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Extends Django's ORM to capture and return rows modified by PostgreSQL UPDATE, DELETE, and bulk CREATE operations, letting you retrieve database-computed values without extra queries.

Yes, if you use PostgreSQL and Django and frequently need to return modified rows from bulk operations or F() expressions. The library is stable and has no known vulnerabilities, but its dormant maintenance (last release 2024-01-04, no recent commits) means it may not support the latest Django versions—verify compatibility with your Django version before adopting. Low install friction and permissive licensing make it a low-risk experiment.

Install

django-pg-returning on PyPI

pip install django-pg-returning

uv add django-pg-returning

poetry add django-pg-returning

Installing django-pg-returning

Before you install

Low friction: pure Python wheel with only django and typing as runtime dependencies. Maintenance is dormant—last release 2024-01-04, no commits since 2024-09-19—so expect no active support or updates for new Django versions.

License in practice

BSD 3-clause permissive license; you may use, modify, and distribute freely with attribution and no warranty.

Quickstart

pip install django-pg-returning

from django_pg_returning import UpdateReturningModel
from django.db import models

class MyModel(UpdateReturningModel):
    field = models.IntegerField()

result = MyModel.objects.all().update_returning(field=1)
print(result.count())

Requires PostgreSQL 9.4+, psycopg2 or psycopg2-binary (not installed by this package), and Django 1.8+. Some features require Django 1.10+.

Verify before relying

• Whether the library works with current Django versions (4.x, 5.x) given dormant maintenance status.
• Compatibility with modern psycopg versions (3.x) and whether psycopg2 is still the expected adapter.
• Performance characteristics when returning large result sets or with complex F() expressions.

Package facts

Evidence: django_pg_returning-2.0.2-py2.py3-none-any.whl

Tags

More Database packages