open-vault/website/content/api-docs/secret/databases/index.mdx

---
layout: api
page_title: Database - Secrets Engines - HTTP API
description: Top page for database secrets engine information
---

# Database Secrets Engine (API)

This is the API documentation for the Vault Database secrets engine. For
general information about the usage and operation of the database secrets engine,
please see the
[Vault database secrets engine documentation](/docs/secrets/databases).

This documentation assumes the database secrets engine is enabled at the
`/database` path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.

## Configure Connection

This endpoint configures the connection string used to communicate with the
desired database. In addition to the parameters listed here, each Database
plugin has additional, database plugin specific, parameters for this endpoint.
Please read the HTTP API for the plugin you'd wish to configure to see the full
list of additional parameters.

~> This endpoint distinguishes between `create` and `update` ACL capabilities.

| Method | Path                     |
| :----- | :----------------------- |
| `POST` | `/database/config/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name for this database
  connection. This is specified as part of the URL.

- `plugin_name` `(string: <required>)` - Specifies the name of the plugin to use
  for this connection.

- `verify_connection` `(bool: true)` – Specifies if the connection is verified
  during initial configuration. Defaults to true.

- `allowed_roles` `(list: [])` - List of the roles allowed to use this connection.
  Defaults to empty (no roles), if contains a `*` any role can use this connection.

- `root_rotation_statements` `(list: [])` - Specifies the database statements to be
  executed to rotate the root user's credentials. See the plugin's API page for more
  information on support and formatting for this parameter.

- `password_policy` `(string: "")` - The name of the
  [password policy](/docs/concepts/password-policies) to use when generating passwords
  for this database. If not specified, this will use a default policy defined as:
  20 characters with at least 1 uppercase, 1 lowercase, 1 number, and 1 dash character.

~> We highly recommended that you use a Vault-specific user rather than the admin user
in your database when configuring the plugin. This user will be used to
create/update/delete users within the database so it will need to have the appropriate
permissions to do so. If the plugin supports
[rotating the root credentials](#rotate-root-credentials), we highly recommended
you perform that action after configuring the plugin. This will change the password
of the user configured in this step. The new password will **not** be viewable by users.

### Common fields

There are several common fields that you will see across many of the database plugins.
Please reference the individual plugin documentation for details on whether these fields
are supported and any additional details about them.

- `connection_url` `(string)` - Specifies the connection string used to connect to the
  database. Some plugins use `url` rather than `connection_url`. This allows for simple
  templating of the username and password of the root user. Typically, this is done by
  including a `{{username}}`, `{{name}}`, and/or `{{password}}` field within the string.
  These fields are typically be replaced with the values in the `username` and
  `password` fields.

- `username` `(string)` - Specifies the name of the user to use as the "root" user when
  connecting to the database. This "root" user is used to create/update/delete users
  managed by these plugins, so you will need to ensure that this user has permissions to
  manipulate users appropriate to the database. This is typically used in the
  `connection_url` field via the templating directive `{{username}}` or `{{name}}`.

- `password` `(string)` - Specifies the password to use when connecting with the
  `username`. This value will not be returned by Vault when performing a read upon the
  configuration. This is typically used in the `connection_url` field via the templating
  directive `{{password}}`.

- `disable_escaping` `(boolean: false)` - Determines whether symbol characters in the
  username and password fields will be escaped. Useful for alternate connection string
  formats like ADO. More information regarding this parameter can be found on the
  [databases secrets engine docs.](/docs/secrets/databases#disable-character-escaping)
  Defaults to `false`.

### Sample Payload

```json
{
  "plugin_name": "mysql-database-plugin",
  "allowed_roles": "readonly",
  "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
  "username": "vaultuser",
  "password": "secretpassword"
}
```

### Sample cURL Request

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

### Sample CLI Request

```shell-session
$ vault write database/config/mysql \
    plugin_name="mysql-database-plugin" \
    allowed_roles="readonly" \
    connection_url="{{username}}:{{password}}@tcp(127.0.0.1:3306)/" \
    username="vaultuser" \
    password="secretpassword"
```

### Sample CLI Request with ADO-style Connection String

```shell-session
$ vault write database/config/mssql \
    plugin_name="mssql-database-plugin" \
    connection_url='server=localhost;port=1433;user id={{username}};password={{password}};database=mssql;' \
    username="vaultuser" \
    password='#secret(password)' \
    disable_escaping="true"
