django-pgbulk

django-pgbulk provides functions for doing native Postgres bulk upserts (i.e. UPDATE ON CONFLICT), bulk updates, and COPY FROM.

Bulk upserts can distinguish between updated/created rows and ignore unchanged updates.

Bulk updates are true bulk updates, unlike Django's bulk_update which can still suffer from O(N) queries and can create poor locking scenarios.

Bulk copies can significantly speed-up bulk inserts, sometimes by an order of magnitude over Django's bulk_create.

Quick Start

Examples

Update or insert rows

import pgbulk

pgbulk.upsert(
    MyModel,
    [
        MyModel(int_field=1, some_attr="some_val1"),
        MyModel(int_field=2, some_attr="some_val2"),
    ],
    # These are the fields that identify the uniqueness constraint.
    ["int_field"],
    # These are the fields that will be updated if the row already
    # exists. If not provided, all fields will be updated
    ["some_attr"]
)

Bulk update rows

import pgbulk

pgbulk.update(
    MyModel,
    [
        MyModel(id=1, some_attr='some_val1'),
        MyModel(id=2, some_attr='some_val2')
    ],
    # These are the fields that will be updated. If not provided,
    # all fields will be updated
    ['some_attr']
)

Copy rows into a table

import pgbulk

pgbulk.copy(
    MyModel,
    # Insert these rows using COPY FROM
    [
        MyModel(id=1, some_attr='some_val1'),
        MyModel(id=2, some_attr='some_val2')
    ],
)

Advanced Features

Here are some advanced features at a glance:

pgbulk.upsert can categorize which rows were inserted or updated.
pgbulk.upsert and pgbulk.update can ignore updating unchanged fields.
pgbulk.upsert and pgbulk.update can use expressions in updates.

Documentation

View the django-pgbulk docs here for more examples.

Compatibility

django-pgbulk is compatible with Python 3.10 - 3.14, Django 4.2 - 6.0, Psycopg 2 - 3, and Postgres 14 - 18.

Installation

Install django-pgbulk with:

pip3 install django-pgbulk

Contributing Guide

For information on setting up django-pgbulk for development and contributing changes, view CONTRIBUTING.md.

Creators

Wes Kendall

Other Contributors

@max-muoto
@dalberto

Release files for django-pgbulk 3.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-pgbulk 3.3.0
File	Size	Uploaded
django_pgbulk-3.3.0.tar.gz	11.8 kB	Nov 30, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for django-pgbulk 3.3.0
File	Interpreter	ABI	Platform	Reset
django_pgbulk-3.3.0-py3-none-any.whl 11.4 kB Nov 30, 2025	Python 3	none	any	Details

Total release size: 23.1 kB

Release files / django_pgbulk-3.3.0.tar.gz

Download URL	django_pgbulk-3.3.0.tar.gz
Size	11.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`b9d1b0cf3aef99a55ab454ec605e3c1a10f160199205ee731418421d8b64d0c1`
BLAKE2b-256 checksum How to use checksums	`f56ccac8f169c53de80cd05862a3d40b18d0885b64632a5a06c6bf9e6bed3500`
Upload date	Nov 30, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.2.1 CPython/3.14.0 Linux/6.8.0-1040-aws`

Release files / django_pgbulk-3.3.0-py3-none-any.whl

Download URL	django_pgbulk-3.3.0-py3-none-any.whl
Size	11.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1dc3dc1a9d30332139c8ddf2176987c1eea43a3e1c6546149f29d8f785506677`
BLAKE2b-256 checksum How to use checksums	`66bd8eaae104beeb8a1c210999e838985309d1b3e7ce72abebb913fa73b63031`
Upload date	Nov 30, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.2.1 CPython/3.14.0 Linux/6.8.0-1040-aws`