diff --git a/website/content/api-docs/secret/databases/postgresql.mdx b/website/content/api-docs/secret/databases/postgresql.mdx index b11f0e2c44..95e9f36068 100644 --- a/website/content/api-docs/secret/databases/postgresql.mdx +++ b/website/content/api-docs/secret/databases/postgresql.mdx @@ -29,7 +29,9 @@ has a number of parameters to further configure a connection. parameters in the following format `{{field_name}}`. Certificate authentication can be used by setting `?sslinline=true` and giving the SSL credentials in the `sslrootcert`, `sslcert` and `sslkey` credentials. A templated connection URL - is required when using root credential rotation. + 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. - `max_open_connections` `(int: 4)` - Specifies the maximum number of open connections to the database. @@ -78,7 +80,7 @@ has a number of parameters to further configure a connection. -### Sample Payload +### Sample Payload with URI-format Connection String ```json { @@ -92,6 +94,20 @@ has a number of parameters to further configure a connection. } ``` +### Sample Payload with Keyword/Value-format Connection String + +```json +{ + "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 ```shell-session @@ -102,6 +118,30 @@ $ curl \ 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](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) +for more information. Below are two small examples. + +#### URI-format Multi-Host String: + +```json +{ + "connection_url": "postgresql://{{username}}:{{password}}@hostone:5432,hosttwo:5432,hostthree:9999/postgres" +} +``` + +#### Keyword/Value-format Multi-Host String: + +```json +{ + "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 diff --git a/website/content/docs/secrets/databases/postgresql.mdx b/website/content/docs/secrets/databases/postgresql.mdx index 67280c32b2..ca4905fd11 100644 --- a/website/content/docs/secrets/databases/postgresql.mdx +++ b/website/content/docs/secrets/databases/postgresql.mdx @@ -32,7 +32,7 @@ options, including SSL options, can be found in the [pgx][pgxlib] and 1. Enable the database secrets engine if it is not already enabled: - ```text + ```shell-session $ vault secrets enable database Success! Enabled the database secrets engine at: database/ ``` @@ -42,9 +42,9 @@ options, including SSL options, can be found in the [pgx][pgxlib] and 1. Configure Vault with the proper plugin and connection information: - ```text + ```shell-session $ vault write database/config/my-postgresql-database \ - plugin_name=postgresql-database-plugin \ + plugin_name="postgresql-database-plugin" \ allowed_roles="my-role" \ connection_url="postgresql://{{username}}:{{password}}@localhost:5432/" \ username="vaultuser" \ @@ -54,9 +54,9 @@ options, including SSL options, can be found in the [pgx][pgxlib] and 1. Configure a role that maps a name in Vault to an SQL statement to execute to create the database credential: - ```text + ```shell-session $ vault write database/roles/my-role \ - db_name=my-postgresql-database \ + db_name="my-postgresql-database" \ creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; \ GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \ default_ttl="1h" \ @@ -72,7 +72,7 @@ the proper permission, it can generate credentials. 1. Generate a new credential by reading from the `/creds` endpoint with the name of the role: - ```text + ```shell-session $ vault read database/creds/my-role Key Value --- -----