Merge branch '10-2-postgres_fdw' into 'master'

Postgres FDW documentation

See merge request gitlab-org/gitlab-ee!3076

doc/gitlab-geo/database.md

@@ -22,7 +22,6 @@ You are encouraged to first read through all the steps before executing them
 in your testing/production environment.
 
 
-
 ## PostgreSQL replication
 
 The GitLab primary node where the write operations happen will connect to
@@ -40,8 +39,9 @@ recover. See below for more details.
 
 The following guide assumes that:
 
-- You are using Omnibus and therefore you are using PostgreSQL 9.6 or later
- which includes the [`pg_basebackup` tool][pgback].
+- You are using Omnibus and therefore you are using PostgreSQL 9.6 or later 
+  which includes the  [`pg_basebackup` tool][pgback] and improved 
+  [Foreign Data Wrapper][FDW] support. 
 - You have a primary node already set up (the GitLab server you are
   replicating from), running Omnibus' PostgreSQL (or equivalent version), and
   you have a new secondary server set up with the same versions of the OS,
@@ -67,10 +67,31 @@ The following guide assumes that:
     ```
 
     This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`.
+    
+1. Make sure your the `gitlab` database user has a password defined
+
+   Generate a MD5 hash of the desired password:
+   
+   ```bash
+   gitlab-ctl pg-password-md5 gitlab
+   # Enter password: mypassword
+   # Confirm password: mypassword
+   # fca0b89a972d69f00eb3ec98a5838484
+   ```
+   
+   Edit `/etc/gitlab/gitlab.rb`:
+   
+   ```ruby
+   # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` 
+   postgresql['sql_user_password'] = 'fca0b89a972d69f00eb3ec98a5838484'
+
+   # If you have HA setup, this must be present in all nodes as well
+   gitlab_rails['db_password'] = 'mypassword'
+   ```
 
 1. Omnibus GitLab already has a [replication user](https://wiki.postgresql.org/wiki/Streaming_Replication)
- called `gitlab_replicator`. You must set the password for this user manually.
- You will be prompted to enter a password:
+   called `gitlab_replicator`. You must set the password for this user manually.
+   You will be prompted to enter a password:
 
     ```bash
     gitlab-ctl set-replication-password
@@ -295,6 +316,27 @@ because we have not yet configured the secondary server. This is the next step.
     connections. The certificate can only be replicated by someone with access
     to the private key, which is **only** present on the primary node.
 
+1. Configure PostgreSQL to listen on network interfaces on secondary
+
+    This step is similar to how we configured the primary instance.
+    We need to enable this, even if using a single node, to enable FDW support.
+    
+    Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP
+        addresses with addresses appropriate to your network configuration:
+    
+        ```ruby
+        geo_primary_role['enable'] = true
+    
+        # Secondary addresses
+        # - replace '5.6.7.8' with the secondary public address
+        postgresql['listen_address'] = '5.6.7.8'
+        postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','5.6.7.8/32']
+        postgresql['md5_auth_cidr_addresses'] = ['5.6.7.8/32']
+        
+        # gitlab database user's password (defined previously)
+        gitlab_rails['db_password'] = 'mypassword'
+        ```
+
 1. Test that the `gitlab-psql` user can connect to the primary's database:
 
     ```bash

doc/gitlab-geo/database_source.md

@@ -34,7 +34,8 @@ recover. See below for more details.
 The following guide assumes that:
 
 - You are using PostgreSQL 9.6 or later
-  which includes the [`pg_basebackup` tool][pgback].
+  which includes the
+  [`pg_basebackup` tool][pgback] and improved [Foreign Data Wrapper][FDW] support. 
 - You have a primary node already set up (the GitLab server you are
   replicating from), running PostgreSQL 9.6 or later, and
   you have a new secondary server set up with the same versions of the OS,
@@ -58,11 +59,33 @@ The following guide assumes that:
     bundle exec rake geo:set_primary_node
     ```
 
