Skip to main content

Cosmos DB Explorer in VS Code

The Azure Databases extension for VS Code lets you browse databases and containers, run queries, and inspect documents — all from the sidebar. It works with both Topaz-emulated Cosmos DB accounts and real Azure Cosmos DB accounts.

Prerequisites​

Trust the certificate in Node.js​

The Azure Databases extension runs on Node.js, which does not automatically pick up certificates trusted at the OS level. You must set the NODE_EXTRA_CA_CERTS environment variable to point to the Topaz root CA certificate before launching VS Code.

Add the following to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export NODE_EXTRA_CA_CERTS="/path/to/topaz.crt"

Replace /path/to/topaz.crt with the actual path — for example /usr/local/share/topaz/topaz.crt on Linux, or the path where you cloned/installed Topaz.

After adding the variable, restart VS Code from the terminal (so it inherits the updated environment) for the change to take effect.

tip

On macOS, launching VS Code from Spotlight or the Dock may not pick up shell profile changes. Always launch from the terminal after updating environment variables:

code .

Connect to a Cosmos DB account​

In the VS Code sidebar, open the Azure Databases panel and expand Cosmos DB Accounts.

Local emulator​

  1. Expand Local Emulators → NoSQL Emulator : 8895.
  2. Click + New Emulator Connection....
  3. Paste the connection string from the Topaz Portal.

Real Azure Cosmos DB account​

  1. Click + New Connection... at the bottom of the Cosmos DB Accounts tree.
  2. Paste the connection string from the Azure Portal (Cosmos DB account → Keys → Primary Connection String).

Local emulator connection string​

Retrieve the connection string from the Topaz Portal or from the ARM API. It follows this format:

AccountEndpoint=https://{account-name}.documents.topaz.local.dev:8895/;AccountKey={key};

For example:

AccountEndpoint=https://my-cosmos.documents.topaz.local.dev:8895/;AccountKey=4KnaN3jL...==;

Real Azure Cosmos DB connection string​

Use the connection string from the Azure Portal (Cosmos DB account → Keys → Primary Connection String):

AccountEndpoint=https://{account-name}.documents.azure.com:443/;AccountKey={key};

Browse and query​

Once connected, the account appears in the Databases tree. You can:

  • Expand the account to see databases and containers
  • Right-click a container and select Open Query Editor to run SQL queries
  • Use standard Cosmos DB SQL syntax, for example:
SELECT TOP 10 * FROM c
SELECT * FROM c WHERE c.id = "my-document"
SELECT c.name, c.createdAt FROM c ORDER BY c.createdAt DESC OFFSET 0 LIMIT 20

Troubleshooting​

ErrorCauseFix
Unable to verify the first certificateNODE_EXTRA_CA_CERTS not set or VS Code not restartedSet the env var and relaunch VS Code from the terminal
The Cosmos DB account could not be resolvedWrong account name in the connection string endpointMake sure the hostname matches the actual account name, e.g. my-cosmos.documents.topaz.local.dev
ERR_CERT_AUTHORITY_INVALID in browserCertificate not installed in the OS trust storeRun sudo security add-trusted-cert (macOS) or update-ca-certificates (Linux)
Star on GitHub