From d3ef4de8cc2c9f3059b94e4794516cfedb3b385c Mon Sep 17 00:00:00 2001
From: Eugen Rochko <eugen@zeonfederated.com>
Date: Sat, 25 Aug 2018 13:50:25 +0200
Subject: [PATCH] Add documentation for using read replicas (#665)

* Add documentation for using read replicas

* Update Tuning.md
---
 Running-Mastodon/Tuning.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/Running-Mastodon/Tuning.md b/Running-Mastodon/Tuning.md
index 0a2698d3..90ebdce7 100644
--- a/Running-Mastodon/Tuning.md
+++ b/Running-Mastodon/Tuning.md
@@ -7,6 +7,7 @@ Table of contents:
 - [Using pgBouncer](PgBouncer-guide.md)
 - [Using nginx proxy caching](#using-nginx-proxy-caching)
 - [Using a separate Redis for the Rails cache](#using-a-separate-redis-for-the-rails-cache)
+- [Using read replicas](#using-read-replicas)
 
 ___
 
@@ -199,3 +200,30 @@ REDIS_PORT=6379
 CACHE_REDIS_HOST=redis_cache
 CACHE_REDIS_PORT=6379
 ```
+
+## Using read replicas
+
+To reduce the load on your Postgresql server, you may wish to setup hot streaming replication (read replica). [See this guide for an example](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby). You can make use of the replica in Mastodon in these ways:
+
+- The streaming API server does not issue writes at all, so you can connect it straight to the replica. But it's not querying the database very often anyway so the impact of this is little.
+- Use the Makara driver in the web and sidekiq processes, so that writes go to the master database, while reads go to the replica. Let's talk about that.
+
+You will have to edit the `config/database.yml` file and replace the `production` section as follows:
+
+```yml
+production:
+  <<: *default
+  adapter: postgresql_makara
+  prepared_statements: false
+  makara:
+    id: postgres
+    sticky: true
+    connections:
+      - role: master
+        blacklist_duration: 0
+        url: postgresql://db_user:db_password@db_host:db_port/db_name
+      - role: slave
+        url: postgresql://db_user:db_password@db_host:db_port/db_name
+```
+
+Make sure the URLs point to wherever your PostgreSQL servers are. You can add multiple replicas. You could have a locally installed pgBouncer with configuration to connect to two different servers based on database name, e.g. "mastodon" going to master, "mastodon_replica" going to the replica, so in the file above both URLs would point to the local pgBouncer with the same user, password, host and port, but different database name. There are many possibilities how this could be setup! For more information on Makara, [see their documentation](https://github.com/taskrabbit/makara#databaseyml).