(MODULES-661) Remote DB support

Adds connection-settings (for remote DB support) when creating DB resources.

Connection-settings allows a hash of options that can be used
when connecting the a remote DB (such as PGHOST, PGPORT, PGPASSWORD
PGSSLKEY) and a special option DBVERSION indicating the version
of the remote database.

Including
- Puppet updates
- Documentation updates
- RSpec unit test updates
- RSpec acceptance test updates
- Some test coverage for connection-settings
- Working acceptance test...
    Basic vagrant setup:
    * Two boxes, server and client
    * Runs puppet code to on server to setup a postgres server that allows all connections and md5 connections, creates db puppet to look at
    * Runs puppet code on client to make a server that a psql command can be run against puppet db on other server
    * Does some fancy stuff to get the fact of the IP from the first server to connect to
- Backwards compatible, with deprecation warnings around old parameters

Author: Tom Hey

README.md

@@ -120,6 +120,43 @@ In this example, you would grant ALL privileges on the test1 database and on the
 
 At this point, you would just need to plunk these database name/username/password values into your PuppetDB config files, and you are good to go.
 
+###Managing remote users, roles and permissions
+
+Remote SQL objects are managed using the same Puppet resources as local SQL objects with the additional of a connect_settings hash. This provides control over how Puppet should connect to the remote Postgres instances and the version that should be used when generating SQL commands.
+
+When provided the connect_settings hash can contain environment variables to control Postgres client connections, such as: PGHOST, PGPORT, PGPASSWORD PGSSLKEY (see http://www.postgresql.org/docs/9.4/static/libpq-envars.html) Additionally the special value of DBVERSION can be provided to specify the target database's version. If the connect_settings hash is omitted or empty then Puppet will connect to the local Postgres instance.
+
+A connect_settings hash can be provided with each of the Puppet resources or a default connect_settings hash can be set in postgresql::globals. Per resource configuration of connect_settings allows for SQL object to be creating on multiple database by multiple users.
+
+    $connection_settings_super2 = {
+                                     'PGUSER'     => "super2",
+                                     'PGPASSWORD' => "foobar2",
+                                     'PGHOST'     => "127.0.0.1",
+                                     'PGPORT'     => "5432",
+                                     'PGDATABASE' => "postgres",
+                                  }
+
+    include postgresql::server
+
+    # Connect with no special settings, i.e domain sockets, user postges
+    postgresql::server::role{'super2':
+      password_hash => "foobar2",
+      superuser => true,
+
+      connect_settings => {},
+      require => [
+                   Class['postgresql::globals'],
+                   Class['postgresql::server::service'],
+                 ],
+    }
+
+    # Now using this new user connect via TCP
+    postgresql::server::database { 'db1':
+      connect_settings => $connection_settings_super2,
+
+      require => Postgresql::Server::Role['super2'],
+    }
+
 Reference
 ---------
 
@@ -241,6 +278,7 @@ This setting is used to specify the name of the default database to connect with
 Path to the `initdb` command.
 
 ####`createdb_path`
+**Deprecated**
 Path to the `createdb` command.
 
 ####`psql_path`
@@ -370,6 +408,7 @@ List of strings for access control for connection method, users, databases, IPv6
 Path to the `initdb` command.
 
 ####`createdb_path`
+**Deprecated**
 Path to the `createdb` command.
 
 ####`psql_path`
@@ -539,7 +578,7 @@ Value for the setting.
 
 
 ###Resource: postgresql::server::db
-This is a convenience resource that creates a database, user and assigns necessary permissions in one go.
+This is a convenience resource that creates a local database, user and assigns necessary permissions in one go.
 
 For example, to create a database called `test1` with a corresponding user of the same name, you can use:
 
@@ -612,6 +651,8 @@ Override the locale during creation of the database. Defaults to the default def
 ####`istemplate`
 Define database as a template. Defaults to `false`.
 
+####`connect_settings`
+Hash of environment variable used when connecting to a remote server. Defaults to connecting to the local Postgres instance.
 
 ###Resource: postgresql::server::database\_grant
 This defined type manages grant based access privileges for users, wrapping the `postgresql::server::database_grant` for database specific permissions. Consult the PostgreSQL documentation for `grant` for more information.
@@ -634,6 +675,8 @@ Database to execute the grant against. This should not ordinarily be changed fro
 ####`psql_user`
 OS user for running `psql`. Defaults to the default user for the module, usually `postgres`.
 
+####`connect_settings`
+Hash of environment variable used when connecting to a remote server. Defaults to connecting to the local Postgres instance.
 
 ###Resource: postgresql::server::extension
 Manages a postgresql extension.
@@ -683,6 +726,9 @@ OS user for running `psql`. Defaults to the default user for the module, usually
 ####`port`
 Port to use when connecting. Default to 'undef' which generally defaults to 5432 depending on your PostgreSQL packaging.
 
+####`connect_settings`
+Hash of environment variable used when connecting to a remote server. Defaults to connecting to the local Postgres instance.
+
 ###Resource: postgresql::server::pg\_hba\_rule
 This defined type allows you to create an access rule for `pg_hba.conf`. For more details see the [PostgreSQL documentation](http://www.postgresql.org/docs/8.2/static/auth-pg-hba-conf.html).
 
@@ -886,6 +932,9 @@ Specifies how many concurrent connections the role can make. Defaults to `-1` me
 ####`username`
 The username of the role to create, defaults to `namevar`.
 
+####`connect_settings`
+Hash of environment variable used when connecting to a remote server. Defaults to connecting to the local Postgres instance.
+
 ###Resource: postgresql::server::schema
 This defined type can be used to create a schema. For example:
 
@@ -909,6 +958,9 @@ The default owner of the schema.
 ####`schema`
 Name of the schma. Defaults to `namevar`.
 
+####`connect_settings`
+Hash of environment variable used when connecting to a remote server. Defaults to connecting to the local Postgres instance.
+
 
 ###Resource: postgresql::server::table\_grant
 This defined type manages grant based access privileges for users. Consult the PostgreSQL documentation for `grant` for more information.
@@ -934,6 +986,8 @@ Database to execute the grant against. This should not ordinarily be changed fro
 ####`psql_user`
 OS user for running `psql`. Defaults to the default user for the module, usually `postgres`.
 
+####`connect_settings`
+Hash of environment variable used when connecting to a remote server. Defaults to connecting to the local Postgres instance.
 
 ###Resource: postgresql::server::tablespace
 This defined type can be used to create a tablespace. For example:
@@ -957,8 +1011,11 @@ The default owner of the tablespace.
 ####`spcname`
 Name of the tablespace. Defaults to `namevar`.
 
+####`connect_settings`
+Hash of environment variable used when connecting to a remote server. Defaults to connecting to the local Postgres instance.
 
 ###Resource: postgresql::validate\_db\_connection
+
 This resource can be utilised inside composite manifests to validate that a client has a valid connection with a remote PostgreSQL database. It can be ran from any node where the PostgreSQL client software is installed to validate connectivity before commencing other dependent tasks in your Puppet manifests, so it is often used when chained to other tasks such as: starting an application server, performing a database migration.
 
 Example usage:
@@ -991,6 +1048,9 @@ Username to connect with. Defaults to 'undef', which when using a unix socket an
 ####`database_password`
 Password to connect with. Can be left blank, but that is not recommended.
 
+####`connect_settings`
+Hash of environment variable used when connecting to a remote server, this is an alternative to providing individual parameters (database_host, etc.). If provided the individual parameters take precedence.
+
 ####`run_as`
 The user to run the `psql` command with for authenticiation. This is important when trying to connect to a database locally using Unix sockets and `ident` authentication. It is not needed for remote testing.
 

lib/puppet/provider/postgresql_psql/ruby.rb

@@ -16,19 +16,21 @@ def run_sql_command(sql)
     command.push("-p", resource[:port]) if resource[:port]
     command.push("-t", "-c", '"' + sql.gsub('"', '\"') + '"')
 
+    environment = get_environment
+
     if resource[:cwd]
       Dir.chdir resource[:cwd] do
-        run_command(command, resource[:psql_user], resource[:psql_group])
+        run_command(command, resource[:psql_user], resource[:psql_group], environment)
       end
     else
-      run_command(command, resource[:psql_user], resource[:psql_group])
+      run_command(command, resource[:psql_user], resource[:psql_group], environment)
     end
   end
 
   private
 
   def get_environment
-    environment = {}
+    environment = resource[:connect_settings] || {}
     if envlist = resource[:environment]
       envlist = [envlist] unless envlist.is_a? Array
       envlist.each do |setting|
@@ -47,7 +49,7 @@ def get_environment
     return environment
   end
 
-  def run_command(command, user, group)
+  def run_command(command, user, group, environment)
     command = command.join ' '
     environment = get_environment
     if Puppet::PUPPETVERSION.to_f < 3.0
@@ -66,7 +68,7 @@ def run_command(command, user, group)
         :failonfail         => false,
         :combine            => true,
         :override_locale    => true,
-        :custom_environment => environment
+        :custom_environment => environment,
       })
       [output, $CHILD_STATUS.dup]
     end

