Skip to main content

Connect to CosmosDB

Connect CosmosDB to Retool and read, create, replace, and delete items in your containers.

CosmosDB is Microsoft Azure's fully managed NoSQL database, which stores data as JSON documents in containers.

What you can do with CosmosDB in Retool​

After you create a CosmosDB resource in Retool, you can:

  • Read items from a container with a SQL-like query.
  • Create new items in a container.
  • Replace the content of an existing item.
  • Delete items from a container.

Before you begin​

To connect CosmosDB to Retool, you need the following:

  • CosmosDB account: An Azure Cosmos DB account with a database and at least one container.
  • Primary or secondary key: Available from your CosmosDB account's Keys page in the Azure portal.
  • Network access: Your CosmosDB account must accept connections from Retool's IP addresses.
  • Retool permissions: Ability to create and manage resources in your organization.

Create a CosmosDB resource​

Follow these steps to create a CosmosDB resource in your Retool organization.

Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for "CosmosDB" and click the CosmosDB tile to begin configuration.

Best practice

Use folders to organize your resources by team, environment, or resource type. This helps keep your resource list manageable as your organization grows.

Configure general settings​

Specify a name and description for the resource that indicates which CosmosDB database it connects to. The description provides more context to users and Assist about how to use the resource.

Example nameExample description
Orders databaseCosmosDB account containing order and shipment records.
Catalog database (read only)Read-only CosmosDB account with product catalog items.

Configure resource credentials​

Configure the connection settings for your CosmosDB resource.

CosmosDB resource configuration form.

Host​

The hostname of your CosmosDB account, in the form [account-name].documents.azure.com.

Example
my-cosmos-account.documents.azure.com

Port​

The port your CosmosDB account listens on. Defaults to 443.

Database ID​

The name of the CosmosDB database to connect to.

Example
MyDatabase

Key​

The primary or secondary key for your CosmosDB account, available from the account's Keys page in the Azure portal.

Configure advanced options​

Configure optional settings available under the Advanced options section of the resource configuration form.

Outbound region​

By default, requests originate from your organization's default outbound region. Enable Override default outbound Retool region to route requests to CosmosDB through a different region.

Test the connection​

Click Test connection to verify Retool can connect to CosmosDB. If the test fails, check the following:

  • Network access: Ensure your CosmosDB account accepts connections from Retool's IP addresses (cloud) or your Retool instance's network (self-hosted).
  • Host: Confirm the hostname matches the value shown on your CosmosDB account's Overview page in the Azure portal.
  • Key: Verify the primary or secondary key is correct and hasn't been regenerated since you copied it.
  • Database ID: Confirm the database name is spelled and cased exactly as it appears in Azure.
Use Debug Tools for detailed connection information

After testing the connection, click View in console to open the Debug Tools console. The console displays the test query executed, its response, execution time, and error details if the test fails. This information is helpful for troubleshooting connection issues.

Save the resource​

Click Create resource to save your CosmosDB resource. You can now use it in queries across your Retool apps and automations.

Interact with CosmosDB data​

Once you've created a CosmosDB resource, you can interact with CosmosDB data using Retool.

Caution

CosmosDB isn't yet supported in the new app builder. Use a classic app, workflow, or agent instead.

For classic apps, workflows, and agents, refer to the resource query documentation to learn how to write a query.

Best practices​

Follow these best practices to maintain the security of your CosmosDB resource.

  • Apply least privilege: Use a read-only key for resources that only need to read data, and reserve the primary key for resources that must write to containers.
  • Store the key securely: Retool encrypts the Key field automatically, so you don't need to route it through a separate secrets store.
  • Use resource environments: Configure multiple resource environments to maintain separate CosmosDB accounts or keys for production, staging, and development.