From a8c03340844dd686c3aba2ea3955f883598736ed Mon Sep 17 00:00:00 2001
From: Benjamin Moss <drteeth@gmail.com>
Date: Sat, 30 Nov 2024 20:32:29 -0500
Subject: [PATCH] Copy wiki documents into the Guides

---
 guides/Architecture.md | 15 +++++++++++++++
 guides/FAQ.md          | 34 ++++++++++++++++++++++++++++++++++
 mix.exs                |  2 ++
 3 files changed, 51 insertions(+)
 create mode 100644 guides/Architecture.md
 create mode 100644 guides/FAQ.md

diff --git a/guides/Architecture.md b/guides/Architecture.md
new file mode 100644
index 00000000..49824631
--- /dev/null
+++ b/guides/Architecture.md
@@ -0,0 +1,15 @@
+### PostgreSQL usage
+
+EventStore creates multiple connections to the Postres database:
+
+- a pooled connection, that you configure via `config/config.exs`, used for most database operations (e.g. reading/appending events);
+- a connection used to listen for event notifications (using Postgres' `LISTEN` / `NOTIFY`);
+- and another connection for subscription [advisory locks](https://www.postgresql.org/docs/current/static/explicit-locking.html#ADVISORY-LOCKS).
+
+If you configure EventStore to use a `pool_size` of 10, then you will have 12 Postgres database connections in total.
+
+The pooled connection uses `:exp` back-off. However the other connections use `:stop` back-off so that the connection process terminates when the database connection is broken. These connections are monitored by another process and will be restarted.
+
+#### Why are these connections stopped on error?
+
+Related processes need to be notified when the connection exits or is restarted. The [postgrex](https://hexdocs.pm/postgrex/) library doesn't provide a way of being notified when the connection terminates. As an example, EventStore uses [Postgres' advisory locks](https://www.postgresql.org/docs/current/static/explicit-locking.html#ADVISORY-LOCKS) to guarantee only one instance of a subscription runs, regardless of how many nodes are running (or whether they are clustered). These advisory locks are tied to a database connection and are released when the connection terminates. When this happens, EventStore attempts to reacquire the locks. The `EventStore.MonitoredServer` module provides this process monitoring and `after_exit` and `after_restart` callback functions.
diff --git a/guides/FAQ.md b/guides/FAQ.md
new file mode 100644
index 00000000..05e5793b
--- /dev/null
+++ b/guides/FAQ.md
@@ -0,0 +1,34 @@
+## Frequently asked questions
+
+- [What version of PostgreSQL is supported?](#what-version-of-postgresql-is-supported)
+- [Which PostgreSQL hosting provider is supported?](#which-postgresql-hosting-provider-is-supported)
+
+---
+
+### What version of PostgreSQL is supported?
+
+PostgreSQL v9.5 or later.
+
+---
+
+### Which PostgreSQL hosting provider is supported?
+
+You can verify a potential hosting provider by running the EventStore test suite against an instance of the hosted PostgreSQL database. If all tests pass, then you should be fine.
+
+To run the test suite you must first clone this GitHub repository:
+
+```console
+git clone https://github.com/commanded/eventstore.git
+cd eventstore
+mix deps.get
+```
+
+Then configure your database connection settings for the test environment, in `config/test.exs`.
+
+Once configured, you can create the test database and run the tests:
+
+```console
+MIX_ENV=test mix do event_store.create, event_store.init
+mix test
+```
+
diff --git a/mix.exs b/mix.exs
index 6d2b7e76..9d98c853 100644
--- a/mix.exs
+++ b/mix.exs
@@ -73,6 +73,8 @@ defmodule EventStore.Mixfile do
         "guides/Subscriptions.md",
         "guides/Cluster.md",
         "guides/Event Serialization.md",
+        "guides/Architecture.md",
+        "guides/FAQ.md",
         "guides/Upgrades.md",
         "guides/upgrades/0.17-1.0.md": [
           filename: "0.17-1.0",