Postgres ssl mode prefer (#21498)

* refactor postgres,
* adds a basic unit test module
* first step towards a common utils module
* set postgresql_db doc argument defaults to what the code actually uses

* unit tests that actually test a missing/found psycopg2, no dependency needed

* add doc fragments, use common args, ansible2ify the imports

* update dict

* add AnsibleModule import

* mv AnsibleModule import to correct file

* restore some database utils we need

* rm some more duplicated pg doc fragments

* change ssl_mode from disable to prefer, add update docs

* use LibraryError pattern for import verification

per comments on #21435. basically LibraryError and touching up its usage in pg_db and the tests.

lib/ansible/utils/module_docs_fragments/postgres.py

@@ -0,0 +1,70 @@
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ModuleDocFragment(object):
+    # Postgres documentation fragment
+    DOCUMENTATION = """
+options:
+  login_user:
+    description:
+      - The username used to authenticate with
+    required: false
+    default: postgres
+  login_password:
+    description:
+      - The password used to authenticate with
+    required: false
+    default: null
+  login_host:
+    description:
+      - Host running the database
+    required: false
+    default: null
+  login_unix_socket:
+    description:
+      - Path to a Unix domain socket for local connections
+    required: false
+    default: null
+  port:
+    description:
+      - Database port to connect to.
+    required: false
+    default: 5432
+  ssl_mode:
+    description:
+      - Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.
+      - See https://www.postgresql.org/docs/current/static/libpq-ssl.html for more information on the modes.
+      - Default of C(prefer) matches libpq default.
+    required: false
+    default: prefer
+    choices: [disable, allow, prefer, require, verify-ca, verify-full]
+    version_added: '2.3'
+  ssl_rootcert:
+    description:
+      - Specifies the name of a file containing SSL certificate authority (CA) certificate(s).
+      - If the file exists, the server's certificate will be verified to be signed by one of these authorities.
+    required: false
+    default: null
+    version_added: '2.3'
+notes:
+- The default authentication assumes that you are either logging in as or sudo'ing to the C(postgres) account on the host.
+- This module uses I(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 C(postgresql), C(libpq-dev),
+  and C(python-psycopg2) packages on the remote host before using this module.
+- The ssl_rootcert parameter requires at least Postgres version 8.4 and I(psycopg2) version 2.4.3.
+requirements: [ psycopg2 ]
+"""