Configure Database Credentials

Database credentials provide programmatic and application-level access to data on a database. Only database credentials can access data.

This page provides information about database credentials and how they work. You will also find procedures for creating and managing database credentials for a database, allowing you to provide programmatic and application-level access to data.

About Database Credentials

Database credentials are separate from organization roles. While organization roles control what you can do within an organization, such as creating projects, a database credential is still required to access data on a database. Database credentials are also distinct from project roles, but only project members with the Project Owner role can create them.

A database credential is specific to a database and consists of a database access name, secret, and a set of bucket and scope access levels. It’s required for applications to remotely authenticate on a database and access bucket data.

Database credentials are distinct and not associated with a particular user. They don’t control access to data tools like the Query tab in the Capella UI.

Database Credentials and Access

You assign database credentials on a per bucket or per scope basis. For example, you could assign a database credential to access all buckets and scopes in a database, assign different access levels to individual buckets, or assign access to just a single scope. This system allows you to mix and match access levels to different buckets and scopes in a database to satisfy your application and security requirements.

The following table describes the available bucket access options and their associated privileges.

Table 1. Database Access Privileges
Access	Description
`Read`	Grants the privileges of the following Couchbase roles: `data_reader` `data_dcp_reader` `data_monitoring` `fts_searcher` `query_select` `analytics_reader` `query_execute_global_functions` `query_execute_global_external_functions` `analytics_select` `external_stats_reader` ^[1] `query_execute_functions` `query_execute_external_functions` 1. The `external_stats_reader` role is only granted when a database credential is given read access to all buckets in a database.
`Write`	Grants the privileges of the following Couchbase roles: `data_writer` `fts_admin` `query_insert` `query_update` `query_delete` `query_manage_index` `replication_target` `analytics_admin` `query_manage_global_functions` `query_manage_global_external_functions` `analytics_manager` `scope_admin` `query_manage_functions` `query_manage_external_functions`
`Read/Write`	Grants the privileges of the following Couchbase roles: All the privileges of Read. All the privileges of Write.

Accessing Database Credentials

Permissions Required

To access the database credentials for a database, you must have any of the following roles for the project containing the database:

Only the Project Owner role allows you to create and modify database credentials.

The Database Access page lists any existing database credentials for a database and allows you to create new ones. To open the Database Access page:

Open the database’s Settings tab.
1. With the Projects tab in your organization open, click the name of the project you’re working with.
2. Click the name of the database that you’re working with.
3. Click the Settings tab.
In the navigation menu, click Database Access.

The Database Access page is shown for the current database:

Database Access Summary

The database access page is in a table format, with sortable columns and rows for each database credential.

The following information is shown about each database credential:

Database Access Name

The name that identifies the database credential.

Created By

The organization user that created the database credential.

Created On

The creation date of the database credential and its age. The color-coded status indicator in this column is based on age to help identify older credentials that need rotation. The colors indicate the following:

Green: Under 90 days old
Yellow: 90—180 days old
Red: Over 180 days old

A Trash icon shown at the end of each row can be used to delete the corresponding database credential.

Creating Database Credentials

Permissions Required

To create a database credential, you must have the Project Owner role for the project containing the database where you’re creating the database credential.

Open the Database Access page for your database:
1. With the Projects tab in your organization open, click the project with the database you’re working with.
2. With the Databases tab open, select your database.
3. Click the Settings tab.
4. In the navigation menu, click Database Access.
Click Create Database Access

Specify the database access name and secret.

Database Access Name

The database access name can’t exceed 35 characters in length and can’t contain the following characters: ( ) < > @ , ; : \ " / [ ] ? = { }

Secret

Secrets must be at least eight characters in length. They need one or more uppercase letters, lowercase letters, numbers, and special characters: @ % + \ \ / ' \ " ! # $ ^ ? : , ( ) { } [ ] ~ ` - _

Once you create a database credential, you can’t change the secret. This prevents situations where a credential’s secret is changed in Capella, but not in an application. The best practice to follow when rotating credentials is to:

Create a new database credential in Capella
Update your application to use the new database credential
Delete the old database credential

Select bucket-level access.

In the Bucket Level Access section, use the Bucket drop-down menu to specify a bucket you want this database credential to access To grant access to all current and future buckets in the database, choose the All Buckets option.
Select scope-level access

Use the Scope drop-down menu to specify a scope you want this database credential to access. To grant access to all current and future scopes in the selected bucket, choose the All Scopes option.
Select access level.

Use the Access drop-down menu to specify Read, Write, or Read/Write access to the chosen bucket and scope selection.
(Optional) Add another level of access.

Database credentials can access a selection of multiple buckets and scopes within a database.
1. Click Add Another.
  
  The Bucket Level Access section adds another line where you can select another bucket and scope for this database credential to access.
Once you’ve finished making the desired configurations, click Create Database Access.

Remember that you can’t use database credentials to log into the Couchbase Capella UI or manage Capella features. Database credentials are used for reading or writing bucket data using the Couchbase SDK and other supported tools.

Modify Database Credentials

Permissions Required

To modify a database credential, you must have the Project Owner role for the project with the database credential

Open the Database Access page for your database:
1. With the Projects tab in your organization open, click the project with the database you’re working with.
2. With the Databases tab open, select your database.
3. Click the Settings tab.
4. In the navigation menu, click Database Access.
Click the access name of the database credential you’re modifying.
In the Bucket Level Access section, change any existing levels of access or add more.

See the access selection steps for creating a database credential for details on choosing bucket and scope access levels.
Once you’ve made your changes, click Apply.

Deleting Database Credentials

Deleting a database credential can cause an application that’s using it to stop functioning. Always make sure that you’ve updated your application to use new credentials before deleting a database credential.

Permissions Required

To delete a database credential, you must have the Project Owner role for the project with the database credential.

Open the Database Access page for your database:
1. With the Projects tab in your organization open, click the project with the database you’re working with.
2. With the Databases tab open, select your database.
3. Click the Settings tab.
4. In the navigation menu, click Database Access.
At the end of the row for the database credential that you want to delete, click the Trash icon .

This opens the Delete Database Access dialog.
Type delete into the provided field and click Delete Database Access.

A small notification indicates that the database credential is deleted.

Manage Database Credentials with Hashicorp Vault

Our Hashicorp Vault plug-in can serve as a centralized hub for secrets management. In addition to managing existing secrets, Vault’s Database Secrets Engine generates dynamic, short-lived database credentials. This streamlines the management of database connections and roles, and you can even customize permissions and TTL settings.

Full details can be found on the plug-in site.