Monday, October 11, 2021

Db2 on Cloud credentials and how to connect from your app

Over the past 12 months, Db2 on Cloud migrated instances to a new deployment model. It seems to be based on the IBM Cloud Databases model and resulted in a different structure for the service credentials. Previously, Db2 on Cloud instances were accessible on the typical ports 50000 and 50001. The JSON-based credentials object included ready-to-use connection URIs. Now, after the change, the VCAP object has more parts, but is missing the easy-to-use URIs. In the following, I am showing you how to consume the new credential structure in your app and to successfully connect to Db2 on Cloud.

Db2 connection information

In order to connect to Db2 or other database systems like Oracle, PostgreSQL, or MySQL, you typically need the following information:

  • hostname: Location (server address) of the Db2 instance. For the new instances it typically is *
  • port: The port to connect to.
  • database: The actual database name. For Db2 on Cloud it traditionally is bludb.
  • username: The user ID for the connection.
  • password: The password for the user ID

Be aware that Db2 on Cloud and Db2 Warehouse on Cloud allow access based on IBM Cloud IAM API keys and access token. Thus, a user name and password are not always needed.

With the update to the new deployment model, SSL/TLS-based access is enforced. By default, all network traffic is encrypted. If you were not using SSL/TLS before, your app needs more changes.

Decode the credentials

The following shows a part of an actual VCAP object. It is a JSON object. To connect to Db2, all interesting information is in the "db2" sub-object. It includes the authentication info (username and password), the database as well as an array of hosts with the hostname and port.

Db2 on Cloud credentials (snippet)

Sample code to extract the connection information and form the URI is available. See this Node.js code as discussed in the tutorial on building a database-driven Slackbot. A Python example with SQLAlchemy is used in the tutorial on serverless eventing and data retrieval. Be aware that in both cases the connection property "Security=SSL;" is added to tell the driver that SSL/TLS is expected.


The new deployment model for Db2 on Cloud, including its free lite plan, change the structure of the credentials object. Knowing what makes up a connection string and how to extract it from the metadata, makes it simple to connect from your app to Db2.

If you have feedback, suggestions, or questions about this post, please reach out to me on Twitter (@data_henrik) or LinkedIn.