diff --git a/README.md b/README.md index ecfe367276..b9b42d436f 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,28 @@ # PostgreSQL system role ![CI Testing](https://github.com/linux-system-roles/postgresql/workflows/tox/badge.svg) -This role installs, configures, and starts PostgreSQL Server. +The PostgreSQL system role installs, configures, and starts the PostgreSQL server. The role also optimizes the database server settings to improve performance. -The role currently works with PostgreSQL server 10 12 and 13. +The role currently works with the PostgreSQL server versions 10, 12, and 13. + ## Role Variables ### postgresql_verison -Allow set up version of Postgresql server. This role supports Postgresql 10 12 and 13 +You can set the version of the PostgreSQL server to 10, 12, or 13. ```yaml postgresql_version: "13" ``` ### postgresql_password -Optionally, you can set up password for database super user `postgres` by default -there is not a password, datababase is accessible from `postgres` system account via UNIX socket. -users are encouraged to use ansible vault +Optionally, you can set a password for the `postgres` database superuser. By default, no password is set, and a datababase is accessible from the `postgres` system account through a UNIX socket. +It is recommended to encrypt the password using Ansible Vault. ```yaml postgresql_password: !vault | $ANSIBLE_VAULT;1.2;AES256;dev .... ``` ### postgresql_pg_hba_conf -A description of input variables that are not reqiured. Upstream configuration is used by default. -Usage of `postgresql_pg_hba_conf` causes replacement of default upstream configuration +The content of the `postgresql_pg_hba_conf` variable replaces the default upstream configuration in the `/var/lib/pgsql/data/pg_hba.conf` file. ```yaml postgresql_pg_hba_conf: - type: local @@ -42,8 +41,7 @@ postgresql_pg_hba_conf: auth_method: ident ``` ### postgresql_server_conf -Usage of `postgresql_server_conf` adds defined values at the end of postgresql.conf. -So the default ones are overwritten. +The content of the `postgresql_server_conf` variable is added to the end of the `/var/lib/pgsql/data/postgresql.conf` file. As a result, the default settings are overwritten. ```yaml postgresql_server_conf: ssl: on @@ -51,41 +49,38 @@ postgresql_server_conf: huge_pages: try ``` ### postgresql_ssl_enable -To set up ssl connection it's necessary to set up `postgresql_ssl_enable` variable and provide server certificate and key. +To set up a SSL/TLS connection, set the `postgresql_ssl_enable` variable to `true` and provide a server certificate and a private key. ```yaml postgresql_ssl_enable: true ``` ### postgresql_cert_name -To specify certificate name use `postgresql_cert_name` variable. -You can copy your certificate to `/etc/pki/tls/certs/server.crt` and key to `/etc/pki/tls/private/server.key` or -you can also use certificate system role. For more detail see [`examples/`](examples). +Use the `postgresql_cert_name` variable to specify the certificate name. +You can copy your server certificate to `/etc/pki/tls/certs/server.crt` and your private key to `/etc/pki/tls/private/server.key`. Alternatively, you can use the certificate system role. For details, see the [`examples/`](examples). ```yaml postgresql_cert_name: server ``` ### postgresql_key_path -Optionaly you can specify path to server key using `postgresql_key_path` variable. The default value is +Optionally, you can specify a path to the server key using the `postgresql_key_path` variable. The default value is `/etc/pki/tls/private`. ```yaml -postgresql_key_path: /etc/pki/tls/private +postgresql_key_path: "/etc/pki/tls/private" ``` ### postgresql_cert_path -Optionaly you can specify path to server cert using `postgresql_cert_path` variable. The default value is +Optionally, you can specify a path to the server certificate using the `postgresql_cert_path` variable. The default value is `/etc/pki/tls/certs`. ```ymal postgresql_cert_path: "/etc/pki/tls/certs" ``` ### postgresql_input_file -For running SQL script define path to your SQL file using `postgresql_input_file`: +To run an SQL script, define a path to your SQL file using the `postgresql_input_file` variable. ```yaml postgresql_input_file: "/tmp/mypath/file.sql" ``` ### postgresql_server_tuning -By default the system role makes server settings tuning based on system resources, -This functionality is enabled by default. For disabling it there is a possibility to -set up the `postgresql_server_tuning` variable. +By default, the PostgreSQL system role enables server settings optimization based on system resources. To disabe the tuning, set the `postgresql_server_tuning` variable to `false`. ```yaml postgresql_server_tuning: false ``` -More about usage could be found in [`examples/`](examples) directory +See the [`examples/`](examples) directory for details. ## Example Playbook diff --git a/tests/tests_default.yml b/tests/tests_default.yml index 300b846445..62f6f86a30 100644 --- a/tests/tests_default.yml +++ b/tests/tests_default.yml @@ -2,6 +2,58 @@ --- - name: Ensure that the role runs with default parameters hosts: all - gather_facts: false # test that role works in this case - roles: - - linux-system-roles.template + gather_facts: true # test that role works in this case + become: yes + become_user: root + + tasks: + - name: Test default settings + block: + - name: Run postgresql role + include_role: + name: linux-system-roles.postgresql + vars: + postgresql_version: "13" + + - meta: flush_handlers + + - name: test - postgresql-server running + command: systemctl is-active postgresql + changed_when: false + + - name: test - postgresql-server is enabled + command: systemctl is-enabled postgresql + changed_when: false + + - name: test - database is accesible for super user usign Unix socket + become: yes + become_user: postgres + shell: echo '\q' | psql + async: 3 # in case of password promt we need to fail + changed_when: false + + - name: check - server tunning is used - shared buffers + become: yes + become_user: postgres + shell: echo "SHOW shared_buffers;" | psql + register: result + changed_when: false + + - name: test - server tunning is used - shared buffers + assert: + that: > + "{{ (ansible_memory_mb.real.total/4)|int|abs }}|string + in result.stdout" + + - name: check - server tunning is used - effective cache size + become: yes + become_user: postgres + shell: echo "SHOW effective_cache_size;" | psql + register: result + changed_when: false + + - name: test - server tunning is used - shared buffers + assert: + that: > + "{{ (ansible_memory_mb.real.total/2)|int|abs }}|string in + result.stdout"