# PostgreSQL cookbook

## Resources

### postgresql_user

Creates a user account in the PostgreSQL instance

#### properties

* `username`: (name property): The name of the user to create. Required
* `password`: The password of the account. Optional. This can be the plaintext password, or an md5 hash of the password. The hash can be generated by running `echo -n 'PASSWORD+USERNAME' | md5sum` and should be passed in the form `md5PASSWORD_HASH`.
* `options`: An array of options to enable on the user. Optional. See the [PostgreSQL documentation](https://www.postgresql.org/docs/12/static/sql-createuser.html) for the available options
* `helper`: The helper object for interacting with the running database. Default: `PgHelper.new(node)`

#### example

Create the user 'bar' without a password or any options

```ruby
postgresql_user 'bar'
```

Create the superuser 'bar' with an md5 encoded password
```ruby
postgresql_user 'bar' do
  options %w(SUPERUSER)
  password 'md5........'
end
```

### postgresql_database

Creates a database in the PostgreSQL instance

#### properties

* `database`: The name of the database to create. Required.
* `owner`: The user account that will be the owner of the database. Default: `node['postgresql']['sql_user']`
* `helper`: The helper object for interacting with the running database. `Default: `PgHelper.new(node)``
* `database_port`: The port the database instance is listening on. Default: `node['postgresql']['port']`
* `database_socket`: The directory that the socket file exists in. Default: `node['postgresql']['unix_socket_directory']`

#### example

Create a database called 'foo' owned by the default postgresql user

```ruby
postgresql_database 'foo'
```

Create a database called 'foo' owned by user 'bar'

```ruby
postgresql_database 'foo' do
  owner 'bar'
end
```

### postgresql_query

Utility resource to execute administrative queries against the PostgreSQL instance.
This resource is used by other resources to CREATE, UPDATE and DESTROY data in the database.

#### properties

* `description`: (name property): Textual identification of the operation (must be unique). Required
* `query`: The SQL query that must be executed in the database. Required
* `db_name`: The database where the queries are going to run. Default: `template1`
* `helper`: The helper object for interacting with the running database. Default: `PgHelper.new(node)`

#### example

```ruby
postgresql_query 'creates gitlab user' do
  query "CREATE USER 'gitlab';"
end
```

### postgresql_schema

Creates a schema and set its owner.

#### properties

* `schema`: (name property): The schema name. Required
* `database`: The database where the schema will be created. Required
* `owner`: The database user who will own the schema. Default: `CURRENT_USER` (current logged-in user)
* `helper`: The helper object for interacting with the running database. Default: `PgHelper.new(node)`

#### example

```ruby
postgresql_schema 'example' do
  database 'omnibus_gitlab_test'
end
```

### postgresql_extension

Enable a PostgreSQL extension in specified database.

#### properties

* `extension`: (name property): The extension name. Required
* `database`: The database where the extension will be enabled. Required
* `helper`: The helper object for interacting with the running database. Default: `PgHelper.new(node)`

#### example

```ruby
postgresql_extension 'pg_trm' do
  database 'omnibus_gitlab_test'
end
```

### postgresql_config

Utility resource to generate PostgreSQL configuration files like 
`pg_hba.conf`, `pg_ident.conf`, `postgresql.conf` and its related files.  

#### properties

* `name`: (name property): Textual identification of the operation (must be unique). Required
* `username`: The unix user who will own the configuration files. Default: `node['postgresql']['username']`
* `helper`: The helper object for interacting with the running database. Default: `PgHelper.new(node)`