postgresql_user – Add or remove a user (role) from a PostgreSQL server instance¶
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.
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 desired
password. 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.
- 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.
- 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
Common return values are documented here, the following are the fields unique to this module:
added in 2.8
List of executed queries.
['CREATE USER "alice"', 'GRANT CONNECT ON DATABASE "acme" TO "alice"']