Skip to main content

users

Creates, updates, deletes, gets or lists a users resource.

Overview​

Nameusers
TypeResource
Iddigitalocean.databases.users

Fields​

The following fields are returned by SELECT queries:

A JSON object with a key of user.

NameDatatypeDescription
namestringThe name of a database user. (example: app-01)
access_certstringAccess certificate for TLS client authentication. (Kafka only) (example: -----BEGIN CERTIFICATE-----
MIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA
MEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD
ExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x
NzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j
b20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz8pnK6V52SVf+
CYssOfCQHAx5f0Ou5rYbq3xNh8VWHIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb
8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4
oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz
Z03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna
k/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb
QwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB
BQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1
MbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG
CCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl
dHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s
ZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu
Zy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgWrgeYGCysGAQQBgt8TAQEBMIHW
MCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB
BQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1
cG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp
dGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBodHRwczovL2xldHNl
bmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM
PKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e
iXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD
D3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL9p+UIY39X0dV3WOboW2Re8nrkFXJ7
q9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/
WyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu
UlF1zblDmg2Iaw==
-----END CERTIFICATE-----)
access_keystringAccess key for TLS client authentication. (Kafka only) (example: -----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBIZMz8pnK6V52
SVf+CYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1
DwGb8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86X
wrE4oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3w
Z2mzZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1F
ZRnak/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFX
fqqbQwuRAgMBAAECggEBAILLmkW0JzOkmLTDNzR0giyRkLoIROqDpfLtjKdwm95l
9NUBJcU4vCvXQITKt/NhtnNTexcowg8pInb0ksJpg3UGE+4oMNBXVi2UW5MQZ5cm
cVkQqgXkBF2YAY8FMaB6EML+0En2+dGR/3gIAr221xsFiXe1kHbB8Nb2c/d5HpFt
eRpLVJnK+TxSr78PcZA8DDGlSgwvgimdAaFUNO2OqB9/0E9UPyKk2ycdff/Z6ldF
0hkCLtdYTTl8Kf/OwjcuTgmA2O3Y8/CoQX/L+oP9Rvt9pWCEfuebiOmHJVPO6Y6x
gtQVEXwmF1pDHH4Qtz/e6UZTdYeMl9G4aNO2CawwcaYECgYEA57imgSOG4XsJLRh
GGncV9R/xhy4AbDWLtAMzQRX4ktvKCaHWyQV2XK2we/cu29NLv2Y89WmerTNPOU+
P8+pB31uty2ELySVn15QhKpQClVEAlxCnnNjXYrii5LOM80+lVmxvQwxVd8Yz8nj
IntyioXNBEnYS7V2RxxFGgFun1cCgYEA1V3W+Uyamhq8JS5EY0FhyGcXdHd70K49
W1ou7McIpncf9tM9acLS1hkI98rd2T69Zo8mKoV1V2hjFaKUYfNys6tTkYWeZCcJ
3rW44j9DTD+FmmjcX6b8DzfybGLehfNbCw6n67/r45DXIV/fk6XZfkx6IEGO4ODt
Nfnvx4TuI1cCgYBACDiKqwSUvmkUuweOo4IuCxyb5Ee8v98P5JIE/VRDxlCbKbpx
pxEam6aBBQVcDi+n8o0H3WjjlKc6UqbW/01YMoMrvzotxNBLz8Y0QtQHZvR6KoCG
RKCKstxTcWflzKuknbqN4RapAhNbKBDJ8PMSWfyDWNyaXzSmBdvaidbF1QKBgDI0
o4oD0Xkjg1QIYAUu9FBQmb9JAjRnW36saNBEQS/SZg4RRKknM683MtoDvVIKJk0E
sAlfX+4SXQZRPDMUMtA+Jyrd0xhj6zmhbwClvDMr20crF3fWdgcqtft1BEFmsuyW
JUMe5OWmRkjPI2+9ncDPRAllA7a8lnSV/Crph5N/AoGBAIK249temKrGe9pmsmAo
QbNuYSmwpnMoAqdHTrl70HEmK7ob6SIVmsR8QFAkH7xkYZc4Bxbx4h1bdpozGB+/
AangbiaYJcAOD1QyfiFbflvI1RFeHgrk7VIafeSeQv6qu0LLMi2zUbpgVzxt78Wg
eTuK2xNR0PIM8OI7pRpgyj1I
-----END PRIVATE KEY-----)
mysql_settingsobject
passwordstringA randomly generated password for the database user.
Requires database:view_credentials scope. (example: jge5lfxtzhx42iff)
rolestringA string representing the database user's role. The value will be either "primary" or "normal". (example: normal)
settingsobject

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
databases_get_userselectdatabase_cluster_uuid, usernameTo show information about an existing database user, send a GET request to
/v2/databases/$DATABASE_ID/users/$USERNAME.

Note: User management is not supported for Caching or Valkey clusters.

The response will be a JSON object with a user key. This will be set to an object
containing the standard database user attributes. The user's password will not show
up unless the database:view_credentials scope is present.

For MySQL clusters, additional options will be contained in the mysql_settings
object.

For Kafka clusters, additional options will be contained in the settings object.

For MongoDB clusters, additional information will be contained in the mongo_user_settings object
databases_list_usersselectdatabase_cluster_uuidTo list all of the users for your database cluster, send a GET request to
/v2/databases/$DATABASE_ID/users.

Note: User management is not supported for Caching or Valkey clusters.

