Default variable details
Some of debops.postgresql
default variables have more extensive
configuration than simple strings or lists, here you can find documentation and
examples for them.
postgresql__preferred_version
By default the role installs the PostgreSQL version preferred by the APT package manager. This behavior is influenced by how the PostgreSQL is packaged in Debian - each version has its own set of packages with the version as a suffix, and there's a set of metapackages which depend on the version available in the distribution (by default only 1 version is available).
Multiple PostgreSQL versions become available after enabling the upstream APT repository. To choose a different version than the default one, you need to set two variables in the inventory:
postgresql__preferred_version
The value of this variable should be set as the version of the PostgreSQL you wish the role to manage (it does not influence the APT packages the role installs, but what version is used in different file/directory paths managed by the role, what features are enabled/disabled in the configuration, etc.).
postgresql__base_packages
This is a list of APT packages which will be used by the role to install PostgreSQL. By default, it contains the metapackages which install the highest available version of PostgreSQL packages. To select a different version, you need to change the list of packages.
For example, to install PostgreSQL 9.3 instead of the default available version, in inventory you need to define:
postgresql__upstream: True
postgresql__preferred_version: '9.3'
postgresql__base_packages: [ 'postgresql-client-9.3' ]
Remember that role does not support management of multiple PostgreSQL versions at the same time. The above variables should be defined in the inventory at all times, otherwise role might revert to the default PostgreSQL packages and version, and break your installation. This also is true for server upgrades. The preferred way to make an upgrade is to configure a new database server with desired PostgreSQL version and move the database to it.
You might also need to set similar set of variables for the
debops.postgresql_server
role to keep both of the roles in sync. Refer to
its documentation for details.
postgresql__user_clusters
This list defines what entries will be set in
/etc/postgresql-common/user_clusters
configuration file. It is used by
pg_wrapper
in Debian to direct PostgreSQL-related commands to correct
clusters. DebOps uses the default entry to redirect PostgreSQL-related commands
like psql
to either local or remote PostgreSQL server.
Each entry is defined by a YAML dict. Supported parameters:
user
Required. String or list with UNIX account usernames to include in a given entry. You can specify
*
to use any user account.group
Required. String or list with UNIX group names to include in a given entry. You can specify
*
to use any group.version
Optional. Specify PostgreSQL version to use for a given entry. If not defined, default PostgreSQL detected by the role will be used.
cluster
Optional. Specify name of the cluster to direct the commands to. If not specified,
main
cluster will be used.host
Optional. IP address or hostname of the server the PostgreSQL database is stored as. Requires
port
to be specified as well. Replacescluster
.port
Optional. TCP port to connect to as the PostgreSQL server. Requires
host
to be specified as well. Replacescluster
.database
Required. Name of the database to connect to by default. If
*
is specified, users will connect to the database with the same name as their UNIX account.
postgresql__roles
PostgreSQL uses Roles as database accounts as well as groups.
Roles can have certain permissions granted to them by the server which allow access to database objects. This list can be used to create roles on a PostgreSQL server. Each role is defined as a YAML dictionary.
role
orname
Required. The name of a given role.
port
Optional. By default roles are created on the local or remote PostgreSQL server's default cluster (
5432
). You can specify a different port to change the cluster which will be used.password
Optional. Specify the password for a given PostgreSQL role. If not set, a random password will be generated and stored in
secret/
directory. See debops.secret role for more details.encrypted
Optional, bool. Specify if a given password is already encrypted or not.
expires
Optional. Specify password expiration date as a PostgreSQL timestamp value.
flags
Optional. YAML list of role attribute flags which should be applied to a given PostgreSQL role. Choices:
[NO]SUPERUSER
,[NO]CREATEROLE
,[NO]CREATEUSER
,[NO]CREATEDB
,[NO]INHERIT
,[NO]LOGIN
,[NO]REPLICATION
.
If a given role should manage a particular database, you can specify additional parameters:
db
Name of the database to manage. Only one database can be configured in a role entry at a time.
priv
YAML list of privileges to grant for a given role to specified database. List will be joined using
/
character into one privilege string.
Examples
Create a PostgreSQL role:
postgresql__roles:
- name: 'alpha'
Create a role and grant specific attribute flags:
postgresql__roles:
- name: 'beta'
flags: [ 'NOLOGIN' ]
Create a role and grant privileges to a particular database:
postgresql__roles:
- name: 'gamma'
db: 'gamma'
priv: [ 'CONNECT', 'table1:ALL' ]
postgresql__groups
Access to one or more PostgreSQL roles can be granted to other roles; that way an application role and database role can have different set of privileges. This list can be used to define these "groups" automatically. Recognized parameters:
roles
Required. List of roles which will be granted access to specified "groups".
groups
Required. List of role "groups" to grant access to.
database
Required. Name of the database on which to grant privileges.
port
Optional. By default roles are managed on the local or remote PostgreSQL server's default cluster (
5432
). You can specify a different port to change the cluster which will be used.
Examples
Grant membership to other roles:
postgresql__groups:
- roles: [ 'alpha', 'beta' ]
groups: [ 'gamma' ]
database: 'gamma'
postgresql__databases
List of PostgreSQL databases to create or manage on a PostgreSQL server. Known parameters:
database
orname
Required. Database name.
owner
Optional. Specifies the PostgreSQL role which will be an owner of a particular database. If not specified, database will be owned by PostgreSQL superuser role, usually
postgres
.If owner is specified, given role will be granted all privileges to the database and will have grant option enabled for a given database.
template
Optional. Specify name of the database which will be used as the template for new database.
encoding
Optional. Default encoding used by a given database. If not supplied it falls back to the server default, derived from
postgresql_server__locale
on thepostgresql_server
role.create_db
Optional. Set this to False when granting a role specific privileges on an existing database.
type
Optional. Type of database object to set privileges on. Default: schema.
objs
Optional. Comma separated list of database objects to set privileges on. Default: public.
privs
Optional. Comma separated list of privileges to grant. Default: ALL.
grant_option
Optional. Whether role (
owner
) may grant/revoke the specified privileges to others. Default: yes.
Examples
Create database owned by a specified role:
postgresql__databases:
- name: 'gamma'
owner: 'gamma'
Create database owned by a specified role and grant select privilege on all tables in schema public to another role:
postgresql__databases:
- name: 'gamma'
owner: 'gamma'
- name: 'gamma'
owner: 'alpha'
create_db: False
type: 'table'
objs: 'ALL_IN_SCHEMA'
public_privs: [ 'SELECT' ]
grant_option: 'no'
postgresql__privileges
List of additional privileges to grant or revoke on a PostgreSQL server. The parameters closely match those of the PostgreSQL Ansible module. Known parameters:
database
Required. Database name.
roles
Required. List of role (user/group) names to set permissions for.
port
Optional. TCP port to use when connecting to the PostgreSQL server.
objs
Optional. List of database objects to set privileges on. Default: public.
privs
Optional. Comma separated list of privileges to grant. Default: ALL.
state
Optional. If
present
, the specified privileges are granted, ifabsent
they are revoked. Default:present
.type
Optional. Type of database object to set privileges on. Default: table.
schema
Optional. Schema that contains the database objects specified via
objs
.target_roles
Optional. A list of existing role (user/group) names for which to set the default permissions for database objects subsequently created by them. Only relevant when
type=default_privs
.grant_option
Optional. Whether role (
owner
) may grant/revoke the specified privileges to others.
Examples
Give the role reader
default rights to any default objects created in the
database library
(e.g. tables created by another user).
postgresql__privileges:
- roles: [ 'reader' ]
database: 'library'
objs: [ 'ALL_DEFAULT' ]
privs: [ 'SELECT', 'INSERT', 'UPDATE', 'DELETE' ]
type: 'default_privs'
Give SELECT
privileges to the role reader
for any tables created by
librarian
in database library
.
postgresql__privileges:
- roles: [ 'reader' ]
database: 'library'
objs: [ 'TABLES' ]
privs: [ 'SELECT' ]
target_roles: [ 'librarian' ]
type: 'default_privs'
postgresql__extensions
List of YAML dictionaries that specify what extensions to enable or disable in a PostgreSQL database. Each dictionary can configure one extension at a time. Known parameters:
database
Required. Name of the database to configure, it needs to be an existing database.
extension
Required. Name of the PostgreSQL extension to configure.
port
Optional. The PostgreSQL cluster port number. If not specified, the default
postgresql__port
will be used automatically.state
Optional. Either
present
orabsent
. If not specified orpresent
, the extension will be enabled for a given database; ifabsent
, the extension will be disabled.
Examples
Add a custom extension to a database:
postgresql__extensions:
- database: 'gamma'
extension: 'pg_trgm'
postgresql__pgpass
The ~/.pgpass
configuration file is used to store usernames and passwords
used to login to local or remote PostgreSQL databases. Using this list you can
configure entries for different servers on UNIX accounts. If an account or
group is not present, it will be created automatically.
Each entry is defined by a YAML dictionary. Recognized parameters:
owner
Required. Specify name of the UNIX account that should be configured to access PostgreSQL databases. If that account doesn't exist, it will be created automatically as a local account.
group
Optional. Specify default group to use for a UNIX account. If it doesn't exist, it will be created as a local group. If it's not specified, a group with the same name as
owner
will be created automatically.system
Optional. If
True
(default), created local accounts will be "system" accounts with UID < 1000. IfFalse
, created accounts and groups will be "normal" accounts and groups.home
Specify home directory of created UNIX account. If not specified, parameter will be omitted (not changed if account is already present).
server
Optional. Specify IP address or FQDN hostname of the server that you want to configure. If not specified, default server will be guessed automatically from
postgresql__server
variable.port
Optional. Specify default TCP port to use for PostgreSQL server entry. If not specified,
postgresql__port
value will be used instead.database
Optional. Specify name of the database that should be covered by a given entry. If not specified,
*
will be used which means any database.role
Optional. Specify PostgreSQL role covered by a given entry. If not specified,
owner
will be used by default.password
Optional. Specify cleartext password which should be used with a given entry. If not specified, password will be pulled from
secret/
directory managed by debops.secret Ansible role.
Examples
Create ~/.pgpass
entry for a role with any database:
postgresql__pgpass:
- owner: 'alpha'
Create ~/.pgpass
entry for a specific database:
postgresql__pgpass:
- owner: 'gamma'
database: 'gamma'