Add implementation notes on readCurrent on PostgreSQL: it does disk I…

…O. [skip ci]

docs/postgresql/index.rst

@@ -8,3 +8,16 @@
    setup
    options
    pgbouncer
+
+.. tip::
+
+   Using ZODB's ``readCurrent(ob)`` method will result in taking
+   shared locks (``SELECT FOR SHARE``) in PostgreSQL for the row
+   holding the data for *ob*.
+
+   This operation performs disk I/O, and consequently has an
+   associated cost. We recommend using this method judiciously.
+
+   For more information, see `this article on PostgreSQL
+   implementation details
+   <https://buttondown.email/nelhage/archive/22ab771c-25b4-4cd9-b316-31a86f737acc>`_.

docs/things-to-know.rst

@@ -166,3 +166,9 @@ You can also use the ``multi-zodb-gc`` script provided by the
 ``zc.zodbdgc`` project to pack a RelStorage. It does not store this
 persistent data, but it may be substantially slower than the native
 packing capabilities, especially on large databases.
+
+Use ``readCurrent(ob)`` Judiciously
+===================================
+
+At least on PostgreSQL, this involves disk I/O. See
+:doc:`postgresql/index` for more.

src/relstorage/adapters/postgresql/procs/lock_objects_and_detect_conflicts.sql

@@ -35,6 +35,11 @@ BEGIN
     -- query, even if we use that keyword, and I don't know if the
     -- keyword alone would be enough to fool it (the plan doesn't
     -- change on 11 when we use the keyword)).
+
+    -- XXX: SELECT FOR SHARE does disk I/O! This can become expensive
+    -- and possibly lead to database issues.
+    -- See https://buttondown.email/nelhage/archive/22ab771c-25b4-4cd9-b316-31a86f737acc
+    -- We document this in docs/postgresql/index.rst
     RETURN QUERY
       WITH locked AS (
         SELECT {CURRENT_OBJECT}.zoid, {CURRENT_OBJECT}.tid, t.tid AS desired