```

## Read Connection

This endpoint returns the configuration settings for a connection.

| Method | Path                     |
| :----- | :----------------------- |
| `GET`  | `/database/config/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the connection to read.
  This is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/database/config/mysql
```

### Sample Response

```json
{
  "data": {
    "allowed_roles": ["readonly"],
    "connection_details": {
      "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
      "username": "vaultuser"
    },
    "plugin_name": "mysql-database-plugin"
  }
}
```

## List Connections

This endpoint returns a list of available connections. Only the connection names
are returned, not any values.

| Method | Path               |
| :----- | :----------------- |
| `LIST` | `/database/config` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/database/config
```

### Sample Response

```json
{
  "data": {
    "keys": ["db-one", "db-two"]
  }
}
```

## Delete Connection

This endpoint deletes a connection.

| Method   | Path                     |
| :------- | :----------------------- |
| `DELETE` | `/database/config/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the connection to delete.
  This is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/database/config/mysql
```

## Reset Connection

This endpoint closes a connection and it's underlying plugin and restarts it
with the configuration stored in the barrier.

| Method | Path                    |
| :----- | :---------------------- |
| `POST` | `/database/reset/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the connection to reset.
  This is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/database/reset/mysql
```

## Rotate Root Credentials

This endpoint is used to rotate the "root" user credentials stored for
the database connection. This user must have permissions to update its own
password.

| Method | Path                          |
| :----- | :---------------------------- |
| `POST` | `/database/rotate-root/:name` |

!> **Use caution:** the root user's password will not be accessible once rotated so it is highly
recommended that you create a user for Vault to utilize rather than using the actual root user.

### Parameters

- `name` `(string: <required>)` – Specifies the name of the connection to rotate.
  This is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/database/rotate-root/mysql
```

## Create Role

This endpoint creates or updates a role definition.

~> This endpoint distinguishes between `create` and `update` ACL capabilities.

| Method | Path                    |
| :----- | :---------------------- |
| `POST` | `/database/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to create. This
  is specified as part of the URL.

- `db_name` `(string: <required>)` - The name of the database connection to use
  for this role.

- `default_ttl` `(string/int: 0)` - Specifies the TTL for the leases
  associated with this role. Accepts time suffixed strings (`1h`) or an integer
  number of seconds. Defaults to system/engine default TTL time.

- `max_ttl` `(string/int: 0)` - Specifies the maximum TTL for the leases
  associated with this role. Accepts time suffixed strings (`1h`) or an integer
  number of seconds. Defaults to `sys/mounts`'s default TTL time; this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer. See also [The TTL General Case](/docs/concepts/tokens#the-general-case).

- `creation_statements` `(list: <required>)` – Specifies the database
  statements executed to create and configure a user. See the plugin's API page
  for more information on support and formatting for this parameter.

- `revocation_statements` `(list: [])` – Specifies the database statements to
  be executed to revoke a user. See the plugin's API page for more information
  on support and formatting for this parameter.

- `rollback_statements` `(list: [])` – Specifies the database statements to be
  executed to rollback a create operation in the event of an error. Not every
  plugin type will support this functionality. See the plugin's API page for
  more information on support and formatting for this parameter.

- `renew_statements` `(list: [])` – Specifies the database statements to be
  executed to renew a user. Not every plugin type will support this
  functionality. See the plugin's API page for more information on support and
  formatting for this parameter.

### Sample Payload

```json
{
  "db_name": "mysql",
  "creation_statements": [
    "CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'",
    "GRANT SELECT ON *.* TO '{{name}}'@'%'"
  ],
  "default_ttl": "1h",
  "max_ttl": "24h"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/roles/my-role
```

## Read Role

This endpoint queries the role definition.

| Method | Path                    |
| :----- | :---------------------- |
| `GET`  | `/database/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to read. This
  is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/roles/my-role
```

### Sample Response

```json
{
  "data": {
    "creation_statements": [
      "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';",
      "GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";"
    ],
    "db_name": "mysql",
    "default_ttl": 3600,
    "max_ttl": 86400,
    "renew_statements": [],
    "revocation_statements": [],
    "rollback_statements": []
  }
}
```

## List Roles

This endpoint returns a list of available roles. Only the role names are
returned, not any values.

