django-pgbulk

3.3.0 verified Fri May 01 auth: no python

Native PostgreSQL bulk update, upsert, and copy operations for Django. Current version 3.3.0, supports Python >=3.10, Django 5.x/6.x, Postgres 12-18. Regular releases every few months.

pip install django-pgbulk

Common errors

error ModuleNotFoundError: No module named 'pgbulk' ↓

cause Installed package 'django-pgbulk' but import path is 'pgbulk'.

fix

Use from pgbulk import ...

error KeyError: 'redundant_updates' ↓

cause `redundant_updates` was renamed to `ignore_unchanged` in v3.0.0.

fix

Replace redundant_updates=True with ignore_unchanged=True.

error ValueError: fields must be provided ↓

cause Missing `fields` argument in `bulk_update`.

fix

Add fields=['field1', 'field2'] to the call.

Warnings

breaking In v3.0.0, the `redundant_updates` flag was renamed to `ignore_unchanged` and the default behavior flipped. Previously, redundant updates were skipped by default; now they are applied unless `ignore_unchanged=True`. ↓

fix Replace `redundant_updates=True` with `ignore_unchanged=True`. If you relied on the old default, set `ignore_unchanged=True` explicitly.

deprecated Python 3.9 support dropped in v3.3.0. Django 4.2 is the last version with Python 3.9 support. ↓

fix Upgrade Python to 3.10+. Use Django 4.2 LTS if stuck on Python 3.9.

gotcha The `bulk_update` function uses Postgres UPDATE FROM, which requires the model's fields list. If you omit fields, it raises `ValueError: fields must be provided`. ↓

fix Always provide the `fields` argument to `bulk_update`, e.g. `pgbulk.bulk_update(MyModel, data, fields=['name', 'age'])`

Imports

upsert

wrong

from django_pgbulk import upsert

correct

from pgbulk import upsert

The package is 'pgbulk', not 'django_pgbulk'.

copy
```
from pgbulk import copy
```

Quickstart

Bulk upsert (INSERT ... ON CONFLICT DO UPDATE) for a Django model.

from pgbulk import upsert
from myapp.models import MyModel

data = [
    {'id': 1, 'name': 'Alice', 'age': 30},
    {'id': 2, 'name': 'Bob', 'age': 25},
]
# Upsert using 'id' as conflict target
upsert(MyModel, data, conflict_target=['id'])
print('Success')