postgresql_idx: improved doc, tests, remove useless lines from code (#55131)

* postgresql_idx: improve doc

* postgresql_idx: improve doc, removed unuseless rows from code

* postgresql_idx: misc doc fix

* postgresql_idx: moved common params where they were

* postgresql_idx: moved common params where they were 2

lib/ansible/modules/database/postgresql/postgresql_idx.py

@@ -18,8 +18,9 @@ DOCUMENTATION = r'''
 module: postgresql_idx
 short_description: Create or drop indexes from a PostgreSQL database
 description:
-- Create or drop indexes from a PostgreSQL database
-  U(https://www.postgresql.org/docs/current/sql-createindex.html).
+- Create or drop indexes from a PostgreSQL database.
+- For more information see U(https://www.postgresql.org/docs/current/sql-createindex.html),
+  U(https://www.postgresql.org/docs/current/sql-dropindex.html).
 version_added: '2.8'
 
 options:
@@ -32,7 +33,7 @@ options:
     - name
   db:
     description:
-    - Name of database where the index will be created/dropped.
+    - Name of database to connect to and where the index will be created/dropped.
     type: str
     aliases:
     - login_db
@@ -57,7 +58,8 @@ options:
     type: str
   schema:
     description:
-    - Name of a database schema.
+    - Name of a database schema where the index will be created.
+    type: str
   login_password:
     description:
     - Password used to authenticate with PostgreSQL.
@@ -90,6 +92,8 @@ options:
   state:
     description:
     - Index state.
+    - I(state=present) implies the index will be created if it does not exist.
+    - I(state=absent) implies the index will be dropped if it exists.
     type: str
     default: present
     choices: [ absent, present ]
@@ -101,7 +105,7 @@ options:
     required: true
   columns:
     description:
-    - List of index columns.
+    - List of index columns that need to be covered by index.
     - Mutually exclusive with I(state=absent).
     type: list
     aliases:
@@ -121,6 +125,10 @@ options:
   concurrent:
     description:
     - Enable or disable concurrent mode (CREATE / DROP INDEX CONCURRENTLY).
+    - Pay attention, if I(concurrent=no), the table will be locked (ACCESS EXCLUSIVE) during the building process.
+      For more information about the lock levels see U(https://www.postgresql.org/docs/current/explicit-locking.html).
+    - If the building process was interrupted for any reason when I(cuncurrent=yes), the index becomes invalid.
+      In this case it should be dropped and created again.
     - Mutually exclusive with I(cascade=yes).
     type: bool
     default: yes
@@ -145,6 +153,8 @@ options:
     default: no
 
 notes:
+- The index building process can affect database performance.
+- To avoid table locks on production databases, use I(concurrent=yes) (default behavior).
 - The default authentication assumes that you are either logging in as or
   sudo'ing to the postgres account on the host.
 - This module uses psycopg2, a Python PostgreSQL database adapter. You must
@@ -595,10 +605,7 @@ def main():
         module.warn("Index %s is invalid! ROLLBACK" % idxname)
 
     if not concurrent:
-        if module.check_mode:
-            db_connection.rollback()
-        else:
-            db_connection.commit()
+        db_connection.commit()
 
     kw['changed'] = changed
     module.exit_json(**kw)

test/integration/targets/postgresql/tasks/postgresql_idx.yml

@@ -181,6 +181,7 @@
     storage_params: fillfactor=90
   register: result
   ignore_errors: yes
+  when: tablespace.rc == 0
 
 - assert:
     that:
@@ -267,6 +268,7 @@
   check_mode: yes
   register: result
   ignore_errors: yes
+  when: tablespace.rc == 0
 
 - assert:
     that:
@@ -284,7 +286,7 @@
   postgresql_query:
     db: postgres
     login_user: "{{ pg_user }}"
-    query: "SELECT 1 FROM pg_indexes WHERE indexname = 'foo_test_idx'"
+    query: "SELECT 1 FROM pg_indexes WHERE indexname = 'foo_test_idx' AND schemaname = 'foo'"
   register: result
   when: tablespace.rc == 0
 
@@ -307,6 +309,7 @@
     concurrent: no
   register: result
   ignore_errors: yes
+  when: tablespace.rc == 0
 
 - assert:
     that:
@@ -324,7 +327,7 @@
   postgresql_query:
     db: postgres
     login_user: "{{ pg_user }}"
-    query: "SELECT 1 FROM pg_indexes WHERE indexname = 'foo_test_idx'"
+    query: "SELECT 1 FROM pg_indexes WHERE indexname = 'foo_test_idx' and schemaname = 'foo'"
   register: result
   when: tablespace.rc == 0