Merge ~jugmac00/launchpad:create-preserving-query-count-how-to into launchpad:master

[Jürgen Gmach]

Create `Preserving query count` how-to

[Colin Watson (cjwatson)]

review: Needs Fixing

[Jürgen Gmach (jugmac00)]

Thanks for the review!

I have replaced my example with code using the mentioned `record_two_runs` function.

As `test_getBuildSummariesForSnapBuildIds_query_count` uses both an inline function definition and a context manager, I looked around and found a simpler test function.

If you have a minute, please review again.

[Colin Watson (cjwatson)]

review: Approve

diff --git a/doc/how-to/preserve-query-count.rst b/doc/how-to/preserve-query-count.rst
new file mode 100644
index 0000000..2b8e180
--- /dev/null
+++ b/doc/how-to/preserve-query-count.rst
@@ -0,0 +1,24 @@
+======================
+Preserving query count
+======================
+
+Given you want to read or create many items instead of one,
+you need to make sure that the number of queries stays constant.
+
+In Launchpad this can be done by using `lp.testing.record_two_runs`,
+as outlined in the following example:
+
+.. code-block:: python
+
+    def test_view_query_count(self):
+        # Test that the view bulk loads artifacts.
+        person = self.factory.makePerson()
+        pillarperson = PillarPerson(self.pillar, person)
+        recorder1, recorder2 = record_two_runs(
+            tested_method=lambda: create_initialized_view(pillarperson, '+index'),
+            item_creator=lambda: self.makeArtifactGrantee(person, True, True, True, False),
+            first_round_number=5,
+            login_method=lambda: login_person(self.owner))
+        self.assertThat(recorder2, HasQueryCount.byEquality(recorder1))
+
+For further information, please have a look at `record_two_runs`' docstring.
diff --git a/doc/index.rst b/doc/index.rst
index aad3908..6e7f32e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -36,6 +36,7 @@ How-to Guides
    how-to/apply-schema-changes
    how-to/use-updated-dependency
    how-to/resurrect-dogfood
+   how-to/preserve-query-count
 
 Explanation
 ===========