Role Name
=========

A role that installs PostgreSQL and manages databases and users.
It can also install pgPoolII

Role Variables
--------------

The most important variables are listed below:

``` yaml
psql_postgresql_install: True
psql_pkg_state: present
postgresql_enabled: True
psql_pgpool_install: False
psql_pgpool_service_install: False
psql_version: 11
psql_db_host: localhost
psql_listen_on_ext_int: False
psql_use_alternate_data_dir: False
psql_enable_ssl: False
psql_force_ssl_client_connection: False
postgresql_letsencrypt_managed: '{{ psql_enable_ssl }}'

psql_db_data:
  # Example of line needed to create a db, create the user that owns the db, manage the db accesses (used by iptables too). All the fields are mandatory.
  - { name: '{{ psql_db_name }}', encoding: 'UTF8', user: '{{ psql_db_user }}', pwd: '{{ psql_db_pwd }}', roles: 'NOCREATEDB,NOSUPERUSER', extensions: [ 'postgis', 'pgpool_regclass', 'pgpool_recovery' ], allowed_hosts: [ 'xxx.xxx.xxx.xxx/32', 'yyy.yyy.yyy.yyy/32' ], managedb: True }
  # Example of line needed to manage the db accesses (used by iptables too), without creating the db and the user. Useful, for example, to give someone access to the postgresql db
  - { name: '{{ psql_db_name }}', user: '{{ psql_db_user }}', allowed_hosts: [ 'xxx.xxx.xxx.xxx/32', 'yyy.yyy.yyy.yyy/32' ], managedb: False }
  # Example of line needed to remove a db, create the user that owns the db, manage the db accesses (used by iptables too). All the fields are mandatory.
  - { name: '{{ psql_db_name }}', encoding: 'UTF8', user: '{{ psql_db_user }}', pwd: '{{ psql_db_pwd }}', managedb: True, roles: 'NOCREATEDB,NOSUPERUSER', extensions: [ 'postgis', 'pgpool_regclass', 'pgpool_recovery' ], allowed_hosts: [ 'xxx.xxx.xxx.xxx/32', 'yyy.yyy.yyy.yyy/32' ], state=absent }
```

### Prometheus exporter

[postgres_exporter](https://github.com/prometheus-community/postgres_exporter)
must run on the database host, so it is installed by this role instead of a
separate one. It is off by default.

``` yaml
psql_prometheus_exporter_install: True
psql_prometheus_exporter_version: "0.20.1"
psql_prometheus_exporter_port: 9187
# Scrape every database of the cluster and not only the one connected to
psql_prometheus_exporter_auto_discover_dbs: True
```

The default connection is the unix socket with peer authentication: the
exporter runs as the `postgres_exporter` system user, the database role has the
same name, and there is no password anywhere. The role is granted `pg_monitor`,
nothing else.

To connect over TCP instead — for example when the exporter has to reach a
cluster that only listens on an address — set:

``` yaml
psql_prometheus_exporter_use_socket: False
psql_prometheus_exporter_db_host: 127.0.0.1
psql_prometheus_exporter_db_pwd: '{{ a_vaulted_variable }}'
```

The DSN is written to `/etc/default/postgres_exporter` (`/etc/sysconfig` on EL)
with mode 0640, and not into the systemd unit, which is world readable.

On EL the exporter port is opened in firewalld when `firewalld_enabled` is
true. On Debian/Ubuntu the port belongs to the `iptables` variable of the
linux-firewall role, which is outside this role.

#### pg_stat_statements

``` yaml
psql_prometheus_exporter_stat_statements: True
# optional, applied after the restart
psql_prometheus_exporter_stat_statements_parameters:
  - { name: 'pg_stat_statements.track', value: 'all', set: 'true' }
```

It adds the library to `shared_preload_libraries`, **restarts the cluster**,
creates the extension in the database the exporter connects to, and adds
`--collector.stat_statements` to the exporter. Enable it before a server goes
into production, or plan the restart.

The current `shared_preload_libraries` is read and the library appended, so an
extension that is already preloaded is not unloaded. For the same reason do
**not** also set `shared_preload_libraries` in `psql_conf_custom_parameters`:
the two would overwrite each other on every run.

Turning the flag back to `False` stops the exporter collecting the metrics but
deliberately does **not** remove the library, which would mean another restart.
Remove it by hand if that is what you want.

The exporter needs no extra privilege: `pg_monitor` already carries
`pg_read_all_stats`, which is what lets a non superuser see the queries of every
user instead of only its own.

Dependencies
------------

None

License
-------

EUPL-1.2

Author Information
------------------

Andrea Dell'Amico, <andrea.dellamico@isti.cnr.it>