1 line
17 KiB
JSON
1 line
17 KiB
JSON
{"name":"postgresql","version":"6.1.1","description":"Installs and configures postgresql for clients or servers","long_description":"# postgresql cookbook\n\n[](https://travis-ci.org/sous-chefs/postgresql) [](https://supermarket.chef.io/cookbooks/postgresql)\n\nInstalls and configures PostgreSQL as a client or a server.\n\n## Requirements\n\n### Platforms\n\n- Debian 7+\n- Ubuntu 12.04+\n- Red Hat/CentOS/Scientific (6.0+ required) - \"EL6-family\"\n- Fedora\n- SLES 12+\n- openSUSE 13+ / openSUSE Leap\n\n### Chef\n\n- Chef 12.1+\n\n### Cookbooks\n\n- `compat_resource`\n- `openssl`\n- `build-essential`\n\n## Attributes\n\nThe following attributes are set based on the platform, see the `attributes/default.rb` file for default values.\n\n- `node['postgresql']['version']` - version of postgresql to manage\n- `node['postgresql']['dir']` - home directory of where postgresql data and configuration lives.\n- `node['postgresql']['client']['packages']` - An array of package names that should be installed on \"client\" systems.\n- `node['postgresql']['server']['packages']` - An array of package names that should be installed on \"server\" systems.\n- `node['postgresql']['server']['config_change_notify']` - Type of notification triggered when a config file changes.\n- `node['postgresql']['contrib']['packages']` - An array of package names that could be installed on \"server\" systems for useful sysadmin tools.\n- `node['postgresql']['enable_pgdg_apt']` - Whether to enable the apt repo by the PostgreSQL Global Development Group, which contains newer versions of PostgreSQL.\n- `node['postgresql']['enable_pgdg_yum']` - Whether to enable the yum repo by the PostgreSQL Global Development Group, which contains newer versions of PostgreSQL.\n- `node['postgresql']['initdb_locale']` - Sets the default locale for the database cluster. If this attribute is not specified, the locale is inherited from the environment that initdb runs in. Sometimes you must have a system locale that is not what you want for your database cluster, and this attribute addresses that scenario. Valid only for EL-family distros (RedHat/Centos/etc.).\n\nThe following attributes are generated in `recipe[postgresql::server]`.\n\n## Configuration\n\nThe `postgresql.conf` and `pg_hba.conf` files are dynamically generated from attributes. Each key in `node['postgresql']['config']` is a postgresql configuration directive, and will be rendered in the config file. For example, the attribute:\n\n```ruby\nnode['postgresql']['config']['listen_addresses'] = 'localhost'\n```\n\nWill result in the following line in the `postgresql.conf` file:\n\n```ruby\nlisten_addresses = 'localhost'\n```\n\nThe attributes file contains default values for Debian and RHEL platform families (per the `node['platform_family']`). These defaults have disparity between the platforms because they were originally extracted from the postgresql.conf files in the previous version of this cookbook, which differed in their default config. The resulting configuration files will be the same as before, but the content will be dynamically rendered from the attributes. The helpful commentary will no longer be present. You should consult the PostgreSQL documentation for specific configuration details.\n\nSee **Recipes** `config_initdb` and `config_pgtune` below to auto-generate many postgresql.conf settings.\n\nFor values that are \"on\" or \"off\", they should be specified as literal `true` or `false`. String values will be used with single quotes. Any configuration option set to the literal `nil` will be skipped entirely. All other values (e.g., numeric literals) will be used as is. So for example:\n\n```ruby\nnode.default['postgresql']['config']['logging_collector'] = true\nnode.default['postgresql']['config']['datestyle'] = 'iso, mdy'\nnode.default['postgresql']['config']['ident_file'] = nil\nnode.default['postgresql']['config']['port'] = 5432\n```\n\nWill result in the following config lines:\n\n```ruby\nlogging_collector = 'on'\ndatestyle = 'iso,mdy'\nport = 5432\n```\n\n(no line printed for `ident_file` as it is `nil`)\n\nNote that the `unix_socket_directory` configuration was renamed to `unix_socket_directories` in Postgres 9.3 so make sure to use the `node['postgresql']['unix_socket_directories']` attribute instead of `node['postgresql']['unix_socket_directory']`.\n\nThe `pg_hba.conf` file is dynamically generated from the `node['postgresql']['pg_hba']` attribute. This attribute must be an array of hashes, each hash containing the authorization data. As it is an array, you can append to it in your own recipes. The hash keys in the array must be symbols. Each hash will be written as a line in `pg_hba.conf`. For example, this entry from `node['postgresql']['pg_hba']`:\n\n```\n[{:comment => '# Optional comment',\n:type => 'local', :db => 'all', :user => 'postgres', :addr => nil, :method => 'md5'}]\n```\n\nWill result in the following line in `pg_hba.conf`:\n\n```\n# Optional comment\nlocal all postgres md5\n```\n\nUse `nil` if the CIDR-ADDRESS should be empty (as above). Don't provide a comment if none is desired in the `pg_hba.conf` file.\n\nNote that the following authorization rule is supplied automatically by the cookbook template. The cookbook needs this to execute SQL in the PostgreSQL server without supplying the clear-text password (which isn't known by the cookbook). Therefore, your `node['postgresql']['pg_hba']` attributes don't need to specify this authorization rule:\n\n```\n# \"local\" is for Unix domain socket connections only\nlocal all all ident\n```\n\n(By the way, the template uses `peer` instead of `ident` for PostgreSQL-9.1 and above, which has the same effect.)\n\n## Recipes\n\n### default\n\nIncludes the client recipe.\n\n### client\n\nInstalls the packages defined in the `node['postgresql']['client']['packages']` attribute.\n\n### ruby\n\nInstall the `pg` gem under Chef's Ruby environment so it can be used in other recipes. The build-essential packages and postgresql client packages will be installed during the compile phase, so that the native extensions of `pg` can be compiled.\n\n### server\n\nIncludes the `server_debian` or `server_redhat` recipe to get the appropriate server packages installed and service managed. Also manages the configuration for the server:\n\n- generates a strong default password (via `openssl`) for `postgres`\n- sets the password for postgres\n- manages the `postgresql.conf` file.\n- manages the `pg_hba.conf` file.\n\n### config_initdb\n\nTakes locale and timezone settings from the system configuration. This recipe creates `node.default['postgresql']['config']` attributes that conform to the system's locale and timezone. In addition, this recipe creates the same error reporting and logging settings that `initdb` provided: a rotation of 7 days of log files named postgresql-Mon.log, etc.\n\nThe default attributes created by this recipe are easy to override with normal attributes because of Chef attribute precedence. For example, suppose a DBA wanted to keep log files indefinitely, rolling over daily or when growing to 10MB. The Chef installation could include the `postgresql::config_initdb` recipe for the locale and timezone settings, but customize the logging settings with these node JSON attributes:\n\n```javascript\n\"postgresql\": {\n \"config\": {\n \"log_rotation_age\": \"1d\",\n \"log_rotation_size\": \"10MB\",\n \"log_filename\": \"postgresql-%Y-%m-%d_%H%M%S.log\"\n }\n}\n```\n\nCredits: This `postgresql::config_initdb` recipe is based on algorithms in the [source code](http://doxygen.postgresql.org/initdb_8c_source.html) for the PostgreSQL `initdb` utility.\n\n### config_pgtune\n\nPerformance tuning. Takes the wimpy default postgresql.conf and expands the database server to be as powerful as the hardware it's being deployed on. This recipe creates a baseline configuration of `node.default['postgresql']['config']` attributes in the right general range for a dedicated Postgresql system. Most installations won't need additional performance tuning.\n\nThe only decision you need to make is to choose a `db_type` from the following database workloads. (See the recipe code comments for more detailed descriptions.)\n\n- \"dw\" -- Data Warehouse\n- \"oltp\" -- Online Transaction Processing\n- \"web\" -- Web Application\n- \"mixed\" -- Mixed DW and OLTP characteristics\n- \"desktop\" -- Not a dedicated database\n\nThis recipe uses a performance model with three input parameters. These node attributes are completely optional, but it is obviously important to choose the `db_type` correctly:\n\n- `node['postgresql']['config_pgtune']['db_type']` -- Specifies database type from the list of five choices above. If not specified, the default is \"mixed\".\n\n- `node['postgresql']['config_pgtune']['max_connections']` -- Specifies maximum number of connections expected. If not specified, it depends on database type: \"web\":200, \"oltp\":300, \"dw\":20, \"mixed\":80, \"desktop\":5\n\n- `node['postgresql']['config_pgtune']['total_memory']` -- Specifies total system memory in kB. (E.g., \"49416564kB\".) If not specified, it will be taken from Ohai automatic attributes. This could be used to tune a system that isn't a dedicated database.\n\nThe default attributes created by this recipe are easy to override with normal attributes because of Chef attribute precedence. For example, if you are running application benchmarks to try different buffer cache sizes, you would experiment with this node JSON attribute:\n\n```javascript\n\"postgresql\": {\n \"config\": {\n \"shared_buffers\": \"3GB\"\n }\n}\n```\n\nNote that the recipe uses `max_connections` in its computations. If you want to override that setting, you should specify `node['postgresql']['config_pgtune']['max_connections']` instead of `node['postgresql']['config']['max_connections']`.\n\nCredits: This `postgresql::config_pgtune` recipe is based on the [pgtune python script](https://github.com/gregs1104/pgtune) developed by [Greg Smith](http://notemagnet.blogspot.com/2008/11/automating-initial-postgresqlconf.html) and [other pgsql-hackers](http://www.postgresql.org/message-id/491C6CDC.8090506@agliodbs.com).\n\n### contrib\n\nInstalls the packages defined in the `node['postgresql']['contrib']['packages']` attribute. The contrib directory of the PostgreSQL distribution includes porting tools, analysis utilities, and plug-in features that database engineers often require. Some (like `pgbench`) are executable. Others (like `pg_buffercache`) would need to be installed into the database.\n\nAlso installs any contrib module extensions defined in the `node['postgresql']['contrib']['extensions']` attribute. These will be available in any subsequently created databases in the cluster, because they will be installed into the `template1` database using the `CREATE EXTENSION` command. For example, it is often necessary/helpful for problem troubleshooting and maintenance planning to install the views and functions in these [standard instrumentation extensions] ([http://www.postgresql.org/message-id/flat/4DC32600.6080900@pgexperts.com#4DD3D6C6.5060006@2ndquadrant.com](mailto:http://www.postgresql.org/message-id/flat/4DC32600.6080900@pgexperts.com#4DD3D6C6.5060006@2ndquadrant.com)):\n\n```ruby\nnode['postgresql']['contrib']['extensions'] = [\n \"pageinspect\",\n \"pg_buffercache\",\n \"pg_freespacemap\",\n \"pgrowlocks\",\n \"pg_stat_statements\",\n \"pgstattuple\"\n]\n```\n\nNote that the `pg_stat_statements` view only works if `postgresql.conf` loads its shared library, which can be done with this node attribute:\n\n```ruby\nnode['postgresql']['config']['shared_preload_libraries'] = 'pg_stat_statements'\n```\n\nIf using `shared_preload_libraries` in combination with the `contrib` recipe, make sure that the `contrib` recipe is called before the `server` recipe (to ensure the dependencies are installed and setup in order).\n\n### apt_pgdg_postgresql\n\nEnables the PostgreSQL Global Development Group yum repository maintained by Devrim Gündüz for updated PostgreSQL packages. (The PGDG is the groups that develops PostgreSQL.) Automatically included if the `node['postgresql']['enable_pgdg_apt']` attribute is true. Also set the `node['postgresql']['client']['packages']` and `node['postgresql']['server]['packages']` to the list of packages to use from this repository, and set the `node['postgresql']['version']` attribute to the version to use (e.g., \"9.2\").\n\n### yum_pgdg_postgresql\n\nEnables the PostgreSQL Global Development Group yum repository maintained by Devrim Gündüz for updated PostgreSQL packages. (The PGDG is the groups that develops PostgreSQL.) Automatically included if the `node['postgresql']['enable_pgdg_yum']` attribute is true. Also use `override_attributes` to set a number of values that will need to have embedded version numbers. For example:\n\n```ruby\nnode['postgresql']['enable_pgdg_yum'] = true\nnode['postgresql']['version'] = \"9.4\"\nnode['postgresql']['dir'] = \"/var/lib/pgsql/9.4/data\"\nnode['postgresql']['config']['data_directory'] = node['postgresql']['dir']\nnode['postgresql']['client']['packages'] = [\"postgresql94\", \"postgresql94-devel\"]\nnode['postgresql']['server']['packages'] = [\"postgresql94-server\"]\nnode['postgresql']['server']['service_name'] = \"postgresql-9.4\"\nnode['postgresql']['contrib']['packages'] = [\"postgresql94-contrib\"]\nnode['postgresql']['setup_script'] = \"postgresql94-setup\"\n```\n\nYou may set `node['postgresql']['pgdg']['repo_rpm_url']` attributes to pick up recent [PGDG repo packages](http://yum.postgresql.org/repopackages.php).\n\n## Usage\n\nOn systems that need to connect to a PostgreSQL database, add to a run list `recipe[postgresql]` or `recipe[postgresql::client]`.\n\nOn systems that should be PostgreSQL servers, use `recipe[postgresql::server]` on a run list. This recipe does set a password for the `postgres` user. If you're using `chef server`, if the attribute `node['postgresql']['password']['postgres']` is not found, the recipe generates a random password and performs a node.save. (TODO: This is broken, as it disables the password.) If you're using `chef-solo`, you'll need to set the attribute `node['postgresql']['password']['postgres']` in your node's `json_attribs` file or in a role.\n\nOn Debian family systems, SSL will be enabled, as the packages on Debian/Ubuntu also generate the SSL certificates. If you use another platform and wish to use SSL in postgresql, then generate your SSL certificates and distribute them in your own cookbook, and set the `node['postgresql']['config']['ssl']` attribute to true in your role/cookboook/node.\n\nOn server systems, the postgres server is restarted when a configuration file changes. This can be changed to reload only by setting the following attribute:\n\n```ruby\nnode['postgresql']['server']['config_change_notify'] = :reload\n```\n\n## Chef Solo Note\n\nThe following node attribute is stored on the Chef Server when using `chef-client`. Because `chef-solo` does not connect to a server or save the node object at all, to have the password persist across `chef-solo` runs, you must specify them in the `json_attribs` file used. For Example:\n\n```\n{\n \"postgresql\": {\n \"password\": {\n \"postgres\": \"iloverandompasswordsbutthiswilldo\"\n }\n },\n \"run_list\": [\"recipe[postgresql::server]\"]\n}\n```\n\nThat should actually be the \"encrypted password\" instead of cleartext, so you should generate it as an md5 hash using the PostgreSQL algorithm.\n\n- You could copy the md5-hashed password from an existing postgres database if you have `postgres` access and want to use the same password:<br>\n `select * from pg_shadow where usename='postgres';`\n- You can run this from any postgres database session to use a new password:<br>\n `select 'md5'||md5('iloverandompasswordsbutthiswilldo'||'postgres');`\n- You can run this from a linux commandline:<br>\n `echo -n 'iloverandompasswordsbutthiswilldo''postgres' | openssl md5 | sed -e 's/.* /md5/'`\n\n## License\n\nCopyright 2010-2016, Chef Software, Inc.\n\n```text\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","maintainer":"Sous Chefs","maintainer_email":"help@sous-chefs.org","license":"Apache 2.0","platforms":{"ubuntu":">= 12.04","debian":">= 7.0","opensuse":">= 13.0","suse":">= 12.0","fedora":">= 0.0.0","opensuseleap":">= 0.0.0","amazon":">= 0.0.0","redhat":">= 6.0","centos":">= 6.0","scientific":">= 6.0","oracle":">= 6.0"},"dependencies":{"compat_resource":">= 12.16.3","build-essential":">= 2.0.0","openssl":">= 4.0"},"recommendations":{},"suggestions":{},"conflicting":{},"providing":{},"replacing":{},"attributes":{},"groupings":{},"recipes":{"postgresql::default":"Includes postgresql::client","postgresql::ruby":"Installs pg gem for Ruby bindings","postgresql::client":"Installs postgresql client package(s)","postgresql::server":"Installs postgresql server packages, templates"}} |