lib/puppet/type/postgresql_psql.rb

@@ -62,12 +62,16 @@ def matches(value)
     end
   end
 
+  newparam(:connect_settings) do
+    desc "Connection settings that will be used when connecting to postgres"
+  end
+
   newparam(:db) do
-    desc "The name of the database to execute the SQL command against."
+    desc "The name of the database to execute the SQL command against, this overrides any PGDATABASE value in connect_settings"
   end
 
   newparam(:port) do
-    desc "The port of the database server to execute the SQL command against."
+    desc "The port of the database server to execute the SQL command against, this overrides any PGPORT value in connect_settings."
   end
 
   newparam(:search_path) do

manifests/globals.pp

@@ -1,58 +1,59 @@
 # Class for setting cross-class global overrides. See README.md for more
 # details.
 class postgresql::globals (
-  $client_package_name    = undef,
-  $server_package_name    = undef,
-  $contrib_package_name   = undef,
-  $devel_package_name     = undef,
-  $java_package_name      = undef,
-  $docs_package_name      = undef,
-  $perl_package_name      = undef,
-  $plperl_package_name    = undef,
-  $plpython_package_name  = undef,
-  $python_package_name    = undef,
-  $postgis_package_name   = undef,
+  $client_package_name      = undef,
+  $server_package_name      = undef,
+  $contrib_package_name     = undef,
+  $devel_package_name       = undef,
+  $java_package_name        = undef,
+  $docs_package_name        = undef,
+  $perl_package_name        = undef,
+  $plperl_package_name      = undef,
+  $plpython_package_name    = undef,
+  $python_package_name      = undef,
+  $postgis_package_name     = undef,
 
-  $service_name           = undef,
-  $service_provider       = undef,
-  $service_status         = undef,
-  $default_database       = undef,
+  $service_name             = undef,
+  $service_provider         = undef,
+  $service_status           = undef,
+  $default_database         = undef,
 
-  $validcon_script_path   = undef,
+  $validcon_script_path     = undef,
 
-  $initdb_path            = undef,
-  $createdb_path          = undef,
-  $psql_path              = undef,
-  $pg_hba_conf_path       = undef,
-  $pg_ident_conf_path     = undef,
-  $postgresql_conf_path   = undef,
-  $recovery_conf_path     = undef,
+  $initdb_path              = undef,
+  $createdb_path            = undef,
+  $psql_path                = undef,
+  $pg_hba_conf_path         = undef,
+  $pg_ident_conf_path       = undef,
+  $postgresql_conf_path     = undef,
+  $recovery_conf_path       = undef,
+  $default_connect_settings = undef,
 
-  $pg_hba_conf_defaults   = undef,
+  $pg_hba_conf_defaults     = undef,
 
-  $datadir                = undef,
-  $confdir                = undef,
-  $bindir                 = undef,
-  $xlogdir                = undef,
-  $logdir                 = undef,
+  $datadir                  = undef,
+  $confdir                  = undef,
+  $bindir                   = undef,
+  $xlogdir                  = undef,
+  $logdir                   = undef,
 
-  $user                   = undef,
-  $group                  = undef,
+  $user                     = undef,
+  $group                    = undef,
 
-  $version                = undef,
-  $postgis_version        = undef,
-  $repo_proxy             = undef,
+  $version                  = undef,
+  $postgis_version          = undef,
+  $repo_proxy               = undef,
 
-  $needs_initdb           = undef,
+  $needs_initdb             = undef,
 
-  $encoding               = undef,
-  $locale                 = undef,
+  $encoding                 = undef,
+  $locale                   = undef,
 
-  $manage_pg_hba_conf     = undef,
-  $manage_pg_ident_conf   = undef,
-  $manage_recovery_conf   = undef,
+  $manage_pg_hba_conf       = undef,
+  $manage_pg_ident_conf     = undef,
+  $manage_recovery_conf     = undef,
 
-  $manage_package_repo    = undef,
+  $manage_package_repo      = undef,
 ) {
   # We are determining this here, because it is needed by the package repo
   # class.

manifests/params.pp

@@ -253,7 +253,6 @@
 
   $validcon_script_path = pick($validcon_script_path, '/usr/local/bin/validate_postgresql_connection.sh')
   $initdb_path          = pick($initdb_path, "${bindir}/initdb")
-  $createdb_path        = pick($createdb_path, "${bindir}/createdb")
   $pg_hba_conf_path     = pick($pg_hba_conf_path, "${confdir}/pg_hba.conf")
   $pg_hba_conf_defaults = pick($pg_hba_conf_defaults, true)
   $pg_ident_conf_path   = pick($pg_ident_conf_path, "${confdir}/pg_ident.conf")

manifests/server.pp

@@ -63,6 +63,10 @@
     $_version = $postgresql::params::version
   }
 
+  if $createdb_path != undef{
+    warning('Passing "createdb_path" to postgresql::server is deprecated, it can be removed safely for the same behaviour')
+  }
+
   # Reload has its own ordering, specified by other defines
   class { "${pg}::reload": require => Class["${pg}::install"] }