| Method | Path              |
| :----- | :---------------- |
| `LIST` | `/database/roles` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/database/roles
```

### Sample Response

```json
{
  "auth": null,
  "data": {
    "keys": ["dev", "prod"]
  },
  "lease_duration": 2764800,
  "lease_id": "",
  "renewable": false
}
```

## Delete Role

This endpoint deletes the role definition.

| Method   | Path                    |
| :------- | :---------------------- |
| `DELETE` | `/database/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to delete. This
  is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/database/roles/my-role
```

## Generate Credentials

This endpoint generates a new set of dynamic credentials based on the named
role.

| Method | Path                    |
| :----- | :---------------------- |
| `GET`  | `/database/creds/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to create
  credentials against. This is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/creds/my-role
```

### Sample Response

```json
{
  "data": {
    "username": "root-1430158508-126",
    "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21"
  }
}
```

## Create Static Role

This endpoint creates or updates a static role definition. Static Roles are a
1-to-1 mapping of a Vault Role to a user in a database which are automatically
rotated based on the configured `rotation_period`. Not all databases support
Static Roles, please see the database-specific documentation.

~> This endpoint distinguishes between `create` and `update` ACL capabilities.

~> Vault will rotate the password when creating a static role. Vault must do
this in order to know the password.

| Method | Path                           |
| :----- | :----------------------------- |
| `POST` | `/database/static-roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to create. This
  is specified as part of the URL.

- `username` `(string: <required>)` – Specifies the database username that this
  Vault role corresponds to.

- `rotation_period` `(string/int: <required>)` – Specifies the amount of time
  Vault should wait before rotating the password. The minimum is 5 seconds.

- `db_name` `(string: <required>)` - The name of the database connection to use
  for this role.

- `rotation_statements` `(list: [])` – Specifies the database statements to be
  executed to rotate the password for the configured database user. Not every
  plugin type will support this functionality. See the plugin's API page for
  more information on support and formatting for this parameter.

### Sample Payload

```json
{
  "db_name": "mysql",
  "username": "static-database-user",
  "rotation_statements": [
    "ALTER USER \"{{name}}\" WITH PASSWORD '{{password}}';"
  ],
  "rotation_period": "1h"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/static-roles/my-static-role
```

## Read Static Role

This endpoint queries the static role definition.

| Method | Path                           |
| :----- | :----------------------------- |
| `GET`  | `/database/static-roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the static role to read.
  This is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/static-roles/my-static-role
```

### Sample Response

```json
{
  "data": {
    "db_name": "mysql",
    "username": "static-user",
    "rotation_statements": [
      "ALTER USER \"{{name}}\" WITH PASSWORD '{{password}}';"
    ],
    "rotation_period": "1h"
  }
}
```

## List Static Roles

This endpoint returns a list of available static roles. Only the role names are
returned, not any values.

| Method | Path                     |
| :----- | :----------------------- |
| `LIST` | `/database/static-roles` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/database/static-roles
```

### Sample Response

```json
{
  "auth": null,
  "data": {
    "keys": ["dev-static", "prod-static"]
  }
}
```

## Delete Static Role

This endpoint deletes the static role definition. The user, having been defined externally,
must be cleaned up manually.

| Method   | Path                           |
| :------- | :----------------------------- |
| `DELETE` | `/database/static-roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the static role to
  delete. This is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/database/static-roles/my-role
```

## Get Static Credentials

This endpoint returns the current credentials based on the named static role.

| Method | Path                           |
| :----- | :----------------------------- |
| `GET`  | `/database/static-creds/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the static role to get
  credentials for. This is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/static-creds/my-static-role
```

### Sample Response

```json
{
  "data": {
    "username": "static-user",
    "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21",
    "last_vault_rotation": "2019-05-06T15:26:42.525302-05:00",
    "rotation_period": 30,
    "ttl": 28
  }
}
```

## Rotate Static Role Credentials

This endpoint is used to rotate the Static Role credentials stored for a given
role name. While Static Roles are rotated automatically by Vault at configured
rotation periods, users can use this endpoint to manually trigger a rotation to
change the stored password and reset the TTL of the Static Role's password.

| Method | Path                          |
| :----- | :---------------------------- |
| `POST` | `/database/rotate-role/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the Static Role to
  trigger the password rotation for. The name is specified as part of the URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/database/rotate-role/my-static-role
```