The result will be a JSON object with a users key. This will be set to an array
of database user objects, each of which will contain the standard database user attributes.
User passwords will not show without the database:view_credentials scope.

For MySQL clusters, additional options will be contained in the mysql_settings object.

For MongoDB clusters, additional information will be contained in the mongo_user_settings object
databases_add_userinsertdatabase_cluster_uuid, data__nameTo add a new database user, send a POST request to /v2/databases/$DATABASE_ID/users
with the desired username.

Note: User management is not supported for Caching or Valkey clusters.

When adding a user to a MySQL cluster, additional options can be configured in the
mysql_settings object.

When adding a user to a Kafka cluster, additional options can be configured in
the settings object.

When adding a user to a MongoDB cluster, additional options can be configured in
the settings.mongo_user_settings object.

The response will be a JSON object with a key called user. The value of this will be an
object that contains the standard attributes associated with a database user including
its randomly generated password.
databases_update_userreplacedatabase_cluster_uuid, username, data__settingsTo update an existing database user, send a PUT request to /v2/databases/$DATABASE_ID/users/$USERNAME
with the desired settings.

Note: only settings can be updated via this type of request. If you wish to change the name of a user,
you must recreate a new user.

The response will be a JSON object with a key called user. The value of this will be an
object that contains the name of the update database user, along with the settings object that
has been updated.
databases_delete_userdeletedatabase_cluster_uuid, usernameTo remove a specific database user, send a DELETE request to
/v2/databases/$DATABASE_ID/users/$USERNAME.

A status of 204 will be given. This indicates that the request was processed
successfully, but that no response body is needed.

Note: User management is not supported for Caching or Valkey clusters.
databases_reset_authexecdatabase_cluster_uuid, usernameTo reset the password for a database user, send a POST request to
/v2/databases/$DATABASE_ID/users/$USERNAME/reset_auth.

For mysql databases, the authentication method can be specifying by
including a key in the JSON body called mysql_settings with the auth_plugin
value specified.

The response will be a JSON object with a user key. This will be set to an
object containing the standard database user attributes.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
database_cluster_uuidstring (uuid)A unique identifier for a database cluster. (example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30)
usernamestringThe name of the database user. (example: app-01)

SELECT examples​

To show information about an existing database user, send a GET request to
/v2/databases/$DATABASE_ID/users/$USERNAME.

Note: User management is not supported for Caching or Valkey clusters.

The response will be a JSON object with a user key. This will be set to an object
containing the standard database user attributes. The user's password will not show
up unless the database:view_credentials scope is present.

For MySQL clusters, additional options will be contained in the mysql_settings
object.

For Kafka clusters, additional options will be contained in the settings object.

For MongoDB clusters, additional information will be contained in the mongo_user_settings object

SELECT
name,
access_cert,
access_key,
mysql_settings,
password,
role,
settings
FROM digitalocean.databases.users
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' -- required
AND username = '{{ username }}' -- required;

INSERT examples​

To add a new database user, send a POST request to /v2/databases/$DATABASE_ID/users
with the desired username.

Note: User management is not supported for Caching or Valkey clusters.

When adding a user to a MySQL cluster, additional options can be configured in the
mysql_settings object.

When adding a user to a Kafka cluster, additional options can be configured in
the settings object.

When adding a user to a MongoDB cluster, additional options can be configured in
the settings.mongo_user_settings object.

The response will be a JSON object with a key called user. The value of this will be an
object that contains the standard attributes associated with a database user including
its randomly generated password.

INSERT INTO digitalocean.databases.users (
data__name,
data__mysql_settings,
data__settings,
data__readonly,
database_cluster_uuid
)
SELECT 
'{{ name }}' --required,
'{{ mysql_settings }}',
'{{ settings }}',
{{ readonly }},
'{{ database_cluster_uuid }}'
RETURNING
user
;

REPLACE examples​

To update an existing database user, send a PUT request to /v2/databases/$DATABASE_ID/users/$USERNAME
with the desired settings.

Note: only settings can be updated via this type of request. If you wish to change the name of a user,
you must recreate a new user.

The response will be a JSON object with a key called user. The value of this will be an
object that contains the name of the update database user, along with the settings object that
has been updated.

REPLACE digitalocean.databases.users
SET 
data__settings = '{{ settings }}'
WHERE 
database_cluster_uuid = '{{ database_cluster_uuid }}' --required
AND username = '{{ username }}' --required
AND data__settings = '{{ settings }}' --required
RETURNING
user;

DELETE examples​

To remove a specific database user, send a DELETE request to
/v2/databases/$DATABASE_ID/users/$USERNAME.

A status of 204 will be given. This indicates that the request was processed
successfully, but that no response body is needed.

Note: User management is not supported for Caching or Valkey clusters.

DELETE FROM digitalocean.databases.users
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' --required
AND username = '{{ username }}' --required;

Lifecycle Methods​

To reset the password for a database user, send a POST request to
/v2/databases/$DATABASE_ID/users/$USERNAME/reset_auth.

For mysql databases, the authentication method can be specifying by
including a key in the JSON body called mysql_settings with the auth_plugin
value specified.

The response will be a JSON object with a user key. This will be set to an
object containing the standard database user attributes.

EXEC digitalocean.databases.users.databases_reset_auth 
@database_cluster_uuid='{{ database_cluster_uuid }}' --required, 
@username='{{ username }}' --required 
@@json=
'{
"mysql_settings": "{{ mysql_settings }}"
}';