PostgreSQL database plugin HTTP API

The PostgreSQL database plugin is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on configured roles for the PostgreSQL database.

Configure connection

In addition to the parameters defined by the Database Backend, this plugin has a number of parameters to further configure a connection.

Method	Path
POST	/database/config/:name

Parameters

• connection_url (string: <required>) - Specifies the PostgreSQL DSN. This field can be templated and supports passing the username and password parameters in the following format {{field_name}}. Certificate authentication can be used by setting ?sslmode= to be any of the applicable values as outlined in the Postgres SQL documentation and giving the SSL credentials in the sslrootcert, sslcert and sslkey credentials. A templated connection URL is required when using root credential rotation. This field supports both format string types, URI and keyword/value. Both formats support multiple host connection strings. Due to how pgx works, parameters such as sslrootcert, sslcert, sslkey are treated as paths on the Vault server.

• max_open_connections (int: 4) - Specifies the maximum number of open connections to the database.

• max_idle_connections (int: 0) - Specifies the maximum number of idle connections to the database. A zero uses the value of max_open_connections and a negative value disables idle connections. If larger than max_open_connections it will be reduced to be equal.

• max_connection_lifetime (string: "0s") - Specifies the maximum amount of time a connection may be reused. If <= 0s, connections are reused forever.

• username (string: "") - The root credential username used in the connection URL.

• password (string: "") - The root credential password used in the connection URL.

• auth_type (string: "") - If set to gcp_iam, will enable IAM authentication to a Google CloudSQL instance. For more information on authenticating to CloudSQL via IAM, please refer to Google's official documentation here..

• service_account_json (string: "") - JSON encoded credentials for a GCP Service Account to use for IAM authentication. Requires auth_type to be gcp_iam.

• username_template (string) - Template describing how dynamic usernames are generated.

• disable_escaping (boolean: false) - Turns off the escaping of special characters inside of the username and password fields. See the databases secrets engine docs for more information. Defaults to false.

• password_authentication (string: "password") - When set to "scram-sha-256", passwords will be hashed by Vault and stored as-is by PostgreSQL. Using "scram-sha-256" requires a minimum version of PostgreSQL 10. Available options are "scram-sha-256" and "password". The default is "password". When set to "password", passwords will be sent to PostgreSQL in plaintext format and may appear in PostgreSQL logs as-is. For more information, please refer to the PostgreSQL documentation.

Default Username Template

Sample payload with URI-format connection string

{
  "plugin_name": "postgresql-database-plugin",
  "allowed_roles": "readonly",
  "connection_url": "postgresql://{{username}}:{{password}}@localhost:5432/postgres",
  "max_open_connections": 5,
  "max_connection_lifetime": "5s",
  "username": "username",
  "password": "password"
}

Sample payload with Keyword/Value-format connection string

{
  "plugin_name": "postgresql-database-plugin",
  "allowed_roles": "readonly",
  "connection_url": "host=localhost port=5432 user={{username}} password={{password}}",
  "max_open_connections": 5,
  "max_connection_lifetime": "5s",
  "username": "username",
  "password": "password"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/config/postgresql

Connection strings with multiple hosts

Postgres supports multiple hosts in the connection string. An example use-case for this might be having Postgres set up with Replication Manager. However, there are some formatting rules to consider when using this feature. Please refer to the "Specifying Multiple Hosts" section of the official Postgres documentation for more information. Below are two small examples.

URI-format Multi-Host string:

{
  "connection_url": "postgresql://{{username}}:{{password}}@hostone:5432,hosttwo:5432,hostthree:9999/postgres"
}

Keyword/Value-format Multi-Host string:

{
  "connection_url": "host=hostone,hosttwo,hostthree port=5432,5432,9999 user={{username}} password={{password}} dbname=postgres"
}

Statements

Statements are configured during role creation and are used by the plugin to determine what is sent to the database on user creation, renewing, and revocation. For more information on configuring roles see the Role API in the database secrets engine docs.

Parameters

The following are the statements used by this plugin. If not mentioned in this list the plugin does not support that statement type.

• creation_statements (list: <required>) – Specifies the database statements executed to create and configure a user. Must be a semicolon-separated string, a base64-encoded semicolon-separated string, a serialized JSON string array, or a base64-encoded serialized JSON string array. The {{name}}, {{password}} and {{expiration}} values will be substituted. The generated password will be a random alphanumeric 20 character string.

• revocation_statements (list: []) – Specifies the database statements to be executed to revoke a user. Must be a semicolon-separated string, a base64-encoded semicolon-separated string, a serialized JSON string array, or a base64-encoded serialized JSON string array. The {{name}} value will be substituted. If not provided defaults to a generic drop user statement.

• rollback_statements (list: []) – Specifies the database statements to be executed rollback a create operation in the event of an error. Not every plugin type will support this functionality. Must be a semicolon-separated string, a base64-encoded semicolon-separated string, a serialized JSON string array, or a base64-encoded serialized JSON string array. The {{name}} value will be substituted.

• renew_statements (list: []) – Specifies the database statements to be executed to renew a user. Not every plugin type will support this functionality. Must be a semicolon-separated string, a base64-encoded semicolon-separated string, a serialized JSON string array, or a base64-encoded serialized JSON string array. The {{name}} and {{expiration}} values will be substituted.

• rotation_statements (list: []) – Specifies the database statements to be executed to rotate the password for a given username. Must be a semicolon-separated string, a base64-encoded semicolon-separated string, a serialized JSON string array, or a base64-encoded serialized JSON string array. The {{name}} and {{password}} values will be substituted. The generated password will be a random alphanumeric 20 character string.