document shared memory segment issue (#6546)

document shared memory segment issue

After discussion with @SamirTalwar-DA, we agree the CI script to clear
memory segments is a bit too dangerous to make it easy to run on
developer machines. Still, developers may run into similar issues if
they run lots of tests and/or do not reboot their laptop frequently.
On developer laptops, we  usually spawn one PostgreSQL instance per
build/test that needs it (as opposed to CI where we create a single one
for the entire build; see `build.sh`), so they can actually build up
fairly quickly in some scenarios.

As an alternative, I have added a section to the README to cover what to
do if that issue happens.

CHANGELOG_BEGIN
CHANGELOG_END

README.md

@@ -112,6 +112,42 @@ If you work with multiple copies of this repository, you can point all of them t
 by overwriting these configs in either a `.bazelrc.local` file in each copy, or a `~/.bazelrc` file
 in your home directory.
 
+### Shared memory segment issues
+
+On macOS at least, it looks like our setup does not always properly close the
+resources PostgreSQL uses. After a number of test runs, you may encounter an
+error message along the lines of:
+
+```
+FATAL:  could not create shared memory segment: No space left on device
+DETAIL:  Failed system call was shmget(key=5432001, size=56, 03600).
+HINT:  This error does *not* mean that you have run out of disk space. It occurs either if all available shared memory IDs have been taken, in which case you need to raise the SHMMNI parameter in your kernel, or because the system's overall limit for shared memory has been reached.
+        The PostgreSQL documentation contains more information about shared memory configuration.
+child process exited with exit code 1
+```
+
+In this case, this is a memory leak, so increasing `SHMNI` (or `SHMALL` etc.)
+as suggested will only delay the issue. You can look at the existing shared
+memory segments on your system by running `ipcs -mcopt`; this will print a line
+per segment, indicating the process ID of the last process to connect to the
+segment as well as the last access time and the number of currently connected
+processes.
+
+If you identify segments with no connected processes, and you are confident you
+can remove them, you can do so with `ipcrm $sid`, where `$sid` is the process
+ID displayed (as the second column) by `ipcs`. Not many macOS applications use
+shared memory segments; **if you have verified that all the existing memory
+segments on your machine need to be deleted**, e.g. because they have all been
+created by PostgreSQL instances that are no longer running, here is a Bash
+invocation you can use to remove all shared memory segments from your system.
+
+**This is a dangerous command. Make sure you understand what it does before
+running it.**
+
+```
+for shmid in $(ipcs -m | sed 1,3d | awk '{print $2}' | sed '$d'); do ipcrm -m $shmid; done
+```
+
 
 ### Haskell profiling builds
 

ci/clear-shared-segments-macos.yml

@@ -28,5 +28,12 @@
 steps:
 - bash: |
     set -euo pipefail
-      for shmid in $(ipcs -m | sed 1,3d | awk '{print $2}' | sed '$d'); do ipcrm -m $shmid; done
+
+    # ipcs -m prints a three-line human-friendly header then all memory
+    # segments in a tabular format. The second column holds the segment IDs,
+    # which is what ipcrm expects as its arguments. After the table, ipcs -m
+    # adds an extra blank line, hence the extra sed at the end.
+    for shmid in $(ipcs -m | sed 1,3d | awk '{print $2}' | sed '$d'); do
+        ipcrm -m $shmid
+    done
   name: clear_shm