postgresql_user – Add or remove a user (role) from a PostgreSQL server instance¶
Synopsis¶
Adds or removes a user (role) from a PostgreSQL server instance (“cluster” in PostgreSQL terminology) and, optionally, grants the user access to an existing database or tables.
A user is a role with login privilege.
The fundamental function of the module is to create, or delete, users from a PostgreSQL instances. Privilege assignment, or removal, is an optional step, which works on one database at a time. This allows for the module to be called several times in the same module to modify the permissions on different databases, or to grant permissions to already existing users.
A user cannot be removed until all the privileges have been stripped from the user. In such situation, if the module tries to remove the user it will fail. To avoid this from happening the fail_on_user option signals the module to try to remove the user, but if not possible keep going; the module will report if changes happened and separately if the user was removed or not.
Parameters¶
Notes¶
Note
The module creates a user (role) with login privilege by default. Use NOLOGIN role_attr_flags to change this behaviour.
If you specify PUBLIC as the user (role), then the privilege changes will apply to all users (roles). You may not specify password or role_attr_flags when the PUBLIC user is specified.
On some systems (such as AWS RDS),
pg_authidis not accessible, thus, the module cannot compare the current and desiredpassword. In this case, the module assumes that the passwords are different and changes it reporting that the state has been changed. To skip all password related checks for existing users, use no_password_changes=yes.The default authentication assumes that you are either logging in as or sudo’ing to the
postgresaccount on the host.To avoid “Peer authentication failed for user postgres” error, use postgres user as a become_user.
This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module.
If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host.
For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module.
The ca_cert parameter requires at least Postgres version 8.4 and psycopg2 version 2.4.3.
See Also¶
See also
- postgresql_privs – Grant or revoke privileges on PostgreSQL database objects
The official documentation on the postgresql_privs module.
- postgresql_membership – Add or remove PostgreSQL roles from groups
The official documentation on the postgresql_membership module.
- postgresql_owner – Change an owner of PostgreSQL database object
The official documentation on the postgresql_owner module.
- PostgreSQL database roles
Complete reference of the PostgreSQL database roles documentation.
Examples¶
- name: Connect to acme database, create django user, and grant access to database and products table
postgresql_user:
db: acme
name: django
password: ceec4eif7ya
priv: "CONNECT/products:ALL"
expires: "Jan 31 2020"
# Connect to default database, create rails user, set its password (MD5-hashed),
# and grant privilege to create other databases and demote rails from super user status if user exists
- name: Create rails user, set MD5-hashed password, grant privs
postgresql_user:
name: rails
password: md59543f1d82624df2b31672ec0f7050460
role_attr_flags: CREATEDB,NOSUPERUSER
- name: Connect to acme database and remove test user privileges from there
postgresql_user:
db: acme
name: test
priv: "ALL/products:ALL"
state: absent
fail_on_user: no
- name: Connect to test database, remove test user from cluster
postgresql_user:
db: test
name: test
priv: ALL
state: absent
- name: Connect to acme database and set user's password with no expire date
postgresql_user:
db: acme
name: django
password: mysupersecretword
priv: "CONNECT/products:ALL"
expires: infinity
# Example privileges string format
# INSERT,UPDATE/table:SELECT/anothertable:ALL
- name: Connect to test database and remove an existing user's password
postgresql_user:
db: test
user: test
password: ""
- name: Create user test and grant group user_ro and user_rw to it
postgresql_user:
name: test
groups:
- user_ro
- user_rw
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description |
|---|---|---|
|
queries
list
added in 2.8 |
always |
List of executed queries.
Sample:
['CREATE USER "alice"', 'GRANT CONNECT ON DATABASE "acme" TO "alice"']
|
Status¶
This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]
This module is maintained by the Ansible Community. [community]
Authors¶
Ansible Core Team
Hint
If you notice any issues in this documentation, you can edit this document to improve it.