community.postgresql.postgresql_ping (3.4.0) — module

Install collection

Install with ansible-galaxy collection install community.postgresql:==3.4.0

Add to requirements.yml

  collections:
    - name: community.postgresql
      version: 3.4.0

Description

Simple module to check remote PostgreSQL server availability.

Requirements

• psycopg2 >= 2.5.1

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# PostgreSQL ping dbsrv server from the shell:
# ansible dbsrv -m postgresql_ping

# In the example below you need to generate certificates previously.
# See https://www.postgresql.org/docs/current/libpq-ssl.html for more information.
- name: >
    Ping PostgreSQL server using non-default credentials and SSL
    registering the return values into the result variable for future use
  community.postgresql.postgresql_ping:
    db: protected_db
    login_host: dbsrv
    login_user: secret
    login_password: secret_pass
    ca_cert: /root/root.crt
    ssl_mode: verify-full
  register: result

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

  # If you need to fail when the server is not available,
  # uncomment the following line:
  #failed_when: not result.is_available

# You can use the registered result with another task
- name: This task should be executed only if the server is available
  # ...
  when: result.is_available == true

Inputs

    
db:
    aliases:
    - login_db
    description:
    - Name of a database to connect to.
    type: str

port:
    aliases:
    - login_port
    default: 5432
    description:
    - Database port to connect to.
    type: int

ca_cert:
    aliases:
    - 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.
    type: str

ssl_key:
    description:
    - Specifies the location for the secret key used for the client certificate.
    type: path
    version_added: 2.4.0
    version_added_collection: community.postgresql

ssl_cert:
    description:
    - Specifies the file name of the client SSL certificate.
    type: path
    version_added: 2.4.0
    version_added_collection: community.postgresql

ssl_mode:
    choices:
    - allow
    - disable
    - prefer
    - require
    - verify-ca
    - verify-full
    default: prefer
    description:
    - Determines whether or with what priority a secure SSL TCP/IP connection will be
      negotiated with the server.
    - See U(https://www.postgresql.org/docs/current/static/libpq-ssl.html) for more information
      on the modes.
    - Default of C(prefer) matches libpq default.
    type: str

login_host:
    aliases:
    - host
    default: ''
    description:
    - Host running the database.
    - If you have connection issues when using C(localhost), try to use C(127.0.0.1) instead.
    type: str

login_user:
    aliases:
    - login
    default: postgres
    description:
    - The username this module should use to establish its PostgreSQL session.
    type: str

trust_input:
    default: true
    description:
    - If C(false), check whether a value of I(session_role) is potentially dangerous.
    - It makes sense to use C(false) only when SQL injections via I(session_role) are
      possible.
    type: bool
    version_added: 0.2.0
    version_added_collection: community.postgresql

session_role:
    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
    version_added: 0.2.0
    version_added_collection: community.postgresql

connect_params:
    default: {}
    description:
    - Any additional parameters to be passed to libpg.
    - These parameters take precedence.
    type: dict
    version_added: 2.3.0
    version_added_collection: community.postgresql

login_password:
    default: ''
    description:
    - The password this module should use to establish its PostgreSQL session.
    type: str

login_unix_socket:
    aliases:
    - unix_socket
    default: ''
    description:
    - Path to a Unix domain socket for local connections.
    type: str

Outputs

conn_err_msg:
  description: Connection error message.
  returned: success
  sample: ''
  type: str
  version_added: 1.7.0
  version_added_collection: community.postgresql
is_available:
  description: PostgreSQL server availability.
  returned: success
  sample: true
  type: bool
server_version:
  description: PostgreSQL server version.
  returned: success
  sample:
    full: '13.2'
    major: 13
    minor: 2
    raw: PostgreSQL 13.2 on x86_64-pc-linux-gnu
  type: dict

See also

• community.postgresql.postgresql_info