-1. Create a [replication user](https://wiki.postgresql.org/wiki/Streaming_Replication) named `gitlab_replicator`:
+1. Create a [replication user] named `gitlab_replicator`:
 
     ```bash
     sudo -u postgres psql -c "CREATE USER gitlab_replicator REPLICATION ENCRYPTED PASSWORD 'thepassword';"
     ```
+    
+1. Make sure your the `gitlab` database user has a password defined
+
+    ```bash
+    sudo -u postgres psql -d template1 -c "ALTER USER gitlab WITH ENCRYPTED PASSWORD 'mydatabasepassword';"
+    ```
+    
+1. Edit the content of `database.yml` in `production:` and add the password like the exemple below:
+
+    ```yaml
+    #
+    # PRODUCTION
+    #
+    production:
+      adapter: postgresql
+      encoding: unicode
+      database: gitlabhq_production
+      pool: 10
+      username: gitlab
+      password: mydatabasepassword
+      host: /var/opt/gitlab/geo-postgresql
+    ```
 
 1. Set up TLS support for the PostgreSQL primary server
 
@@ -166,7 +189,7 @@ The following guide assumes that:
 
 1. Create the replication slot on the primary:
 
-    ```
+    ```bash
     $ sudo -u postgres psql -c "SELECT * FROM pg_create_physical_replication_slot('secondary_example');"
       slot_name         | xlog_position
       ------------------+---------------
@@ -264,6 +287,33 @@ node.
     bundle exec rake geo:db:migrate
     ```
 
+1. Configure the [PostgreSQL FDW][FDW] connection and credentials:
+
+    Save the script below in a file, ex. `/tmp/geo_fdw.sh` and modify the connection
+    params to match your environment.
+    
+    ```bash
+    #!/bin/bash
+ 
+    # Secondary Database connection params:
+    DB_HOST="/var/opt/gitlab/postgresql"
+    DB_NAME="gitlabhq_production"
+    DB_USER="gitlab"
+    DB_PORT="5432"
+    
+    # Tracking Database connection params:
+    GEO_DB_HOST="/var/opt/gitlab/geo-postgresql"
+    GEO_DB_NAME="gitlabhq_geo_production"
+    GEO_DB_USER="gitlab_geo"
+    GEO_DB_PORT="5432"
+ 
+    sudo -u postgres psql -h $GEO_DB_HOST -d $GEO_DB_NAME -p $GEO_DB_PORT -c "CREATE EXTENSION postgres_fdw;"
+    sudo -u postgres psql -h $GEO_DB_HOST -d $GEO_DB_NAME -p $GEO_DB_PORT -c "CREATE SERVER gitlab_secondary FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host '$(DB_HOST)', dbname '$(DB_NAME)', port '$(DB_PORT)' );"
+    sudo -u postgres psql -h $GEO_DB_HOST -d $GEO_DB_NAME -p $GEO_DB_PORT -c "CREATE USER MAPPING FOR $(GEO_DB_USER) SERVER gitlab_secondary OPTIONS (user '$(DB_USER)');"
+    sudo -u postgres psql -h $GEO_DB_HOST -d $GEO_DB_NAME -p $GEO_DB_PORT -c "CREATE SCHEMA gitlab_secondary;"
+    sudo -u postgres psql -h $GEO_DB_HOST -d $GEO_DB_NAME -p $GEO_DB_PORT -c "GRANT USAGE ON FOREIGN SERVER gitlab_secondary TO $(GEO_DB_USER);"
+    ```
+
 ### Step 4. Initiate the replication process
 
 Below we provide a script that connects the database on the secondary node to
@@ -279,7 +329,7 @@ data before running `pg_basebackup`.
 
 1. SSH into your GitLab **secondary** server and login as root:
 
-    ```
+    ```bash
     sudo -i
     ```
 
@@ -333,7 +383,7 @@ data before running `pg_basebackup`.
 
 1. Run it with:
 
-    ```
+    ```bash
     bash /tmp/replica.sh
     ```
 
@@ -361,4 +411,6 @@ MySQL replication is not supported for GitLab Geo.
 Read the [troubleshooting document](troubleshooting.md).
 
 [pgback]: http://www.postgresql.org/docs/9.6/static/app-pgbasebackup.html
+[replication user]:https://wiki.postgresql.org/wiki/Streaming_Replication
+[FDW]: https://www.postgresql.org/docs/9.6/static/postgres-fdw.html
 [toc]: README.md#using-gitlab-installed-from-source

lib/tasks/migrate/setup_postgresql.rake

@@ -16,3 +16,18 @@ task setup_postgresql: :environment do
   AddLowerPathIndexToRedirectRoutes.new.up
   IndexRedirectRoutesPathForLike.new.up
 end
+
+desc 'GitLab | Generate PostgreSQL Password Hash'
+task :postgresql_md5_hash do
+  require 'digest'
+  username = ENV.fetch('USERNAME') do |missing|
+    puts "You must provide an username with '#{missing}' ENV variable"
+    exit(1)
+  end
+  password = ENV.fetch('PASSWORD') do |missing|
+    puts "You must provide a password with '#{missing}' ENV variable"
+    exit(1)
+  end
+  hash = Digest::MD5.hexdigest("#{password}#{username}")
+  puts "The MD5 hash of your database password for user: #{username} -> #{hash}"
+end