django-bulk-update is a Django library that enables efficient bulk updates of multiple model instances using a single database query. It significantly improves performance compared to iterating and calling `save()` on each object individually. The current version is 2.2.0, and the project maintains an active but not rapid release cadence, ensuring compatibility with recent Django versions.
pip install django-bulk-updateVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to integrate `BulkUpdateManager` into a Django model, create initial instances using `bulk_create`, modify these instances in memory, and then efficiently persist changes to specific fields across all modified objects using a single `bulk_update` query. It includes a complete, runnable standalone Django setup with an in-memory SQLite database.
If you relied on `on_conflict`, you must manually implement conflict resolution logic or re-evaluate your update strategy. For simple 'ignore duplicates' cases with `bulk_create` (not `bulk_update`), consider using `ignore_duplicates=True`.
Always explicitly list only the fields that *must* be updated in `update_fields`. This optimizes the generated SQL query and prevents unintended updates to other fields.
If related objects require updating, perform those operations separately using standard ORM methods or other bulk operations specifically for those related models.
Manage the `update_fields` argument carefully. If you only want to update fields that have genuinely changed, you need to implement your own dirty tracking logic or filter the list of objects and fields before calling `bulk_update`.
First, retrieve the model instances into a list, modify them as needed, and then pass that list of instances to `bulk_update`.
```python
# Incorrect
# MyModel.objects.filter(some_field=value).bulk_update([...])
# Correct
my_objects = list(MyModel.objects.filter(some_field=value))
for obj in my_objects:
obj.field_to_update = new_value
MyModel.objects.bulk_update(my_objects, ['field_to_update'])
```Ensure that all model instances provided to `bulk_update` have already been saved to the database and possess a primary key. For creating multiple new objects in a single query, use `Model.objects.bulk_create()` instead. ```python # Incorrect (if 'new_obj' hasn't been saved yet) # MyModel.objects.bulk_update([new_obj], ['field_name']) # Correct (for updating existing objects) existing_obj = MyModel.objects.get(pk=1) existing_obj.field_name = 'updated_value' MyModel.objects.bulk_update([existing_obj], ['field_name']) # Correct (for creating new objects) new_obj_1 = MyModel(field_name='value1') new_obj_2 = MyModel(field_name='value2') MyModel.objects.bulk_create([new_obj_1, new_obj_2]) ```
First, ensure the library is installed in your environment: ```bash pip install django-bulk-update==2.2.0 ``` Then, import the `bulk_update` function from its correct location: ```python from django_bulk_update.helper import bulk_update ```
If using Django's built-in `bulk_update`, call it on a `QuerySet`. If using `django-bulk-update`'s helper, import it and pass a list of instances.
```python
# Incorrect
# MyModel.objects.bulk_update(my_objects, ['field_name'])
# Correct (using Django's built-in bulk_update on a QuerySet)
my_objects = list(MyModel.objects.filter(some_condition=True))
for obj in my_objects:
obj.field_name = 'new_value'
MyModel.objects.bulk_update(my_objects, ['field_name'])
# Correct (using django-bulk-update helper)
from django_bulk_update.helper import bulk_update
my_objects = list(MyModel.objects.filter(some_condition=True))
for obj in my_objects:
obj.field_name = 'new_value'
bulk_update(my_objects, update_fields=['field_name'])
```