{
  "name": "database",
  "description": "Sets up the database master or slave",
  "long_description": "Database Cookbook\n=================\n\nThe main highlight of this cookbook is the `database` and\n`database_user` resources for managing databases and database users in\na RDBMS. Providers for MySQL, PostgreSQL and SQL Server are also\nprovided, see usage documentation below.\n\nThis cookbook also contains recipes to configure mysql database\nmasters and slaves and uses EBS for storage, integrating together with\nthe application cookbook utilizing data bags for application related\ninformation. These recipes are written primarily to use MySQL and the\nOpscode mysql cookbook. Other RDBMS may be supported at a later date.\nThis cookbook does not automatically restore database dumps, but does\ninstall tools to help with that.\n\nRequirements\n============\n\nChef version 0.10.10+.\n\nPlatform\n--------\n\n* Debian, Ubuntu\n* Red Hat, CentOS, Scientific, Fedora, Amazon\n\nCookbooks\n---------\n\nThe following Opscode cookbooks are dependencies:\n\n* mysql\n* postgresql\n* xfs\n* aws\n\nResources/Providers\n===================\n\nThese resources aim to expose an abstraction layer for interacting\nwith different RDBMS in a general way. Currently the cookbook ships\nwith providers for MySQL, PostgreSQL and SQL Server. Please see\nspecific usage in the __Example__ sections below. The providers use\nspecific Ruby gems installed under Chef's Ruby environment to execute\ncommands and carry out actions. These gems will need to be installed\nbefore the providers can operate correctly. Specific notes for each\nRDBS flavor:\n\n- MySQL: leverages the `mysql` gem which is installed as part of the\n  `mysql::ruby` recipe. You can use `database::mysql` to include this,\n  too.\n- PostgreSQL: leverages the `pg` gem which is installed as part of the\n  `postgresql::ruby` recipe. You can use `database::postgresql` to\n  include this, too.\n  Currently does not work in Chef \"omnibus\" full stack installs, see COOK-1406.\n- SQL Server: leverages the `tiny_tds` gem which is installed as part\n  of the `sql_server::client` recipe.\n\n`database`\n----------\n\nManage databases in a RDBMS. Use the proper shortcut resource\ndepending on your RDBMS: `mysql_database`, `postgresql_database` or\n`sql_server_database`.\n\n### Actions\n\n- :create: create a named database\n- :drop: drop a named database\n- :query: execute an arbitrary query against a named database\n\n### Attribute Parameters\n\n- database_name: name attribute. Name of the database to interact with\n- connection: hash of connection info. valid keys include :host,\n  :port, :username, :password\n- sql: string of sql or a block that executes to a string of sql,\n  which will be executed against the database. used by :query action\n  only\n\n### Providers\n\n- **Chef::Provider::Database::Mysql**: shortcut resource `mysql_database`\n- **Chef::Provider::Database::Postgresql**: shortcut resource `postgresql_database`\n- **Chef::Provider::Database::SqlServer**: shortcut resource `sql_server_database`\n\n### Examples\n\n    # create a mysql database\n    mysql_database 'oracle_rules' do\n      connection ({:host => \"localhost\", :username => 'root', :password => node['mysql']['server_root_password']})\n      action :create\n    end\n\n    # create a sql server database\n    sql_server_database 'mr_softie' do\n      connection ({:host => \"127.0.0.1\", :port => node['sql_server']['port'], :username => 'sa', :password => node['sql_server']['server_sa_password']})\n      action :create\n    end\n\n    # create a postgresql database\n    postgresql_database 'mr_softie' do\n      connection ({:host => \"127.0.0.1\", :port => 5432, :username => 'postgres', :password => node['postgresql']['password']['postgres']})\n      action :create\n    end\n\n    # create a postgresql database with additional parameters\n    postgresql_database 'mr_softie' do\n      connection ({:host => \"127.0.0.1\", :port => 5432, :username => 'postgres', :password => node['postgresql']['password']['postgres']})\n      template 'DEFAULT'\n      encoding 'DEFAULT'\n      tablespace 'DEFAULT'\n      connection_limit '-1'\n      owner 'postgres'\n      action :create\n    end\n\n    # externalize conection info in a ruby hash\n    mysql_connection_info = {:host => \"localhost\",\n                             :username => 'root',\n                             :password => node['mysql']['server_root_password']}\n    sql_server_connection_info = {:host => \"localhost\",\n                                  :port => node['sql_server']['port'],\n                                  :username => 'sa',\n                                  :password => node['sql_server']['server_sa_password']}\n    postgresql_connection_info = {:host => \"127.0.0.1\",\n                                  :port => node['postgresql']['config']['port'],\n                                  :username => 'postgres',\n                                  :password => node['postgresql']['password']['postgres']}\n\n    # same create commands, connection info as an external hash\n    mysql_database 'foo' do\n      connection mysql_connection_info\n      action :create\n    end\n    sql_server_database 'foo' do\n      connection sql_server_connection_info\n      action :create\n    end\n    postgresql_database 'foo' do\n      connection postgresql_connection_info\n      action :create\n    end\n\n    # create database, set provider in resource parameter\n    database 'bar' do\n       connection mysql_connection_info\n       provider Chef::Provider::Database::Mysql\n       action :create\n    end\n    database 'bar' do\n      connection sql_server_connection_info\n      provider Chef::Provider::Database::SqlServer\n      action :create\n    end\n    database 'bar' do\n      connection postgresql_connection_info\n      provider Chef::Provider::Database::Postgresql\n      action :create\n    end\n\n    # drop a database\n    mysql_database \"baz\" do\n      connection mysql_connection_info\n      action :drop\n    end\n\n    # query a database\n    mysql_database \"flush the privileges\" do\n      connection mysql_connection_info\n      sql \"flush privileges\"\n      action :query\n    end\n\n    # query a database from a sql script on disk\n    mysql_database \"run script\" do\n      connection mysql_connection_info\n      sql { ::File.open(\"/path/to/sql_script.sql\").read }\n      action :query\n    end\n\n    # vacuum a postgres database\n    postgres_database \"vacuum databases\" do\n      connection postgresql_connection_info\n      database_table \"template1\"\n      sql \"VACUUM FULL VERBOSE ANALYZE\"\n      action :query\n    end\n\n`database_user`\n---------------\n\nManage users and user privileges in a RDBMS. Use the proper shortcut\nresource depending on your RDBMS: `mysql_database_user`,\n`postgresql_database_user`, or `sql_server_database_user`.\n\n### Actions\n\n- :create: create a user\n- :drop: drop a user\n- :grant: manipulate user privileges on database objects\n\n### Attribute Parameters\n\n- username: name attribute. Name of the database user\n- password: password for the user account\n- database_name: Name of the database to interact with\n- connection: hash of connection info. valid keys include :host,\n  :port, :username, :password\n- privileges: array of database privileges to grant user. used by the\n  :grant action. default is :all\n- host: host where user connections are allowed from. used by MySQL\n  provider only. default is 'localhost'\n- table: table to grant privileges on. used by :grant action and MySQL\n  provider only. default is '*' (all tables)\n\n### Providers\n\n- **Chef::Provider::Database::MysqlUser**: shortcut resource\n    `mysql_database_user`\n- **Chef::Provider::Database::PostgresqlUser**: shortcut\n    resource `postgresql_database_user`\n- **Chef::Provider::Database::SqlServerUser**: shortcut resource\n    `sql_server_database_user`\n\n### Examples\n\n    # create connection info as an external ruby hash\n    mysql_connection_info = {:host => \"localhost\",\n                             :username => 'root',\n                             :password => node['mysql']['server_root_password']}\n    postgresql_connection_info = {:host => \"localhost\",\n                                  :port => node['postgresql']['config']['port'],\n                                  :username => 'postgres',\n                                  :password => node['postgresql']['password']['postgres']}\n    sql_server_connection_info = {:host => \"localhost\",\n                                  :port => node['sql_server']['port'],\n                                  :username => 'sa',\n                                  :password => node['sql_server']['server_sa_password']}\n\n    # create a mysql user but grant no privileges\n    mysql_database_user 'disenfranchised' do\n      connection mysql_connection_info\n      password 'super_secret'\n      action :create\n    end\n\n    # do the same but pass the provider to the database resource\n    database_user 'disenfranchised' do\n      connection mysql_connection_info\n      password 'super_secret'\n      provider Chef::Provider::Database::MysqlUser\n      action :create\n    end\n\n    # create a postgresql user but grant no privileges\n    postgresql_database_user 'disenfranchised' do\n      connection postgresql_connection_info\n      password 'super_secret'\n      action :create\n    end\n\n    # do the same but pass the provider to the database resource\n    database_user 'disenfranchised' do\n      connection postgresql_connection_info\n      password 'super_secret'\n      provider Chef::Provider::Database::PostgresqlUser\n      action :create\n    end\n\n    # create a sql server user but grant no privileges\n    sql_server_database_user 'disenfranchised' do\n      connection sql_server_connection_info\n      password 'super_secret'\n      action :create\n    end\n\n    # drop a mysql user\n    mysql_database_user \"foo_user\" do\n      connection mysql_connection_info\n      action :drop\n    end\n\n    # bulk drop sql server users\n    %w{ disenfranchised foo_user }.each do |user|\n      sql_server_database_user user do\n        connection sql_server_connection_info\n        action :drop\n      end\n    end\n\n    # grant select,update,insert privileges to all tables in foo db from all hosts\n    mysql_database_user 'foo_user' do\n      connection mysql_connection_info\n      password 'super_secret'\n      database_name 'foo'\n      host '%'\n      privileges [:select,:update,:insert]\n      action :grant\n    end\n\n    # grant all privileges on all databases/tables from localhost\n    mysql_database_user 'super_user' do\n      connection mysql_connection_info\n      password 'super_secret'\n      action :grant\n    end\n\n    # grant all privileges on all tables in foo db\n    postgresql_database_user 'foo_user' do\n      connection postgresql_connection_info\n      database_name 'foo'\n      privileges [:all]\n      action :grant\n    end\n\n    # grant select,update,insert privileges to all tables in foo db\n    sql_server_database_user 'foo_user' do\n      connection sql_server_connection_info\n      password 'super_secret'\n      database_name 'foo'\n      privileges [:select,:update,:insert]\n      action :grant\n    end\n\nRecipes\n=======\n\nebs\\_volume\n-----------\n\n*Note*: This recipe does not currently work on RHEL platforms due to\n the xfs cookbook not supporting RHEL yet.\n\nLoads the aws information from the data bag. Searches the applications\ndata bag for the database master or slave role and checks that role is\napplied to the node. Loads the EBS information and the master\ninformation from data bags. Uses the aws cookbook LWRP,\n`aws_ebs_volume` to manage the volume.\n\nOn a master node:\n* if we have an ebs volume already as stored in a data bag, attach it.\n* if we don't have the ebs information then create a new one and\n  attach it.\n* store the volume information in a data bag via a ruby block.\n\nOn a slave node:\n* use the master volume information to generate a snapshot.\n* create the new volume from the snapshot and attach it.\n\nAlso on a master node, generate some configuration for running a\nsnapshot via `chef-solo` from cron.\n\nOn a new filesystem volume, create as XFS, then mount it in /mnt, and\nalso bind-mount it to the mysql data directory (default\n/var/lib/mysql).\n\nmaster\n------\n\nThis recipe no longer loads AWS specific information, and the database\nposition for replication is no longer stored in a databag because the\nclient might not have permission to write to the databag item. This\nmay be handled in a different way at a future date.\n\nSearches the apps databag for applications, and for each one it will\ncheck that the specified database master role is set in both the\ndatabag and applied to the node's run list. Then, retrieves the\npasswords for `root`, `repl` and `debian` users and saves them to the\nnode attributes. If the passwords are not found in the databag, it\nprints a message that they'll be generated by the mysql cookbook.\n\nThen it adds the application databag database settings to a hash, to\nuse later.\n\nThen it will iterate over the databases and create them with the\n`mysql_database` resource while adding privileges for application\nspecific database users using the `mysql_database_user` resource.\n\nslave\n-----\n\n_TODO_: Retrieve the master status from a data bag, then start\nreplication using a ruby block. The replication status needs to be\nhandled in some other way for now since the master recipe above\ndoesn't actually set it in the databag anymore.\n\nsnapshot\n--------\n\nRun via Chef Solo. Retrieves the db snapshot configuration from the\nspecified JSON file. Uses the `mysql_database` resource to lock and\nunlock tables, and does a filesystem freeze and EBS snapshot.\n\nDeprecated Recipes\n==================\n\nThe following recipe is considered deprecated. It is kept for\nreference purposes.\n\nebs\\_backup\n-----------\n\nOlder style of doing mysql snapshot and replication using Adam Jacob's\n[ec2_mysql](http://github.com/adamhjk/ec2_mysql) script and library.\n\nData Bags\n=========\n\nThis cookbook uses the apps data bag item for the specified\napplication; see the `application` cookbook's README.md. It also\ncreates data bag items in a bag named 'aws' for storing volume\ninformation. In order to interact with EC2, it expects aws to have a\nmain item:\n\n    {\n      \"id\": \"main\",\n      \"ec2_private_key\": \"private key as a string\",\n      \"ec2_cert\": \"certificate as a string\",\n      \"aws_account_id\": \"\",\n      \"aws_secret_access_key\": \"\",\n      \"aws_access_key_id\": \"\"\n    }\n\nNote: with the Open Source Chef Server, the server using the database\nrecipes must be an admin client or it will not be able to create data\nbag items. You can modify whether the client is admin by editing it\nwith knife.\n\n    knife client edit <client_name>\n    {\n      ...\n      \"admin\": true\n      ...\n    }\n\nThis is not required if the Chef Server is Opscode Hosted Chef,\ninstead use the ACL feature to modify access for the node to be able\nto update the data bag.\n\nUsage\n=====\n\nAside from the application data bag (see the README in the application\ncookbook), create a role for the database master. Use a role.rb in\nyour chef-repo, or create the role directly with knife.\n\n    % knife role show my_app_database_master -Fj\n    {\n      \"name\": \"my_app_database_master\",\n      \"chef_type\": \"role\",\n      \"json_class\": \"Chef::Role\",\n      \"default_attributes\": {\n      },\n      \"description\": \"\",\n      \"run_list\": [\n        \"recipe[mysql::server]\",\n        \"recipe[database::master]\"\n      ],\n      \"override_attributes\": {\n      }\n    }\n\nCreate a `production` environment. This is also used in the\n`application` cookbook.\n\n    % knife environment show production -Fj\n    {\n      \"name\": \"production\",\n      \"description\": \"\",\n      \"cookbook_versions\": {\n      },\n      \"json_class\": \"Chef::Environment\",\n      \"chef_type\": \"environment\",\n      \"default_attributes\": {\n      },\n      \"override_attributes\": {\n      }\n    }\n\n\nThe cookbook `my_app_database` is recommended to set up any\napplication specific database resources such as configuration\ntemplates, trending monitors, etc. It is not required, but you would\nneed to create it separately in `site-cookbooks`. Add it to the\n`my_app_database_master` role.\n\nLicense and Author\n==================\n\n- Author:: Adam Jacob (<adam@opscode.com>)\n- Author:: Joshua Timberman (<joshua@opscode.com>)\n- Author:: AJ Christensen (<aj@opscode.com>)\n- Author:: Seth Chisamore (<schisamo@opscode.com>)\n- Author:: Lamont Granquist (<lamont@opscode.com>)\n\nCopyright 2009-2012, Opscode, Inc.\n\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",
  "maintainer": "Opscode, Inc.",
  "maintainer_email": "cookbooks@opscode.com",
  "license": "Apache 2.0",
  "platforms": {
    "debian": ">= 0.0.0",
    "ubuntu": ">= 0.0.0",
    "centos": ">= 0.0.0",
    "suse": ">= 0.0.0",
    "fedora": ">= 0.0.0",
    "redhat": ">= 0.0.0",
    "scientific": ">= 0.0.0",
    "amazon": ">= 0.0.0"
  },
  "dependencies": {
    "mysql": ">= 1.3.0",
    "postgresql": ">= 1.0.0",
    "aws": ">= 0.0.0",
    "xfs": ">= 0.0.0"
  },
  "recommendations": {
  },
  "suggestions": {
  },
  "conflicting": {
  },
  "providing": {
  },
  "replacing": {
  },
  "attributes": {
  },
  "groupings": {
  },
  "recipes": {
    "database": "Empty placeholder",
    "database::ebs_backup": "Considered deprecated, older way of backing up EBS volumes",
    "database::ebs_volume": "Sets up an EBS volume in EC2 for the database",
    "database::master": "Creates application specific user and database",
    "database::snapshot": "Locks tables and freezes XFS filesystem for replication, assumes EC2 + EBS"
  },
  "version": "1.3.12"
}