From b4139ed6eaa430874360a3a98e85bd2c91e19bc7 Mon Sep 17 00:00:00 2001
From: daniel a rios <misterrios@gmail.com>
Date: Fri, 26 Jul 2019 15:11:48 +0200
Subject: [PATCH] [2.2.x] Refs #30656 -- Reorganized bulk methods in the
 database optimization docs.

Backport of fe33fdc049df75f9dd8e2eecc8c94aefc0132cb8 from master
---
 docs/topics/db/optimization.txt | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt
index 671f57a8ae..0f39fae103 100644
--- a/docs/topics/db/optimization.txt
+++ b/docs/topics/db/optimization.txt
@@ -341,8 +341,13 @@ it on a ``QuerySet`` by calling
 
 Adding an index to your database may help to improve ordering performance.
 
-Insert in bulk
-==============
+Use bulk methods
+================
+
+Use bulk methods to reduce the number of SQL statements.
+
+Create in bulk
+--------------
 
 When creating objects, where possible, use the
 :meth:`~django.db.models.query.QuerySet.bulk_create()` method to reduce the
@@ -362,8 +367,13 @@ Note that there are a number of :meth:`caveats to this method
 <django.db.models.query.QuerySet.bulk_create>`, so make sure it's appropriate
 for your use case.
 
-This also applies to :class:`ManyToManyFields
-<django.db.models.ManyToManyField>`, so doing::
+Insert in bulk
+--------------
+
+When inserting objects into :class:`ManyToManyFields
+<django.db.models.ManyToManyField>`, use
+:meth:`~django.db.models.fields.related.RelatedManager.add` with multiple
+objects to reduce the number of SQL queries. For example::
 
     my_band.members.add(me, my_friend)