#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright: Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

from __future__ import absolute_import, division, print_function
__metaclass__ = type

ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'status': ['stableinterface'],
                    'supported_by': 'community'}

DOCUMENTATION = r'''
---
module: postgresql_privs
version_added: '1.2'
short_description: Grant or revoke privileges on PostgreSQL database objects
description:
- Grant or revoke privileges on PostgreSQL database objects.
- This module is basically a wrapper around most of the functionality of
  PostgreSQL's GRANT and REVOKE statements with detection of changes
  (GRANT/REVOKE I(privs) ON I(type) I(objs) TO/FROM I(roles)).
options:
  database:
    description:
    - Name of database to connect to.
    required: yes
    type: str
    aliases:
    - db
    - login_db
  state:
    description:
    - If C(present), the specified privileges are granted, if C(absent) they are revoked.
    type: str
    default: present
    choices: [ absent, present ]
  privs:
    description:
    - Comma separated list of privileges to grant/revoke.
    type: str
    aliases:
    - priv
  type:
    description:
    - Type of database object to set privileges on.
    - The `default_privs` choice is available starting at version 2.7.
    - The 'foreign_data_wrapper' and 'foreign_server' object types are available from Ansible version '2.8'.
    type: str
    default: table
    choices: [ database, default_privs, foreign_data_wrapper, foreign_server, function,
               group, language, table, tablespace, schema, sequence ]
  objs:
    description:
    - Comma separated list of database objects to set privileges on.
    - If I(type) is C(table), C(partition table), C(sequence) or C(function),
      the special valueC(ALL_IN_SCHEMA) can be provided instead to specify all
      database objects of type I(type) in the schema specified via I(schema).
      (This also works with PostgreSQL < 9.0.) (C(ALL_IN_SCHEMA) is available
       for C(function) and C(partition table) from version 2.8)
    - If I(type) is C(database), this parameter can be omitted, in which case
      privileges are set for the database specified via I(database).
    - 'If I(type) is I(function), colons (":") in object names will be
      replaced with commas (needed to specify function signatures, see examples)'
    type: str
    aliases:
    - obj
  schema:
    description:
    - Schema that contains the database objects specified via I(objs).
    - May only be provided if I(type) is C(table), C(sequence), C(function)
      or C(default_privs). Defaults to  C(public) in these cases.
    type: str
  roles:
    description:
    - Comma separated list of role (user/group) names to set permissions for.
    - The special value C(PUBLIC) can be provided instead to set permissions
      for the implicitly defined PUBLIC group.
    type: str
    required: yes
    aliases:
    - role
  fail_on_role:
    version_added: '2.8'
    description:
    - If C(yes), fail when target role (for whom privs need to be granted) does not exist.
      Otherwise just warn and continue.
    default: yes
    type: bool
  session_role:
    version_added: '2.8'
    description:
    - Switch to session_role after connecting.
    - The specified session_role must be a role that the current login_user is a member of.
    - Permissions checking for SQL commands is carried out as though the session_role were the one that had logged in originally.
    type: str
  target_roles:
    description:
    - A list of existing role (user/group) names to set as the
      default permissions for database objects subsequently created by them.
    - Parameter I(target_roles) is only available with C(type=default_privs).
    type: str
    version_added: '2.8'
  grant_option:
    description:
    - Whether C(role) may grant/revoke the specified privileges/group memberships to others.
    - Set to C(no) to revoke GRANT OPTION, leave unspecified to make no changes.
    - I(grant_option) only has an effect if I(state) is C(present).
    type: bool
    aliases:
    - admin_option
  host:
    description:
    - Database host address. If unspecified, connect via Unix socket.
    type: str
    aliases:
    - login_host
  port:
    description:
    - Database port to connect to.
    type: int
    default: 5432
    aliases:
    - login_port
  unix_socket:
    description:
    - Path to a Unix domain socket for local connections.