# PostgreSQL

Summary: Work with Postgres databases.

## Common Options

- `host` (str): The host name. Default: `localhost`
- `password` (str): The password of the user executing the command.
- `port` (int): The TCP port. Default: `5432`
- `user` (str): The username of the user executing the command. Default: `postgres`

## Automatic Conversion of Postgres Command Switches

Options provided in the steps file are automatically converted to command line switches. For example:

```ini
[create a soft backup of the database schema]
pgsql.dump: example_app
schema_only: yes
path: /tmp/example_app.sql

```

`schema_only` becomes "--schema-only".

## Available Commands

### pgsql.create

Create a database. Argument is the database name.

- `owner` (str): The username that owns the database.

```ini
[create the database]
pgsql.create: database_name
```

### pgsql.drop

Drop a database. Argument is the database name.

```ini
[drop the testing database]
pgsql.drop: testing_example_app

```

### pgsql.dump

Dump the database schema. Argument is the database name.

- `path` (str): The path to the dump file. Default: `database_name.sql`

```ini
[create a soft backup of the database]
pgsql.dump: example_app
column_inserts: yes
path: /tmp/example_app.sql

```

### pgsql.exists

Determine if a database exists. Argument is the database name.

```ini
[determine if the database exists]
pgsql.exists: example_app

```

### pgsql.grant

Grant privileges to a user. Argument is the username. Database option is required.

- `database` (str): The name of the database where the target object exists.
- `privileges` (str): The privileges to be granted. Default `ALL` (see [Postgres docs](https://www.postgresql.org/docs/current/sql-grant.html))
- `schema` (str): The schema name to which the privileges apply.
- `table` (str): The table name to which privileges apply.

!!! note
    A schema name or table name is required.

```ini
[grant select access to bob]
pgsql.grant: bob
database: example_app
privileges: select
schema: public

```

### pgsql.user

Create a user. Argument is the user name.

- `password` (str): The user's password.

```ini
[create a database user]
pgsql.user: username
```

Remove a user.

```ini
[remove a database user]
pgsql.user: username
op: remove
```

Determine if a user exists.

```ini
[determine if database user exists]
pgsql.user: username
op: exists
```