Add a troubleshooting page with help on how to work around unix domain socket issues on MacOS

Author: newhoggy

Readme.md

@@ -28,6 +28,11 @@ The database schema is highly normalised which helps prevent data inconsistencie
 with the use of foreign keys from one table to another). More user friendly database queries can be
 implemented using [Postgres Views][PostgresView] to implement joins between tables.
 
+## Troubleshooting
+
+If you have any issues with this project, consult the [troubleshooting][troubleshooting] page for
+possible solutions.
+
 ## Further Reading
 
 * [BuildingRunning][BuildingRunning]: Building and running the db-sync node.
@@ -42,3 +47,4 @@ implemented using [Postgres Views][PostgresView] to implement joins between tabl
 [PostgresView]: https://www.postgresql.org/docs/current/sql-createview.html
 [Schema Management]: doc/interesting-queries.md
 [Validation]: doc/validation.md
+[PostgresView]: doc/troubleshooting.md

doc/troubleshooting.md

@@ -0,0 +1,54 @@
+
+# Testing
+
+## Unable to connect to Unix domain socket /var/run/postgresql/.s.PGSQL.5432
+
+When running on MacOS, you get the following error:
+
+```text
+      Exception: libpq: failed (could not connect to server: No such file or directory
+      	Is the server running locally and accepting
+      	connections on Unix domain socket "/var/run/postgresql/.s.PGSQL.5432"?
+      )
+```
+
+This may indiciate that you do not have `postgres` installed, or that the `postgres`
+daemon is not running.
+
+You can install `postgres` using Homebrew using:
+
+```bash
+brew install postgres
+```
+
+And start the `postgres` daemon using:
+
+```bash
+brew services start postgresql
+```
+
+And check that it is running using:
+
+```bash
+brew services
+Name       Status  User Plist
+postgresql started jky  /Users/jky/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
+```
+
+If the daemon is running and the problem persists, then it could be because `postgres`
+is configured to create its unix domain socket on a path different to that expected by
+`cardano-db-sync`.
+
+Assuming the daemon is running, the actual path to the unix domain socket can
+be discovered by like this:
+
+```bash
+$ lsof -p "$(ps -ef | grep postgres | grep '[b]in/postgres' | xargs | cut -d ' ' -f 2)" | grep 5432
+postgres 9050  jky    7u   unix 0xb7eadc9d471eb839      0t0                     /tmp/.s.PGSQL.5432
+```
+
+We can work around the problem by sym-linking the expected path to the actual path:
+
+```bash
+sudo ln -s /tmp/.s.PGSQL.5432 /var/run/postgresql/.s.PGSQL.5432
+```