Tech Note: Rotate db credentials programmatically without restarting server in Release 22.3


How do we programmatically rotate db credentials without restarting the server?

Affected Products & Versions

Release 22.3


Enabling Live Update

To use this feature, you must first enable it in xl-release.conf

xl {
features {
liveDbCredentialUpdate {
enabled = true

Performing the Update

Credentials are updated by invoking the following REST endpoint:

URL: http://{host}:{port}/{contextRoot}/settings/reloadDbConfig \ Request body:

"dbUsername": "newRepositoryUsername",
"dbPassword": "newRepositoryPassword",
"database": "repository"

The endpoint supports updating credentials for both the repository and archive database, using the database field in the request body.

Database Identifier
main database repository
archive database archive

Any other value will result with an HTTP 400 response.


Only administrators are permitted to invoke the endpoint.

Database Support

All database engines supported by Release apart from Oracle are supported

Additional Notes

  • Update doesn't require system restart
  • Update takes place immediately. However, for a system under load, it takes some time to prune the connection pools of the old connections. Maximum time to completely transition to new credentials is configured in xl.database.max-life-time for main and xl.reporting.max-life-time for archive databases. It is mandatory to have some time overlap in the validity of old and new credentials.
  • Update is performed on all running cluster nodes
  • xl-release.conf file is updated on all nodes
  • New password is written to the xl-release.conf in an encrypted format
  • If one or more cluster nodes are down during the operation, they are started up again and old credentials become invalid. The nodes refuse to start because of the inability to connect to the database. The xl-release.conf files of these nodes must be updated manually with either encrypted or clear text password.
  • The operation will not create any users in the database. It only instructs the Release to start using new credentials to connect to the selected database.
  • The credentials sent in the request body are validated for connectivity
Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.