Merge branch 'doc-postgresql-slony-vale-fixes' into 'master'

Fixes vale warnings for Slony documentation

See merge request gitlab-org/gitlab!68221

doc/update/upgrading_postgresql_using_slony.md

@@ -9,23 +9,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 This guide describes the steps one can take to upgrade their PostgreSQL database
 to the latest version without the need for hours of downtime. This guide assumes
 you have two database servers: one database server running an older version of
-PostgreSQL (e.g. 9.2.18) and one server running a newer version (e.g. 9.6.0).
+PostgreSQL (for example, 9.2.18) and one server running a newer version (for example, 9.6.0).
 
-For this process we use a PostgreSQL replication tool called
-["Slony"](https://www.slony.info/). Slony allows replication between different
+For this process, a PostgreSQL replication tool called
+[Slony](https://www.slony.info/) is used. Slony allows replication between different
 PostgreSQL versions and as such can be used to upgrade a cluster with a minimal
 amount of downtime.
 
-In various places we refer to the user `gitlab-psql`. This user should be the
-user used to run the various PostgreSQL OS processes. If you're using a
-different user (e.g. `postgres`) you should replace `gitlab-psql` with the name
+This guide often refers to the user `gitlab-psql`, which is the
+user used to run the various PostgreSQL OS processes. If you are using a
+different user (for example, `postgres`), replace `gitlab-psql` with the name
 of said user. This guide also assumes your database is called
 `gitlabhq_production`. If you happen to use a different database name you should
 change this accordingly.
 
 ## Database Dumps
 
-Slony only replicates data and not any schema changes. As a result we must
+Slony only replicates data and not any schema changes. As a result you must
 ensure that all databases have the same database structure.
 
 To do so, generate a dump of the current database. This dump only
@@ -40,10 +40,9 @@ If you're not using the Omnibus GitLab package you may have to adjust the paths
 `pg_dump` and the PostgreSQL installation directory to match the paths of your
 configuration.
 
-After the structure dump is generated we also need to generate a dump for the
+After the structure dump is generated, generate another dump for the
 `schema_migrations` table. This table doesn't have any primary keys and as such
-can't be replicated easily by Slony. To generate this dump run the following
-command on your active database server:
+can't be replicated by Slony. To generate a dump of the `schema_migrations` table, run the following command on your active database server:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql/ -p 5432 -U gitlab-psql -a -t schema_migrations -f /tmp/migrations.sql gitlabhq_production
@@ -105,7 +104,7 @@ slonik version 2.2.5
 
 ## Slony User
 
-Next we must set up a PostgreSQL user that Slony can use to replicate your
+Next, set up a PostgreSQL user that Slony can use to replicate your
 database. To do so, sign in to your production database using `psql` using a
 super-user account. After signing in, run the following SQL queries:
 
@@ -123,8 +122,8 @@ later.
 
 ## Configuring Slony
 
-We can now start configuring Slony. Slony uses a configuration file for
-most of the work so we need to set this one up. This configuration file
+You can now start configuring Slony. Slony uses a configuration file for
+most of the work so it is important to set this up with care. Your configuration
 specifies where to put log files, how Slony should connect to the databases,
 etc.
 
@@ -138,11 +137,11 @@ sudo chown gitlab-psql:root /var/log/gitlab/slony /var/run/slony1 /var/opt/gitla
 ```
 
 Here `gitlab-psql` is the user used to run the PostgreSQL database processes. If
-you're using a different user you should replace this with the name of said
+you are using a different user you should replace this with the name of said
 user.
 
-Now that the directories are in place we can create the configuration file. For
-this we can use the following template:
+Now that the directories are in place you can create the configuration file
+by using the following template:
 
 ```perl
 if ($ENV{"SLONYNODES"}) {
@@ -179,15 +178,14 @@ if ($ENV{"SLONYSET"}) {
 1;
 ```
 
-In this configuration file you should replace a few placeholders before you can
-use it. The following placeholders should be replaced:
+Replace the following placeholders in this file to use it:
 
 - `OLD_HOST`: the address of the old database server.
 - `NEW_HOST`: the address of the new database server.
 - `SLONY_PASSWORD`: the password of the Slony user created earlier.
 - `TABLES`: the tables to replicate.
 
-The list of tables to replicate can be generated by running the following
+Generate the list of tables to replicate by running the following
 command on your old PostgreSQL database:
 
 ```shell
@@ -212,12 +210,12 @@ this output, don't just append it below it. The result looks like this:
 
 After you have the configuration file generated you must install it on both the
 old and new database. To do so, place it in
-`/var/opt/gitlab/postgresql/slony/slon_tools.conf` (for which we created the
+`/var/opt/gitlab/postgresql/slony/slon_tools.conf` (for which you created the
 directory earlier on).
 
-Now that the configuration file is in place we can _finally_ start replicating
-our database. First we must set up the schema in our new database. To do so make
-sure that the SQL files we generated earlier can be found in the `/tmp`
+Now that the configuration file is in place, you can _finally_ start replicating
+the database. First, set up the schema in the new database by making
+sure that the SQL files generated earlier are in the `/tmp`
 directory of the new server. After these files are in place start a `psql`
 session on this server:
 
@@ -250,8 +248,8 @@ following:
  ... more rows here ...
 ```
 
-Now we can initialize the required tables and what not that Slony uses for
-its replication process. To do so, run the following on the old database:
+Now you can initialize the required tables and other processes for
+the replication process. To do so, run the following on the old database:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slonik_init_cluster --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf | /opt/gitlab/embedded/bin/slonik
@@ -266,14 +264,14 @@ If all went well this produces something along the lines of:
 <stdin>:17: Please start a slon replication daemon for each node
 ```
 
-Next we need to start a replication node on every server. To do so, run the
+Next, start a replication node on every server. To do so, run the
 following on the old database:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 1 --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf
 ```
 
-If all went well this produces output such as:
+This should produce an output like the following:
 
 ```plaintext
 Invoke slon for node 1 - /opt/gitlab/embedded/bin/slon -p /var/run/slony1/slony_replication_node1.pid -s 1000 -d2  slony_replication 'host=192.168.0.7 dbname=gitlabhq_production user=slony port=5432 password=hieng8ezohHuCeiqu0leeghai4aeyahp' > /var/log/gitlab/slony/node1/gitlabhq_production-2016-10-06.log 2>&1 &
@@ -282,7 +280,7 @@ PID [26740]
 Start the watchdog process as well...
 ```
 
-Next we need to run the following command on the _new_ database server:
+Next, run the following command on the _new_ database server:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 2 --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf
@@ -290,14 +288,13 @@ sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 2 --conf /var/opt/gitlab
 
 This produces similar output if all went well.
 
-Next we need to tell the new database server what it should replicate. This can
-be done by running the following command on the _new_ database server:
+After Slony starts, you must tell the new database server what it should replicate. Run the following command on the _new_ database server:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slonik_create_set 1 --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf | /opt/gitlab/embedded/bin/slonik
 ```
 
-This should produce output along the lines of the following:
+This should produce an output like the following:
 
 ```plaintext
 <stdin>:11: Subscription set 1 (set1) created
@@ -310,7 +307,7 @@ This should produce output along the lines of the following:
 <stdin>:328: All tables added
 ```
 
-Finally we can start the replication process by running the following on the
+Finally, you can start the replication process by running the following on the
 _new_ database server:
 
 ```shell
@@ -357,17 +354,14 @@ main
 ```
 
 This script compares the sizes of the old and new database every minute and
-print the result to STDOUT as well as logging it to a file. Make sure to replace
+prints the results to STDOUT as well as logging it to a file. Make sure to replace
 `SLONY_PASSWORD`, `OLD_HOST`, and `NEW_HOST` with the correct values.
 
 ## Stopping Replication
 
-At some point, the two databases are in sync. If this is the case, you must plan
-for a few minutes of downtime. This small downtime window is used to stop the
-replication process, remove any Slony data from both databases, and restart
-GitLab so it can use the new database.
+Eventually, the two databases become in sync. At this point, there is a few minutes of downtime that you must plan for before the replicated database is available. During this time, the replication process should stop and all Slony data should be removed from both databases. After the replication process finishes, GitLab can restart and is able to use the newly-replicated database.
 
-First, let's stop all of GitLab. Omnibus users can do so by running the
+First, stop all of GitLab. Omnibus users can do so by running the
 following on their GitLab servers:
 
 ```shell
@@ -378,10 +372,10 @@ sudo gitlab-ctl stop mailroom
 
 If you have any other processes that use PostgreSQL, you should also stop those.
 
-After everything has been stopped, be sure to update any configuration settings
+After everything successfully stops, be sure to update any configuration settings
 and DNS records so they all point to the new database.
 
-When the settings have been taken care of, we need to stop the replication
+When the configuration is complete, stop the replication
 process. It's crucial that no new data is written to the databases at this point,
 as this data is discarded.
 
@@ -473,14 +467,14 @@ This corrects the ownership of sequences and reset the next value for the
 
 ## Removing Slony
 
-Next we need to remove all Slony related data. To do so, run the following
+The final step is to remove all Slony related data. To do so, run the following
 command on the _target_ server:
 
 ```shell
 sudo gitlab-psql gitlabhq_production -c "DROP SCHEMA _slony_replication CASCADE;"
 ```
 
-Once done you can safely remove any Slony related files (e.g. the log
+Once done you can safely remove any Slony related files (for example, the log
 directory), and uninstall Slony if desired. At this point you can start your
 GitLab instance again and if all went well it should be using your new database
 server.