DEV Community: Abhishek Gupta

A Chrome Extension That Talks to Your Database

Abhishek Gupta — Mon, 23 Mar 2026 06:55:35 +0000

Cosmos DB Sidekick is a Chrome extension built with the GitHub Copilot SDK and the Azure Cosmos DB JavaScript SDK. The GitHub Copilot SDK lets you embed Copilot's AI capabilities directly into your apps — available for Go, Python, TypeScript, and .NET.

It sits alongside the Cosmos DB vNext emulator Data Explorer and lets you ask questions in plain English. It writes the queries, runs them, and shows results. No copy-pasting SQL, no switching between tabs.

You can find the code on GitHub.

Here is a demo of the app in action:

What can you actually do with it?

Use natural language to query data. In response to something like "Find all orders over $100 from the last month" — the extension figures out the schema, generates a SQL query, runs it against your emulator, and streams back the results.

Write data too. Need test data? Ask it to "Add 10 test users to the users container" and it generates realistic documents with proper id fields and partition keys, then upserts them.

It knows what you're looking at. When the Cosmos DB Data Explorer is open, the extension auto-detects which database and container you're browsing. A context bar shows something like 📂 ordersDb › customers, and your questions automatically target that data. Switch to a different container in the Data Explorer — the context follows.

Conversations persist. You can have multi-turn conversations, switch between sessions, and pick up where you left off. Close the side panel, reopen it — your chat history is still there.

How the Copilot SDK makes this work

Under the hood, the extension is powered by the GitHub Copilot SDK. The architecture is straightforward:

┌─────────────────────┐
│  Chrome Extension   │
│    (side panel)     │
└────────┬────────────┘
         │ HTTP + SSE
┌────────▼────────────┐       ┌──────────────────────┐
│   Node.js Sidecar   │──────▶│  GitHub Copilot SDK  │
│                     │◀──────│  (LLM + tool calls)  │
└────────┬────────────┘       └──────────────────────┘
         │ Cosmos DB JS SDK
┌────────▼────────────┐
│  Cosmos DB vNext    │
│     Emulator        │
└─────────────────────┘

The sidecar is a lightweight Node.js server that acts as the bridge. It creates a CopilotClient, manages chat sessions, and, (most importantly) defines tools that the LLM can call autonomously. Tools are the key to the agentic behavior — they let the model interact with the external world (in this case, your Cosmos DB instance) in a structured way:

list_databases — discover what databases exist
list_containers — see containers and partition keys in a database
sample_documents — grab sample docs to understand the schema
run_query — execute a read-only SQL query
upsert_items — insert or replace documents

For example, what happens when you ask a question like "What does the schema look like?". You didn't tell it which database to query. You didn't tell it to sample documents. But the LLM chains the tools together on its own — lists databases, picks the one from your context, lists containers, samples documents, then describes what it found. That's the agentic part.

Same applies to query generation and execution - you define the tools, the SDK handles the orchestration, and the model decides the sequence.

Here's what a tool definition looks like (simplified):

{
  name: "run_query",
  description: "Execute a read-only SQL query against a Cosmos DB container.",
  parameters: {
    type: "object",
    properties: {
      database:  { type: "string", description: "The database name" },
      container: { type: "string", description: "The container name" },
      query:     { type: "string", description: "The SQL query to execute" },
    },
    required: ["database", "container", "query"],
  },
  handler: async (args) => {
    return await runQuery(args.database, args.container, args.query);
  },
}

The SDK takes care of the rest — passing tool definitions to the model, routing tool calls to your handlers, feeding results back into the conversation, and streaming the final response.

Streaming is built into the session. The sidecar subscribes to session events and forwards them over SSE to the Chrome extension, so responses appear token-by-token in the chat panel. Creating a streaming chat session is a few lines:

const session = await client.createSession({
  model: "gpt-4.1",
  systemMessage: { mode: "append", content: SYSTEM_PROMPT },
  tools: getTools(),
  streaming: true,
  onPermissionRequest: approveAll,
});

Session persistence comes for free too. The SDK's listSessions() and resumeSession() let the extension show chat history and restore previous conversations — the sidecar doesn't need its own storage layer.

Context-aware — no configuration needed

The extension watches which database and container you have open in the Data Explorer and automatically uses that as context. Ask "show me the top 10 documents" and it knows exactly where to look — no need to specify the target every time.

Try it out

The whole thing runs locally — Chrome extension + a Node.js sidecar + the Cosmos DB vNext emulator in Docker. You'll need GitHub Copilot and the Copilot CLI set up for auth.

Follow the steps in the GitHub repo to get it running, and start chatting with your database in natural language. It's a fun demo of how the GitHub Copilot SDK can turn a simple extension into an intelligent agent that understands your data and helps you interact with it seamlessly.

The bigger picture

Cosmos DB Sidekick is one specific use case, but the pattern behind it is general. Define a few tools, hand them to the Copilot SDK, and you get an agent that can reason about when and how to use them — chaining calls, handling errors, and streaming results back to the user. The SDK handles sessions, tool orchestration, and model access; you just bring the domain logic.

That same pattern works for any data source, any API, any workflow. A CLI that talks to your CI/CD pipeline. A Slack bot that queries your observability stack. A dashboard that lets non-technical teammates explore production metrics in plain English. The building blocks are the same: tools, a system prompt, and a session.

If you're looking for a starting point, the Copilot SDK has samples for Go, Python, TypeScript, and .NET. Pick your stack and start building.

DocumentDB on Kubernetes: Resilient, Highly Available Databases with Automatic Failover

Abhishek Gupta — Tue, 03 Mar 2026 08:06:34 +0000

DocumentDB is an open-source MongoDB-compatible database built on PostgreSQL that provides a familiar interface while leveraging PostgreSQL's reliability and extensibility. The DocumentDB Kubernetes Operator brings this database to Kubernetes environments by extending the platform with custom resources. The operator manages DocumentDB clusters declaratively, handling deployment, scaling, upgrades, and high availability scenarios automatically.

The DocumentDB Kubernetes Operator provides multiple levels of high availability, each addressing a different failure domain. Local HA deploys multiple database instances within a single Kubernetes cluster with automatic failover in seconds, protecting against pod and node failures. For further resilience, you can configure availability zone spreading so that replicas land in different AZs, allowing the cluster to survive a full zone outage without manual intervention. Beyond a single cluster, the operator supports multi-region HA across Azure regions (using KubeFleet) and multi-cloud HA across providers like Azure, AWS, and GCP (using Istio). Both use physical WAL replication with manual failover via kubectl documentdb promote. These levels are composable: a production deployment can combine all of them.

This post focuses on local HA, the foundational layer, and walks through automatic failover in action.

Highly Available DocumentDB deployment on Kubernetes

In single-instance database deployments, any failure (such as a pod crash, node issue, or planned upgrade) may result in downtime. Local high availability (HA) solves this problem by deploying multiple database instances within a single Kubernetes cluster. The operator creates one primary instance that handles all client operations, along with multiple replica instances that are continuously replicated via asynchronous WAL streaming. When the primary fails, a replica is automatically promoted to become the new primary, ensuring your application experiences minimal disruption.

Local HA is ideal when you need resilience within a single region without the complexity of multi-region deployments. It's a cost-effective solution for development and staging environments where you want to validate failover behavior without cloud distribution costs, as well as for production workloads that require automatic recovery from infrastructure failures. For cross-region disaster recovery scenarios, the operator also supports multi-cluster replication features.

Architecture Overview

DocumentDB's local HA leverages CloudNativePG (CNPG) as its underlying PostgreSQL foundation. CNPG handles WAL-based streaming replication and automatic failover orchestration, while DocumentDB adds the MongoDB-compatible protocol layer on top.

Here are the key components:

CNPG Cluster: Manages PostgreSQL replication (1 primary + N replicas) with WAL-based streaming
DocumentDB Gateway: A sidecar container injected into each PostgreSQL pod that translates MongoDB wire protocol to PostgreSQL DocumentDB extension calls
Kubernetes Services: Layered service architecture for different access patterns:
- Internal PostgreSQL services (port 5432): <cluster>-rw (primary), <cluster>-ro (replicas only), <cluster>-r (all instances — primary and replicas) - used for internal operations, metrics, and backups
- External Gateway service (port 10260): Routes MongoDB client traffic to the current primary by tracking the cnpg.io/instanceRole: primary label

When the primary fails, CNPG automatically detects the failure and promotes the most advanced replica to primary, updating the pod labels. The Kubernetes service automatically follows the new primary, keeping the external IP stable – no manual DNS changes required. The operator currently supports a maximum of 3 instances (instancesPerNode: 3), providing 1 primary + 2 replicas for optimal balance between availability, performance, and operational flexibility.

Let's see how this works in practice.

Setting Up the Test Environment

You need the following installed:

minikube, kubectl, and helm
Python (for the test client application)

Start your minikube cluster:

minikube start

Also make sure to clone the GitHub repository:

git clone https://github.com/abhirockzz/documentdb-local-ha-tutorial.git
cd documentdb-local-ha-tutorial

Install DocumentDB Operator

First, install cert-manager (required dependency):

helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true

Install the DocumentDB operator:

helm repo add documentdb https://documentdb.github.io/documentdb-kubernetes-operator

helm install documentdb-operator documentdb/documentdb-operator \
  --namespace documentdb-operator \
  --create-namespace \
  --wait

Verify the operator is running:

kubectl get deployment -n documentdb-operator

To check the operator version, run kubectl get pods -n documentdb-operator -o jsonpath='{.items[*].spec.containers[*].image}' && echo

Deploy Local HA Cluster

In a separate terminal, start the minikube tunnel. This creates a network route that enables LoadBalancer services to receive external IPs in your local minikube environment. The tunnel will assign an IP address to the DocumentDB service and route traffic from your host machine to the cluster, allowing the Python test client to connect:

minikube tunnel

# output:
✅  Tunnel successfully started

📌  NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible ...

The local_ha.yaml file contains the complete configuration including namespace, credentials secret, and the DocumentDB resource with instancesPerNode: 3 to create a 3-instance HA cluster.

Deploy the cluster:

kubectl apply -f local_ha.yaml

Monitor the pod status. Wait for all pods to be running (this may take 1-2 minutes). In the meantime, you should see output similar to this, and eventually all 3 pods will reach Running status:

kubectl get pods -n documentdb-preview-ns -w

# output:

NAME                                 READY   STATUS            RESTARTS   AGE
documentdb-local-ha-1-initdb-ffrjf   0/1     PodInitializing   0          3s
documentdb-local-ha-1-initdb-ffrjf   1/1     Running           0          24s
documentdb-local-ha-1-initdb-ffrjf   0/1     Completed         0          25s
documentdb-local-ha-1-initdb-ffrjf   0/1     Completed         0          27s
documentdb-local-ha-1-initdb-ffrjf   0/1     Completed         0          27s
documentdb-local-ha-1                0/2     Pending           0          0s
documentdb-local-ha-1                0/2     Pending           0          0s
//....
documentdb-local-ha-3                2/2     Running           0          11s

Go to the minikube tunnel terminal, and verify the tunnel is now active for the DocumentDB service:

Starting tunnel for service documentdb-service-documentdb-local-ha.

You can verify the external IP assigned to the service (should be 127.0.0.1 in this case):

kubectl get svc -n documentdb-preview-ns

# output:
NAME                                     TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)           AGE
documentdb-local-ha-r                    ClusterIP      10.108.176.232   <none>        5432/TCP          4m47s
documentdb-local-ha-ro                   ClusterIP      10.111.154.246   <none>        5432/TCP          4m47s
documentdb-local-ha-rw                   ClusterIP      10.101.235.95    <none>        5432/TCP          4m47s
documentdb-service-documentdb-local-ha   LoadBalancer   10.97.24.62      127.0.0.1     10260:31829/TCP   4m57s

Ok now we are ready to test failover.

Test Failover

The test uses a Python client application that continuously performs write and read operations against the DocumentDB cluster. This includes retry logic with exponential backoff and tracks metrics like operation counts, failures, and downtime.

Note that the client uses retryWrites=True, which allows the MongoDB driver to automatically retry failed writes on the new primary — in very fast failovers, you may see zero reported failures as the driver absorbs the disruption transparently.

Start the client application:

pip install -r requirements.txt
python failover_test_read_write.py

Let it run for ~15 seconds to establish a baseline. You'll see continuous write and read operations succeeding.

//....
[CLIENT][10:29:28.051] ✓ Connected to DocumentDB
[CLIENT][10:29:28.138] ✓ W#1 (44ms) | R#1 (43ms) | Avg W:44ms R:43ms | Docs: 1
[CLIENT][10:29:28.688] ✓ W#2 (2ms) | R#2 (43ms) | Avg W:23ms R:43ms | Docs: 2
[CLIENT][10:29:29.234] ✓ W#3 (2ms) | R#3 (43ms) | Avg W:16ms R:43ms | Docs: 3
[CLIENT][10:29:29.783] ✓ W#4 (3ms) | R#4 (43ms) | Avg W:13ms R:43ms | Docs: 4
[CLIENT][10:29:30.327] ✓ W#5 (2ms) | R#5 (42ms) | Avg W:11ms R:43ms | Docs: 5
//.....

Trigger Failover

In a new terminal, identify the current primary (the primary/replica roles may vary in your deployment):

kubectl get pods -n documentdb-preview-ns -L cnpg.io/instanceRole

# output:
NAME                    READY   STATUS    RESTARTS   AGE   INSTANCEROLE
documentdb-local-ha-1   2/2     Running   0          14m   primary
documentdb-local-ha-2   2/2     Running   0          14m   replica
documentdb-local-ha-3   2/2     Running   0          14m   replica

Note which pod shows primary role, then delete it to simulate a failure:

kubectl delete pod <primary-pod-name> -n documentdb-preview-ns

So, in case your primary pod is documentdb-local-ha-1, you would run: kubectl delete pod documentdb-local-ha-1 -n documentdb-preview-ns

Automatic Recovery

Watch the client terminal. You should see logs similar to this:

[CLIENT][10:32:32.452] ✗ FAILOVER EVENT DETECTED
[CLIENT][10:32:32.452] ℹ   Error: the database system is shutting down, full error: {'ok': 0.0, 'code': 50463173, 'codeName': 'Error', 'errmsg': 'the database system is shutting down'}
[CLIENT][10:32:32.452] ℹ   Last successful write: #178
[CLIENT][10:32:32.452] ℹ ================================================================================
[CLIENT][10:32:32.500] ✗ ⚠ Write FAILED | ⚠ Read FAILED | Downtime: 0.0s | Failed W: 1 R: 1
[CLIENT][10:32:32.551] ↻ Attempting reconnection (backoff: 1.0s)...
[CLIENT][10:32:32.703] ✗ Connection failed: error connecting to server: Connection refused (os error 111), full error: {'ok': 0.0, 'code': 1, 'codeName': 'Internal Error', 'errmsg': 'error connecting to server: Connection refused (os error 111)'}
[CLIENT][10:32:33.705] ↻ Attempting reconnection (backoff: 2.0s)...
[CLIENT][10:32:33.947] ✓ Connected to DocumentDB
[CLIENT][10:32:33.947] ✓ Reconnection successful!
[CLIENT][10:32:33.998] ℹ ================================================================================
[CLIENT][10:32:33.998] ↻ RECOVERY COMPLETE
//.....

Then the read and write operations should resume successfully:

[CLIENT][10:32:34.044] ✓ W#179 (51ms) | R#179 (46ms) | Avg W:8ms R:39ms | Docs: 284
[CLIENT][10:32:34.593] ✓ W#180 (4ms) | R#180 (42ms) | Avg W:8ms R:39ms | Docs: 285
[CLIENT][10:32:35.143] ✓ W#181 (5ms) | R#181 (44ms) | Avg W:9ms R:39ms | Docs: 286
[CLIENT][10:32:35.693] ✓ W#182 (3ms) | R#182 (43ms) | Avg W:9ms R:39ms | Docs: 287
[CLIENT][10:32:36.238] ✓ W#183 (2ms) | R#183 (42ms) | Avg W:8ms R:39ms | Docs: 288
[CLIENT][10:32:36.787] ✓ W#184 (3ms) | R#184 (43ms) | Avg W:9ms R:39ms | Docs: 289
[CLIENT][10:32:37.333] ✓ W#185 (3ms) | R#185 (42ms) | Avg W:8ms R:39ms | Docs: 290
//....

Let's take a closer look at what happened.

Behind the scenes

These are the key events during failover:

Failure detection: Operations start failing with connection errors
FAILOVER EVENT DETECTED: The client recognizes the disruption
Reconnection attempts: Automatic retry with exponential backoff
RECOVERY COMPLETE: Service automatically resumes

Behind the scenes, CNPG automatically detects the primary pod termination, promotes a healthy replica to primary, and updates the cnpg.io/instanceRole: primary label on the new primary pod. The Kubernetes service automatically routes traffic to the new primary (the external IP remains unchanged).

The key to failover is the service's label selector mechanism. Since the service tracks pods with cnpg.io/instanceRole: primary, when CNPG updates this label during promotion, the service endpoint automatically switches to the new primary without any DNS changes or client reconfiguration.

Verify the new primary – you should see a different pod as the new primary (it may vary in your deployment). In this example, documentdb-local-ha-3 has become the new primary:

kubectl get pods -n documentdb-preview-ns -L cnpg.io/instanceRole

# output:
NAME                    READY   STATUS    RESTARTS   AGE     INSTANCEROLE
documentdb-local-ha-1   2/2     Running   0          2m17s   replica
documentdb-local-ha-2   2/2     Running   0          18m     replica
documentdb-local-ha-3   2/2     Running   0          18m     primary

Verify manually

You can also connect directly using mongosh to verify. First, get the connection string:

kubectl get documentdb documentdb-local-ha -n documentdb-preview-ns

# output:

NAME                  STATUS                     CONNECTION STRING
documentdb-local-ha   Cluster in healthy state   mongodb://$(kubectl get secret documentdb-credentials -n documentdb-preview-ns -o jsonpath='{.data.username}' | base64 -d):$(kubectl get secret documentdb-credentials -n documentdb-preview-ns -o jsonpath='{.data.password}' | base64 -d)@127.0.0.1:10260/?directConnection=true&authMechanism=SCRAM-SHA-256&tls=true&tlsAllowInvalidCertificates=true&replicaSet=rs0

Use the connection string to connect with mongosh:

mongosh "mongodb://$(kubectl get secret documentdb-credentials -n documentdb-preview-ns -o jsonpath='{.data.username}' | base64 -d):$(kubectl get secret documentdb-credentials -n documentdb-preview-ns -o jsonpath='{.data.password}' | base64 -d)@127.0.0.1:10260/?directConnection=true&authMechanism=SCRAM-SHA-256&tls=true&tlsAllowInvalidCertificates=true&replicaSet=rs0"

Once connected, you can connect to the testdb database and verify the documents:

rs0 [direct: mongos] test> use testdb
switched to db testdb
rs0 [direct: mongos] testdb> db.getCollectionNames()
[ 'failover_test' ]
rs0 [direct: mongos] testdb> db.failover_test.countDocuments()
408
rs0 [direct: mongos] testdb>

Bonus exercise

Try connecting to each cluster node directly. You can kubectl port-forward to each pod. For example, to connect to documentdb-local-ha-1 over port 27017:

kubectl port-forward -n documentdb-preview-ns documentdb-local-ha-1 27017:10260

Now you can connect with mongosh:

mongosh "mongodb://k8s_secret_user:K8sSecret100@localhost:27017/?directConnection=true&authMechanism=SCRAM-SHA-256&tls=true&tlsAllowInvalidCertificates=true"

Experiment with different commands and observe the behavior.

You can also explore advanced scenarios like multi-region or multi-cloud deployments

Cleanup

To tear down the environment when you're done:

kubectl delete namespace documentdb-preview-ns
helm uninstall documentdb-operator -n documentdb-operator
kubectl delete namespace documentdb-operator
minikube stop

Wrapping Up

The DocumentDB Kubernetes Operator provides local high availability with automatic failover capabilities. You have seen how the operator handles primary failures with minimal manual intervention, making it easier to build resilient database deployments on Kubernetes.

This tutorial demonstrates basic failover recovery using a small dataset in a single-node cluster. In this case, the client-observed recovery time was approximately 1-3 seconds. Since CNPG uses asynchronous replication by default, note that transactions committed on the old primary but not yet replicated to standbys could be lost during an unplanned failover. Make sure to consider factors specific to your deployments for production or with larger datasets.

Go ahead, try it out in your own environment, and let us know your feedback!

Check out the documentation for the latest feature updates. If you run into issues or have questions, reach out on Discord or raise an issue on GitHub. Contributions are welcome, whether it's code, documentation improvements, or simply sharing your experience.

Happy building!

Build a Time Tracking App with GitHub Copilot SDK

Abhishek Gupta — Mon, 02 Mar 2026 06:09:41 +0000

The GitHub Copilot SDK lets you embed Copilot's agentic workflows directly into your apps, and it's available for Python, TypeScript, Go, and .NET.

TimeTrack is a desktop app built with the GitHub Copilot SDK (TypeScript) and Azure Cosmos DB. You can:

⏱️ Track time with a start/stop timer, projects, and tags
🗣️ Ask questions about your time data in plain English — Copilot generates and runs Cosmos DB SQL queries behind the scenes
📊 View reports and charts across multiple users

Here is a demo of the app in action:

If you want to try it yourself, the code is on GitHub. Works with Azure Cosmos DB or the vNext emulator — clone, configure, and npm start.

For local development, you don't need an Azure account. The Cosmos DB vNext emulator runs as a Docker container, so you can seed sample data and start querying right away.

Behind the Scenes

What makes this interesting is the SDK's tool calling. You define a tool using defineTool with a schema (powered by Zod), and Copilot decides when to call it. Here's what the core of it looks like:

const queryTool = defineTool("query_time_data", {
  description: "Execute a read-only Cosmos DB SQL query against time entries",
  parameters: z.object({
    query: z.string().describe("Cosmos DB SQL query"),
  }),
  handler: async ({ query }) => {
    // query is scoped to the user's partition key
    const result = await runQuery(userId, query);
    return JSON.stringify(result);
  },
});

session = await client.createSession({
  tools: [queryTool],
  systemMessage: { mode: "replace", content: "..." },
});

When a user asks "what was my most productive day this week?", the model generates a SQL query, executes it against Cosmos DB (scoped to the user's partition key), and returns a conversational answer. If the generated SQL hits a Cosmos DB error — say, an unsupported ORDER BY on an aggregate alias — the error is returned to the model as a tool result. The model reads it, adjusts the query, and retries. This usually succeeds within 1–2 attempts, with no user intervention.

Here's the overall flow:

+--------------+     +----------------+     +-------------+
|  Electron UI | --> |  Copilot SDK   | --> | Copilot CLI |
|  (renderer)  |     |  (main process)|     |  (sidecar)  |
+--------------+     +----------------+     +------+------+
       ^                                           |
       |                                    tool call: query_time_data
       |                                           |
       |                                    +------v------+
       |                                    |  Cosmos DB  |
       |                                    +------+------+
       |                                           |
       |                                     result or error
       |                                           |
       |                                    +------v------+
       |                                    |    Model    |
       |                                    | (interpret) |
       |                                    +------+------+
       |                                      |         |
       |                                success?     SQL error?
       |                                   |          retry with
       |                                   |        corrected SQL
       |                                   |             |
       +---  AI response  <---------------+     (back to Cosmos DB)

Because the AI writes arbitrary SQL rather than picking from canned reports, the range of questions is wide. A few examples:

Do I tend to work longer hours early in the week or late in the week?
How does my Monday workload compare to Friday?
Compare my total hours this week vs last week
Rank my projects by total hours and show the percentage each represents
Summarize my last two weeks in 3 bullet points

The app uses GPT-4.1 by default, but you can switch to any supported Copilot model — gpt-5, claude-sonnet-4.5, etc. — by setting COPILOT_MODEL in .env.

If you want to go beyond Copilot's model lineup entirely, the app supports BYOK (Bring Your Own Key). Point it at your own Azure AI Foundry deployment — set your endpoint, API key, and deployment name in .env and the SDK routes all AI calls to your model. The tool calling, session management, and agent runtime stay identical. You control the model, the billing, and the identity layer; the SDK provides the agentic infrastructure.

The app also has experimental support for local OpenAI-compatible servers (Ollama, Foundry Local), though results vary depending on the model's tool calling capabilities, and your environment setup (GPU, etc).

Try It Yourself

The full source code is on GitHub. You can run it with the Cosmos DB vNext emulator — no Azure account needed — seed sample data, and start asking questions in natural language. Swap in your own model via BYOK if you want full control over the AI layer.

The Copilot SDK is open source and available for TypeScript, Python, Go, and .NET. Check out the docs to see what else you can build with it.

Agentic Apps with GitHub Copilot SDK

Abhishek Gupta — Mon, 02 Feb 2026 14:45:46 +0000

The GitHub Copilot SDK lets you embed Copilot's AI capabilities directly into your apps — available for Go, Python, TypeScript, and .NET.

Here's a quick demo of building an agentic application with the SDK and Azure Cosmos DB.

Flight Diary is a sample app where you can:

📸 Upload a boarding pass image → Copilot extracts flight details automatically (no separate OCR/vision API needed)
🗣️ Query your flight history in plain English → Copilot generates and runs Cosmos DB SQL queries behind the scenes

The part I find interesting is how the SDK handles tool calling. You define the tools, Copilot figures out when and how to use them. For example, when extracting from a boarding pass, it parses the image and calls the save function — all from a single prompt.

If you want to try it yourself, the code is on GitHub. It also works with the Cosmos DB vNext emulator for local development.

GitHub Copilot CLI + MCP: Talk to Your Database in Plain English

Abhishek Gupta — Sat, 24 Jan 2026 11:56:09 +0000

Here is a quick demo of how to interact with Azure Cosmos DB from GitHub Copilot CLI using MCP. This MCP server lets you interact with Azure Cosmos DB using plain English instead of writing queries or clicking through the portal. List databases, create containers, run SQL queries, add items — all through natural language. It works with both the Cosmos DB service and the vNext emulator (for local development).

The part I really enjoy is watching Copilot CLI figure out which tools to call to get the job done. For example, when I asked for "pending tasks," it generated the query and ran it without me having to think about the syntax.

If you want to try it yourself, the code is on GitHub. It's fairly straightforward to build, and set up with /mcp add. For something production-ready with remote (HTTP) deployment and Entra ID authentication, check out the Azure Cosmos DB MCP Toolkit.

If you haven't tried GitHub Copilot CLI with MCP servers yet, this is an easy way to get started.

Cheers!

Azure Cosmos DB Playground: Learn and experiment with queries in your browser

Abhishek Gupta — Wed, 14 Jan 2026 07:04:05 +0000

Interactive Browser-Based Environment to Learn, Test, and Share Queries

The Azure Cosmos DB Playground is an interactive, browser-based playground for learning and experimenting with Azure Cosmos DB SQL queries without any setup, installation, or cloud costs. The playground runs on the Azure Cosmos DB vNext emulator and leverages the open-source codapi project behind the scenes.

The playground is a great tool for learning, prototyping, testing, and sharing Azure Cosmos DB queries. You can:

📦 Explore with pre-loaded datasets and ready-to-run query examples
📤 Paste or upload your own JSON data to experiment with custom scenarios
⚡ Instantly see query results and modify both data and queries on the fly
🔗 Generate shareable links that capture your current dataset and query for easy sharing
♻️ Restore your last session automatically after a refresh or reopening the page
🧩 Embed interactive, runnable examples directly into HTML files for documentation, blogs, or tutorials

Note: This is an experimental project and not an official Microsoft or Azure offering. It’s designed for learning and sharing, not for production use.

▶️ Quick Demo (click to play)

Try the Playground (or Deploy Your Own) 🚀

You can head over to https://aka.ms/cosmosdb-playground and start experimenting right away!

While the hosted playground is ready to use, you can also deploy your own instance on Azure. The playground uses a fully containerized architecture with Docker Compose. Follow the detailed deployment instructions available on GitHub to set up your own playground instance.

To configure HTTP(s) access for your deployed playground, refer to the instructions available on GitHub.

Playground Features 🛠️

These might evolve over time - You can check out the GitHub repository for up to date list of features.

Behind the Scenes 🏗️

Here is a simplified architecture of the Azure Cosmos DB Playground:

+-------------------+        +-------------------+        +-------------------+
|   User Browser    |  <---> |      nginx        |  <---> |     Codapi        |
| (playground.html) |        | (Reverse Proxy)   |        | (Sandbox Server)  |
+-------------------+        +-------------------+        +-------------------+
                                                           |
                                                           v
                                                +--------------------------+
                                                |  Ephemeral Query Container|
                                                |  (Python + Cosmos SDK)    |
                                                +--------------------------+
                                                           |
                                                           v
                                                +--------------------------+
                                                | Cosmos DB Emulator       |
                                                | (Docker Container)       |
                                                +--------------------------+

At its core, the playground uses the Azure Cosmos DB vNext Emulator as a custom Codapi sandbox.

Azure Cosmos DB vNext Emulator: This is a local version of Azure Cosmos DB (SQL API) available as a Docker container. It emulates the real Azure Cosmos DB service, so you can experiment with queries and data models without any cloud setup or cost.

Codapi: It is a lightweight sandbox server designed for interactive documentation, code examples, and learning environments. In the playground, Codapi manages the creation of isolated Docker containers for each query execution. This ensures that each user’s code and data are executed in an ephemeral environment. Codapi JavaScript widget (codapi-js) is used for the playground frontend integration, which invokes the Codapi API for code execution in the sandbox.

Query Execution Flow

nginx serves the frontend and routes API requests to Codapi, enabling interactive query execution from the browser.

For each run, Codapi spawns an ephemeral query Docker container where a Python component connects to the long-running Cosmos DB emulator. It creates a temporary Cosmos DB container, seeds the data, executes the query, and returns results. After execution, both the temporary Cosmos DB container and the ephemeral query Docker container are cleaned up.

Limitations ⚠️

The playground is a sandbox for learning and experimentation, not production use. It is designed for small(ish) datasets and may have performance constraints, among other limitations. Some of these limitations may change over time. For the most current list, refer to the GitHub repo.

Try It Out! ✨

Visit https://aka.ms/cosmosdb-playground to start experimenting with queries, and share your examples with others.

Have feedback or suggestions? Visit the GitHub repository and share your thoughts. Happy querying!

Build AI Tooling in Go with the MCP SDK – Connecting AI Apps to Databases

Abhishek Gupta — Wed, 07 Jan 2026 17:12:51 +0000

A hands‑on walkthrough of building MCP servers that can plug AI applications into Azure Cosmos DB

The Model Context Protocol (MCP) has established itself as the ubiquitous standard for connecting AI applications to external systems. Since its release, there have been implementations across various programming languages and frameworks, enabling developers to build solutions that expose data sources, tools, and workflows to AI applications.

For Go developers, however, the journey to an official MCP SDK took longer (compared to other SDKs like Python and TypeScript). Discussions and design/implementation work on the official Go implementation began during early to mid 2025. At the time of writing (January 2026) it stands at version 1.2.0. As a Gopher, I'm excited (and relieved!) to finally have a stable, official MCP Go SDK that the Go community can rely on.

To explore its capabilities, I built an MCP server for Azure Cosmos DB. This blog post will dive into the MCP Go SDK fundamentals by walking through its specifics, and exploring concepts such as tools, servers, etc. By the end, you'll understand how to use the MCP Go SDK to build your own MCP servers, with Azure Cosmos DB serving as a practical example.

Note: This project is not intended to replace the Azure MCP Server or Azure Cosmos DB MCP Toolkit. Rather, it serves as an experimental learning tool that demonstrates how to combine the Azure and MCP Go SDKs to build AI tooling for Azure Cosmos DB.

MCP Basics

Let's briefly cover what MCP is and how the MCP Go SDK works.

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems. It's often referred to as a USB-C port for AI applications — just as USB-C provides a standardized way to connect devices, MCP provides a standardized way to connect AI applications to data sources, tools, and workflows.

With MCP, AI applications (ranging from IDEs like VS Code, CLI coding tools like GitHub Copilot or apps like Claude web/desktop) can:

Access data sources (local files, databases, APIs)
Use tools (search engines, calculators, external services)
Execute workflows (specialized prompts, multi-step operations)

This standardization means developers can build MCP servers once and have them work with any MCP-compatible AI application, rather than creating custom integrations for each platform.

MCP Go SDK

The official Go MCP SDK provides the building blocks to create MCP servers and clients in Go. Here's a minimal example of an MCP server with a simple tool:

package main

import (
    "context"
    "log"
    "strings"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

type ReverseInput struct {
    Text string `json:"text" jsonschema:"the text to reverse"`
}

type ReverseOutput struct {
    Reversed string `json:"reversed" jsonschema:"the reversed text"`
}

func ReverseText(ctx context.Context, req *mcp.CallToolRequest, input ReverseInput) (
    *mcp.CallToolResult,
    ReverseOutput,
    error,
) {
    runes := []rune(input.Text)
    for i, j := 0, len(runes)-1; i < j; i, j = i+1, j-1 {
        runes[i], runes[j] = runes[j], runes[i]
    }
    return nil, ReverseOutput{Reversed: string(runes)}, nil
}

func main() {
    // Create server
    server := mcp.NewServer(&mcp.Implementation{
        Name:    "text-tools",
        Version: "v1.0.0",
    }, nil)

    // Add a tool
    mcp.AddTool(server, &mcp.Tool{
        Name:        "reverse",
        Description: "reverses the input text",
    }, ReverseText)

    // Run over stdio
    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}

This example demonstrates the key concepts:

Tool definition: A mcp.Tool with a name and description
Input/Output types: Structs with JSON schema tags that define the tool's interface
Handler function: The actual logic that executes when the tool is called
Server: Created with mcp.NewServer() and configured with tools
Transport: How the server communicates (here using stdio)

These concepts will be covered later on the blog.

MCP Server in Action

▶️ To get a sense of what the server can do, take a look at this short demo of using the MCP server with Agent Mode in Visual Studio Code:

This server exposes several tools that enable AI applications to interact with Azure Cosmos DB:

list_databases - List all databases in a Cosmos DB account
list_containers - List all containers in a specific database
read_item - Read a specific item using its ID and partition key
execute_query - Execute SQL queries against containers
create_container - Create new containers with partition keys
add_item_to_container - Add items to containers
read_container_metadata - Retrieve container configuration details

If you want to setup and configure the server, check out the GitHub repository.

Alright, let's dive into how it's built.

Understanding the Implementation

Tools are the building blocks of an MCP server. Each tool represents a specific operation that the server can perform.

Let's use the read_item tool as an example to understand the fundamental concepts of the MCP Go SDK and how it integrates with the Azure Cosmos DB Go SDK.

MCP Tools: Definition, Handler, and Execution Flow

An MCP tool consists of these components:

Tool Definition

The tool definition describes the tool to the AI application. Here's how we define the read_item tool:

func ReadItem() *mcp.Tool {
    return &mcp.Tool{
        Name:        "read_item",
        Description: "Read a specific item from a container in an Azure Cosmos DB database using the item ID and partition key",
    }
}

The Tool struct contains:

Name: A unique identifier for the tool
Description: Helps the AI understand when to use this tool

The SDK can automatically infer input and output schemas from your handler function's types, which we'll see next.

Input and Output Types

Type-safe input and output structures define the tool's interface:

type ReadItemToolInput struct {
    Account      string `json:"account" jsonschema:"Azure Cosmos DB account name"`
    Database     string `json:"database" jsonschema:"Name of the database"`
    Container    string `json:"container" jsonschema:"Name of the container to read data from"`
    ItemID       string `json:"itemID" jsonschema:"ID of the item to read"`
    PartitionKey string `json:"partitionKey" jsonschema:"Partition key value of the item"`
}

type ReadItemToolResult struct {
    Item string `json:"item" jsonschema:"The item data as JSON string"`
}

The SDK uses these types to automatically generate JSON schemas and handle validation. JSON tags define how fields are serialized, and jsonschema tags provide descriptions that help AI applications understand what each field represents

Tool Handler

The handler is where the actual work happens. The MCP Go SDK provides a generic AddTool function that can bind tools to functions with this signature:

func(ctx context.Context, request *CallToolRequest, input InputType) (result *CallToolResult, output OutputType, error)

Here's the read_item handler:

func ReadItemToolHandler(ctx context.Context, _ *mcp.CallToolRequest, input ReadItemToolInput) (*mcp.CallToolResult, ReadItemToolResult, error) {
    // 1. Validate inputs
    if input.Account == "" {
        return nil, ReadItemToolResult{}, errors.New("cosmos db account name missing")
    }
    if input.Database == "" {
        return nil, ReadItemToolResult{}, errors.New("database name missing")
    }
    // ... more validation

    // 2. Get Cosmos DB client
    client, err := GetCosmosClientFunc(input.Account)
    if err != nil {
        return nil, ReadItemToolResult{}, err
    }

    // 3. Navigate to the container
    databaseClient, err := client.NewDatabase(input.Database)
    if err != nil {
        return nil, ReadItemToolResult{}, fmt.Errorf("error creating database client: %v", err)
    }

    containerClient, err := databaseClient.NewContainer(input.Container)
    if err != nil {
        return nil, ReadItemToolResult{}, fmt.Errorf("error creating container client: %v", err)
    }

    // 4. Read the item using Cosmos DB SDK
    partitionKey := azcosmos.NewPartitionKeyString(input.PartitionKey)
    itemResponse, err := containerClient.ReadItem(ctx, partitionKey, input.ItemID, nil)
    if err != nil {
        return nil, ReadItemToolResult{}, fmt.Errorf("error reading item: %v", err)
    }

    // 5. Return the result
    return nil, ReadItemToolResult{Item: string(itemResponse.Value)}, nil
}

The handler handles (pun intended!) several things:

Validates input parameters
Interacts with Azure Cosmos DB
Returns structured output

Notice we return nil for the *mcp.CallToolResult. The SDK automatically handles the response marshaling for us. If we return an error, the SDK sets IsError: true in the result automatically.

Authenticating with Azure Cosmos DB

The MCP server uses NewDefaultAzureCredential from the Azure Identity SDK, which automatically handles multiple authentication methods, such as Azure CLI credentials (for local development), Managed Identity (for production), environment variables, and more:

func GetCosmosDBClient(accountName string) (*azcosmos.Client, error) {
    endpoint := fmt.Sprintf("https://%s.documents.azure.com:443/", accountName)

    cred, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        return nil, fmt.Errorf("error creating credential: %v", err)
    }

    client, err := azcosmos.NewClient(endpoint, cred, nil)
    if err != nil {
        return nil, fmt.Errorf("error creating Cosmos client: %v", err)
    }

    return client, nil
}

Once we have the client, we use the standard Azure Cosmos DB SDK patterns:

client.NewDatabase() to get a database client
databaseClient.NewContainer() to get a container client
containerClient.ReadItem() to perform the actual read operation

MCP Server: Bringing Tools Together

The beauty here is that MCP provides the standardized interface for AI interactions, while the Azure Cosmos DB SDK handles all the database operations – the handler acts as the bridge between these two worlds.

Now that we understand individual tools, let's see how they're organized within an MCP server. An MCP server exposes specific capabilities (tools, resources, prompts) to AI applications through the standardized MCP protocol.

Creating the Server

Here's how we create and configure the MCP server in main.go:

func main() {
    // Create the server with metadata
    server := mcp.NewServer(&mcp.Implementation{
        Name:       "mcp_azure_cosmosdb_go",
        Title:      "Go based MCP server for Azure Cosmos DB using the Azure SDK for Go and the MCP Go SDK",
        Version:    "0.0.1",
        WebsiteURL: "https://github.com/abhirockzz/mcp_cosmosdb_go",
    }, nil)

    // Register all tools with their handlers
    mcp.AddTool(server, tools.ListDatabases(), tools.ListDatabasesToolHandler)
    mcp.AddTool(server, tools.ListContainers(), tools.ListContainersToolHandler)
    mcp.AddTool(server, tools.ReadContainerMetadata(), tools.ReadContainerMetadataToolHandler)
    mcp.AddTool(server, tools.CreateContainer(), tools.CreateContainerToolHandler)
    mcp.AddTool(server, tools.AddItemToContainer(), tools.AddItemToContainerToolHandler)
    mcp.AddTool(server, tools.ReadItem(), tools.ReadItemToolHandler)
    mcp.AddTool(server, tools.ExecuteQuery(), tools.ExecuteQueryToolHandler)

    // ... transport setup (covered next)
}

Breaking this down:

mcp.NewServer() creates a new server instance with:
- Implementation metadata: Name, title, and version that identify the server
- ServerOptions: Additional configuration (we use nil for defaults)
mcp.AddTool() registers each tool with the server:
- Takes the server instance
- The tool definition (from functions like tools.ReadItem())
- The handler function (like tools.ReadItemToolHandler)

When the server connects to a client, it automatically advertises the tools capability, making all registered tools discoverable by the AI application.

Transport: Connecting Server to Client

A transport defines how the server communicates with clients. It's the communication channel that carries JSON-RPC messages between the server and client. The MCP Go SDK supports multiple transport types.

HTTP Streamable Transport

The server also supports http transport, which is ideal for web-based AI applications. Here's how we set it up:

// Create the streamable HTTP handler
handler := mcp.NewStreamableHTTPHandler(func(req *http.Request) *mcp.Server {
    return server
}, nil)

// Start the HTTP server
if err := http.ListenAndServe(":9090", handler); err != nil {
    log.Fatalf("Server failed: %v", err)
}

The NewStreamableHTTPHandler creates an HTTP handler that accepts incoming HTTP requests from MCP clients, and returns the appropriate server instance for each request. It handles the streamable transport protocol automatically, and supports multiple concurrent client sessions

This transport is ideal when you want to support web-based AI applications and the server needs to be accessible over HTTP/HTTPS. This allows multiple clients to connect simultaneously.

Stdio Transport

Another common MCP transport is stdio, used when the server runs as a subprocess:

err := server.Run(context.Background(), &mcp.StdioTransport{})
if err != nil {
    log.Fatal(err)
}

The stdio transport runs as a subprocess started by the client and communicates via standard input/output streams. It's perfect for local MCP clients like GitHub Copilot CLI, Claude Code (or Desktop), etc. Both transports implement the same MCP protocol, so the server's tools work identically regardless of which transport you choose. The difference is purely in how the server connects to and communicates with clients.

With the server created, tools registered, and transport configured, the MCP server is ready to accept connections from AI applications and execute operations against Azure Cosmos DB.

Testing the MCP Server

This involves verifying functionality at different layers of the stack. This server uses integration tests at two levels: tests that verify the MCP protocol aspects, and tests that focus on handler logic with database interactions. Let's explore both approaches.

Before diving into testing, let's briefly understand what an MCP client is.

Understanding MCP Clients

An MCP client is the component that connects to an MCP server to consume its capabilities. In the context of the MCP server:

In production: The client is typically an AI application (like Claude Desktop or VS Code) that discovers and calls our tools
In testing: We create programmatic clients to verify our server works correctly

The MCP Go SDK provides a Client type that we can use to connect to our server and call its tools, simulating how a real AI application would interact with it.

Handler-Level Integration Testing with Azure Cosmos DB vNext Emulator

Let's start by looking at tests that focus on handler logic and database interactions. It uses the Azure Cosmos DB vNext Emulator with testcontainers-go.

From tools_test.go:

func TestListDatabases(t *testing.T) {
    tests := []struct {
        name           string
        input          ListDatabasesToolInput
        expectError    bool
        expectedResult string
        expectedErrMsg string
    }{
        {
            name: "valid account name",
            input: ListDatabasesToolInput{
                Account: "dummy_account_does_not_matter",
            },
            expectError:    false,
            expectedResult: testOperationDBName,
        },
        {
            name: "empty account name",
            input: ListDatabasesToolInput{
                Account: "",
            },
            expectError:    true,
            expectedErrMsg: "cosmos db account name missing",
        },
    }

    for _, test := range tests {
        t.Run(test.name, func(t *testing.T) {
            _, response, err := ListDatabasesToolHandler(
                context.Background(), 
                nil, 
                test.input,
            )

            if test.expectError {
                require.Error(t, err)
                assert.Contains(t, err.Error(), test.expectedErrMsg)
                return
            }

            require.NoError(t, err)
            assert.Contains(t, response.Databases, test.expectedResult)
        })
    }
}

These tests call handlers directly (bypassing the MCP protocol layer) and use table-driven tests for input validation and error handling, business logic correctness, database operations and edge cases.

func setupCosmosEmulator(ctx context.Context) (testcontainers.Container, error) {
    req := testcontainers.ContainerRequest{
        Image:        "mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview",
        ExposedPorts: []string{"8081:8081", "8080:8080"},
        WaitingFor:   wait.ForListeningPort(nat.Port("8080")),
        Env: map[string]string{
            "PROTOCOL": "http",
        },
    }

    container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
        ContainerRequest: req,
        Started:          true,
    })
    // ... error handling

    return container, nil
}

The testcontainers-go library automatically pulls the emulator image, starts the container, and cleans up after tests complete. This is set up once in TestMain function and shared across all tests.

MCP Protocol Integration Testing

Beyond handler testing, we also verify the complete MCP protocol stack—from client request through server processing to response. Here's an example from mcp_integration_test.go:

func TestMCPIntegration_ReadItem(t *testing.T) {
    ctx := context.Background()

    // 1. Create MCP server and register the read_item tool
    server := mcp.NewServer(&mcp.Implementation{
        Name:    "test-cosmosdb-server",
        Version: "0.0.1",
    }, nil)

    mcp.AddTool(server, ReadItem(), ReadItemToolHandler)

    // 2. Create in-memory transports for testing
    serverTransport, clientTransport := mcp.NewInMemoryTransports()

    // 3. Connect server
    serverSession, err := server.Connect(ctx, serverTransport, nil)
    require.NoError(t, err)
    defer serverSession.Close()

    // 4. Create and connect client
    client := mcp.NewClient(&mcp.Implementation{
        Name:    "test-client",
        Version: "0.0.1",
    }, nil)

    clientSession, err := client.Connect(ctx, clientTransport, nil)
    require.NoError(t, err)
    defer clientSession.Close()

    // 5. Call the tool via MCP protocol
    result, err := clientSession.CallTool(ctx, &mcp.CallToolParams{
        Name: "read_item",
        Arguments: map[string]any{
            "account":      "dummy_account_does_not_matter",
            "database":     testOperationDBName,
            "container":    testOperationContainerName,
            "itemID":       id,
            "partitionKey": partitionKeyValue,
        },
    })

    // 6. Verify the response
    require.NoError(t, err)
    require.False(t, result.IsError)
    require.NotEmpty(t, result.Content)

    // 7. Parse and validate the JSON response
    textContent, ok := result.Content[0].(*mcp.TextContent)
    require.True(t, ok)

    var response ReadItemToolResult
    err = json.Unmarshal([]byte(textContent.Text), &response)
    require.NoError(t, err)

    assert.NotEmpty(t, response.Item)
}

This test demonstrates several key concepts:

In-Memory Transports: mcp.NewInMemoryTransports() creates a pair of connected transports without requiring actual network communication—perfect for testing
Client-Server Connection: Both server and client connect to their respective transports, establishing a session
Tool Invocation: clientSession.CallTool() sends a properly formatted MCP request
Response Handling: The result is parsed from the MCP protocol format back to our domain types
Full Protocol Verification: This tests the complete round trip: request serialization → tool execution → response serialization → client parsing

Both handler-level and protocol-level tests use the Azure Cosmos DB vNext emulator, not mocks. Handler-level tests provide feedback on business logic, while protocol-level tests ensure MCP compliance and end-to-end functionality.

Wrap Up

With the MCP Go SDK, building MCP servers has become significantly more accessible for Go developers. You don't have to go for Python anymore (sorry Pythonistas, pun intended!).

This MCP server demonstrates how to combine the MCP Go SDK with domain-specific tools — in this case, the Azure Cosmos DB Go SDK. While this server provides useful functionality for interacting with Cosmos DB from AI applications, its primary purpose is educational. As mentioned before, this is a learning tool that shows how to integrate MCP with real-world services, not a replacement for solutions like the Azure MCP Server or the Azure Cosmos DB MCP Toolkit.

The specific patterns we covered (defining tools, implementing handlers, managing authentication, choosing transports, and writing integration tests) apply to any MCP server you might build. The same concepts apply, whether you're exposing APIs, databases, file systems, or custom business logic.

Next Steps

Ready to build your own MCP server? Here are some resources to get you started:

MCP Go SDK resources: Documentation, design, and examples.
MCP Specification: https://modelcontextprotocol.io/
Azure Cosmos DB Go SDK: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
Azure Cosmos DB vNext Emulator and Testcontainers Guide: Integration Testing for Go Applications

The MCP ecosystem is growing rapidly, and I am excited for Go developers who now have first-class support for participating in this evolution!

Azure Cosmos DB vNext Emulator: Query and Observability Enhancements

Abhishek Gupta — Sat, 13 Dec 2025 15:28:48 +0000

The Azure Cosmos DB Linux-based vNext emulator (preview) is a local version of the Azure Cosmos DB service that runs as a Docker container on Linux, macOS, and Windows. It provides a cost-effective way to develop and test applications locally without requiring an Azure subscription or network connectivity.

The latest release brings improvements in two key areas:

Enhanced Query engine: Addresses limitations in JOINs, operators, subdocument handling, and more.
Observability: OpenTelemetry support to collect and correlate metrics, logs, and traces for deeper insight into applications.

Query Improvements

This emulator release enables several query patterns that were previously unsupported. In this post, we'll focus on the following enhancements to query capabilities:

Improved JOIN Operations – Support for nested JOINs across multiple array levels, cross-product JOINs, and self-JOINs on primitive arrays
Enhanced Operator Support – Support for string manipulation functions (CONCAT, LENGTH) and array operations (ARRAY_LENGTH, direct array indexing)
Better Subdocument Handling – Improved querying of deeply nested object properties and proper handling of missing properties

Let's explore these with practical examples.

Improved JOINs

In Azure Cosmos DB, JOINs enable you to flatten and traverse data within documents, allowing you to work with nested and hierarchical data structures.

Let's explore this using a sample family dataset where each document represents a family with nested arrays. This includes three families (Andersen, Wakefield, and Miller) with varying numbers of children and pets, demonstrating how JOINs handle different data structures. Notice the hierarchical nesting: each family has a children array, each child has a pets array, and families also have a separate tags array.

[
    {
        "id": "AndersenFamily",
        "lastName": "Andersen",
        "parents": [
            {"firstName": "Thomas", "relationship": "father"},
            {"firstName": "Mary Kay", "relationship": "mother"}
        ],
        "children": [
            {
                "firstName": "Henriette",
                "grade": 5,
                "pets": [{"name": "Fluffy", "type": "Rabbit"}]
            }
        ],
        "tags": ["seattle", "active", "family-friendly"],
        "address": {"state": "WA", "city": "Seattle"}
    },
    {
        "id": "WakefieldFamily",
        "lastName": "Wakefield",
        "parents": [
            {"firstName": "Robin", "relationship": "mother"},
            {"firstName": "Ben", "relationship": "father"}
        ],
        "children": [
            {
                "firstName": "Jesse",
                "grade": 8,
                "pets": [
                    {"name": "Goofy", "type": "Dog"},
                    {"name": "Shadow", "type": "Horse"}
                ]
            },
            {"firstName": "Lisa", "grade": 1, "pets": []}
        ],
        "tags": ["newyork", "urban"],
        "address": {"state": "NY", "city": "New York"}
    },
    {
        "id": "MillerFamily",
        "lastName": "Miller",
        "parents": [{"firstName": "David", "relationship": "father"}],
        "children": [
            {
                "firstName": "Emma",
                "grade": 6,
                "pets": [{"name": "Whiskers", "type": "Cat"}]
            }
        ],
        "tags": ["boston", "academic"],
        "address": {"state": "MA", "city": "Boston"}
    }
]

Basic JOIN – Flattening Arrays

For example, if you need to generate a list of all children across multiple families for a school roster or activity planning, use the JOIN operator to flatten the children array, creating one result row per child across all family documents.

SELECT f.id, f.lastName, c.firstName, c.grade 
FROM f 
JOIN c IN f.children

This returns one row per child (giving you a flattened view of all children with their family information) – Henriette from the Andersen family, Jesse and Lisa from the Wakefield family, and Emma from the Miller family.

JOIN with Filter

To find children within specific grade ranges, add a WHERE clause to JOIN. This lets you filter results based on properties of the array elements, like selecting only middle school students (grade 6 and above).

SELECT f.id, f.lastName, c.firstName, c.grade 
FROM f 
JOIN c IN f.children 
WHERE c.grade >= 6

The result set includes only Jesse (grade 8) and Emma (grade 6), automatically excluding Henriette and Lisa who are in lower grades.

Nested JOIN – Traversing Hierarchical Data

If you need to traverse multiple levels of your data structure to identify all pets and their owners, use chained JOINs to drill down through nested arrays, moving from families to children to pets in a single query.

SELECT f.id, c.firstName AS child, p.name AS pet, p.type 
FROM f 
JOIN c IN f.children 
JOIN p IN c.pets

You'll see each pet listed with its owner and family: Henriette's rabbit Fluffy, Jesse's dog Goofy and horse Shadow, and Emma's cat Whiskers. Notice that Lisa doesn't appear in the results since her pets array is empty, demonstrating the INNER JOIN behavior.

Cross Product JOIN – Combining Independent Arrays

To associate every child with all of their family's characteristics or tags to understand patterns and preferences, join two arrays from the same document to create a cross product pairing each child with each family tag.

SELECT f.id, c.firstName AS child, t AS tag 
FROM f 
JOIN c IN f.children 
JOIN t IN f.tags

This creates every possible child-tag pairing within each family: Henriette appears three times (paired with "seattle", "active", and "family-friendly"), Jesse and Lisa each appear twice (with "newyork" and "urban"), and Emma appears twice (with "boston" and "academic").

JOIN on Primitive Arrays

Analyzing common characteristics across your entire dataset requires flattening simple value arrays. JOINs work on arrays of primitive values like strings or numbers, in addition to complex objects.

SELECT f.id, f.lastName, t AS tag 
FROM f 
JOIN t IN f.tags

Each tag becomes its own row associated with its family: the Andersen family contributes three tags ("seattle", "active", "family-friendly"), while Wakefield and Miller each contribute two tags.

Self-JOIN – Finding Combinations

Analyzing which characteristics tend to appear together in your data (such as discovering that families tagged "urban" are also often tagged "active") requires finding unique pairs within the same array. You achieve this by joining an array with itself using different aliases.

SELECT f.id, t1 AS tag1, t2 AS tag2 
FROM f 
JOIN t1 IN f.tags 
JOIN t2 IN f.tags 
WHERE t1 < t2

The Andersen family yields three unique pairs from their three tags ("active"+"seattle", "active"+"family-friendly", "family-friendly"+"seattle"), while Wakefield and Miller each produce one pair from their two tags – perfect for discovering which characteristics commonly appear together.

Complex Filters – Multi-Level Conditions

Real-world queries often require filtering on multiple criteria at different nesting levels, like finding all rabbits owned by families in Washington state for a local pet adoption program. You can combine conditions on both root document properties (location) and deeply nested array elements (pet type) in a single query.

SELECT f.id, f.address.state, c.firstName, p.name AS pet 
FROM f 
JOIN c IN f.children 
JOIN p IN c.pets 
WHERE f.address.state = 'WA' AND p.type = 'Rabbit'

The query pinpoints exactly what you're looking for: Henriette's rabbit Fluffy in the Andersen family from Washington state, filtering out all other pets and families in one efficient operation.

Code sample

A Python example demonstrating these JOIN scenarios is available in this GitHub Gist: cosmosdb_join_examples.py

To run the example, start the Azure Cosmos DB Emulator:

docker run -p 8081:8081 -p 8080:8080 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol http

Download and run the script from the gist – it automatically sets up the database, loads the sample data, and runs each query scenario:

python cosmosdb_join_examples.py

Enhanced Operator Support

The emulator now supports operators related to string manipulation, array operations and more. Let's explore these capabilities using an employee dataset where each document contains personal information, skill tags, and performance scores.

[
    {
        "id": "1",
        "firstName": "Alice",
        "email": "alice@company.com",
        "tags": ["senior", "manager", "remote"],
        "scores": [85, 92, 78, 95]
    },
    {
        "id": "2",
        "firstName": "Bob",
        "email": "bob@company.com",
        "tags": ["junior", "developer"],
        "scores": [72, 88, 65, 91]
    },
    {
        "id": "3",
        "firstName": "Charlie",
        "email": "charlie@company.com",
        "tags": ["senior", "architect", "onsite"],
        "scores": [95, 87, 92, 89]
    }
]

String Operations

Build formatted contact lists by combining multiple fields:

SELECT CONCAT(e.firstName, ' - ', e.email) as contact FROM e

This produces formatted strings like "Alice – alice@company.com", useful for generating reports or user-facing displays.

Filter records based on text length for data validation:

SELECT e.firstName FROM e WHERE LENGTH(e.firstName) > 5

This returns only "Charlie" since it's the only name exceeding 5 characters.

Array Operations

Count elements in nested arrays to identify employees with multiple skills:

SELECT e.firstName, ARRAY_LENGTH(e.tags) as skillCount FROM e

This returns the number of tags each employee has – Alice and Charlie each have 3 skills, while Bob has 2.

Query specific array positions to filter by criteria like first performance score:

SELECT e.firstName FROM e WHERE e.scores[0] > 85

This returns "Charlie" whose first score (95) exceeds the threshold, enabling queries on specific elements without flattening the entire array.

Code sample

A Python example demonstrating these operator scenarios above is available in this GitHub Gist: cosmosdb_operator_examples.py

To run the example, start the Azure Cosmos DB Emulator:

docker run -p 8081:8081 -p 8080:8080 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol http

Download and run the script from the gist – it automatically sets up the database, loads the sample data, and runs each query scenario:

python cosmosdb_operator_examples.py

Improved Subdocument Queries

The emulator now provides better support for querying nested object properties and subdocuments. Let's explore these capabilities using a user profile dataset where each document contains nested profile information, contact details, and settings.

[
    {
        "id": "1",
        "username": "user1",
        "profile": {
            "fullName": "John Doe",
            "age": 30,
            "contact": {
                "email": "john@example.com",
                "phone": "555-0101"
            }
        },
        "settings": {
            "theme": "dark",
            "notifications": true
        }
    },
    {
        "id": "2",
        "username": "user2",
        "profile": {
            "fullName": "Jane Smith",
            "age": 25
        },
        "settings": {
            "theme": "light",
            "notifications": false
        }
    }
]

Selecting Nested Properties with IS_DEFINED

This query selects nested properties while ensuring the parent object exists. It returns all usernames with their full names, correctly handling documents with defined profile objects:

SELECT c.username, c.profile.fullName 
FROM c 
WHERE IS_DEFINED(c.profile)

Checking Nested Properties

To identify users with complete contact information before processing, use this query that returns only users who have the profile.contact defined:

SELECT c.id, c.username 
FROM c 
WHERE IS_DEFINED(c.profile.contact)

Handling Missing Properties

Cases where certain nested properties don't exist need to be handled gracefully. This query accesses a property that may not be present in all documents. It returns the document with the phone property omitted from results when it doesn't exist.

SELECT c.id, c.profile.contact.phone 
FROM c

Code sample

A Python example demonstrating these subdocument query scenarios above is available in this GitHub Gist: cosmosdb_subdocument_examples.py

To run the example, start the Azure Cosmos DB Emulator:

docker run -p 8081:8081 -p 8080:8080 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol http

Download and run the script from the gist – it automatically sets up the database, loads the sample data, and runs each query scenario:

python cosmosdb_subdocument_examples.py

OpenTelemetry for Observability

OpenTelemetry is an open-source observability framework that provides a collection of tools, APIs, and SDKs for instrumenting, generating, collecting, and exporting telemetry data.

To activate OpenTelemetry in the Azure Cosmos DB Emulator, set the "--enable-otlp" flag to "true" (or ENABLE_OTLP_EXPORTER environment variable) when starting the Docker container. For example:

docker run -p 8081:8081 -p 8080:8080 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol http --enable-otlp true

You can also use the "--enable-console" flag (or use the ENABLE_CONSOLE_EXPORTER environment variable) to enable console output of telemetry data that can be useful for debugging purposes.

Use Docker Compose to simplify OpenTelemetry setup with the Azure Cosmos DB Emulator. The configuration below connects the emulator with Jaeger (distributed tracing) and Prometheus (metrics collection):

Copy and save the following in a docker-compose.yml file:

services:
  jaeger:
    image: jaegertracing/jaeger:latest
    container_name: jaeger
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"
    networks:
      - cosmosdb-network

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    networks:
      - cosmosdb-network
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--web.enable-otlp-receiver'
      - '--storage.tsdb.path=/prometheus'

  cosmosdb_emulator:
    image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
    container_name: cosmosdb_emulator
    ports:
      - "8081:8081"
      - "1234:1234"
      - "9712:9712"
      - "8889:8889"
    environment:
      - ENABLE_OTLP_EXPORTER=true
      - ENABLE_CONSOLE_EXPORTER=true
    networks:
      - cosmosdb-network

networks:
  cosmosdb-network:

Also, make sure to create a prometheus.yml file in the same directory as your docker-compose.yml with the following content – this will ensure that Prometheus can scrape metrics from the Azure Cosmos DB Emulator:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'cosmosdb-emulator-metrics'
    scrape_interval: 5s
    static_configs:
      - targets: ['cosmosdb_emulator:8889']

If the emulator is already running, stop it first. Then start the entire stack (Azure Cosmos DB Emulator, Jaeger, and Prometheus) using Docker Compose:

docker-compose up -d

Wait for the services to start, and run the sample Python script from the previous sections (a few times) – this will generate some telemetry data.

Check the Jaeger UI at http://localhost:16686 to view distributed traces, search for specific operations, analyze request latency, and inspect the execution flow of your queries through the Azure Cosmos DB Emulator:

Check the Prometheus UI at http://localhost:9090 to query and visualize metrics, monitor request rates, track query performance statistics, and analyze resource utilization patterns from the Azure Cosmos DB Emulator.

For details, refer to the documentation

Health Probe

The emulator exposes health check endpoints on port "8080" that return a HTTP 200 OK response when all components (Gateway, Data Explorer, etc.) are fully operational.

This is particularly valuable for integration testing frameworks like Testcontainers, which provide waiting strategies to ensure containers are ready before tests run. Instead of using arbitrary sleep delays or log messages (which are unreliable since they may change), you can configure a waiting strategy that will check if the emulator Docker container is listening to the "8080" health check port.

Here's a Go example using testcontainers-go library:

func TestMain(m *testing.M) {
    req := testcontainers.ContainerRequest{
        Image:        emulatorImage,
        ExposedPorts: []string{"8081:8081", "8080:8080"},
        WaitingFor:   wait.ForListeningPort(nat.Port("8080")), // Wait for health check port
        // WaitingFor: wait.ForLog("PostgreSQL=OK, Gateway=OK, Explorer=OK, Ready=YES"), //this works but is less reliable, hence not recommended

    }

    _, err := testcontainers.GenericContainer(context.Background(), testcontainers.GenericContainerRequest{
        ContainerRequest: req,
        Started:          true,
    })

    if err != nil {
        log.Fatal(err)
    }

    // Create credential and client
    cred, err := azcosmos.NewKeyCredential(emulatorKey)
    if err != nil {
        log.Fatal(err)
    }

    client, err = azcosmos.NewClientWithKey(emulatorEndpoint, cred, nil)
    if err != nil {
        log.Fatal(err)
    }

    m.Run()
}

Available endpoints:

Endpoint	Purpose	Behavior
http://localhost:8080/alive	Liveness probe	Returns 503 if PostgreSQL and Gateway are unhealthy
http://localhost:8080/ready	Readiness probe	Returns 503 if any component is not operational (disabled components like Explorer are excluded)
http://localhost:8080/status	Status information	Always returns 200 with detailed JSON status for all components

Conclusion

The latest Azure Cosmos DB Emulator release eliminates key query limitations and adds observability features, enabling you to develop and test more complex scenarios locally. You can now implement advanced data access patterns with nested JOINs, leverage operator support for string and array manipulation, and monitor your application's behavior with OpenTelemetry. You can start using these capabilities to accelerate your development workflow and catch issues earlier in your development cycle.

DocumentDB goes cloud-native: Introducing the DocumentDB Kubernetes Operator

Abhishek Gupta — Mon, 10 Nov 2025 08:49:43 +0000

Announced and published on https://opensource.microsoft.com/blog/2025/11/05/documentdb-goes-cloud-native-introducing-the-documentdb-kubernetes-operator

Today, we're excited to announce the DocumentDB Kubernetes Operator, an open-source, cloud-native solution to deploy, manage, and scale DocumentDB instances on Kubernetes. DocumentDB is a MongoDB-compatible, open-source document database built on PostgreSQL. The DocumentDB Kubernetes Operator represents a natural evolution of the DocumentDB ecosystem, following our open source announcement and recent joining of the Linux Foundation.

When it comes to distributed databases, there is no one-size-fits-all solution. Database-as-a-Service (DBaaS) options may not always meet customers' data sovereignty or portability needs. On the other hand, managing database clusters manually is complex and resource intensive. What’s needed is a balanced approach that automates routine tasks like updates and backups, while simplifying operations such as scaling, failover, and recovery. This is precisely where Kubernetes excels—bridging automation with operational simplicity.

However, unlike stateless applications that can be easily scaled and replaced, running stateful workloads in Kubernetes has always posed unique challenges.

The DocumentDB Kubernetes Operator addresses these by using the operator pattern to extend Kubernetes, making it possible to manage DocumentDB clusters as native Kubernetes resources.

This approach creates a clear separation of responsibilities:

The database platform team can focus solely on system health.
App developers enjoy a DBaaS-like experience, without the need to build custom automation between container orchestration and database operations.
The operator handles the complexity of PostgreSQL cluster orchestration, MongoDB protocol translation, and other critical operations.
Application development teams can integrate services using MongoDB-compatible drivers and tools, thereby simplifying the process of migrating existing workloads to DocumentDB, or building new cloud-native applications.

DocumentDB operator architecture overview

To understand how this works, let’s take a look under the hood, to explore the key components and architecture that make this seamless Kubernetes integration possible.

A DocumentDB cluster deployed on Kubernetes consists of multiple DocumentDB instances that are orchestrated by the operator. A DocumentDB instance consists of the following core components that run inside a Kubernetes Pod:

PostgreSQL with DocumentDB Extension: This is the core database engine enhanced with document storage and querying capabilities.It is deployed in customer application namespaces on Kubernetes worker nodes.
Gateway Container: A protocol translator that runs as a sidecar container, converting MongoDB wire protocol requests into PostgreSQL DocumentDB extension calls.

By default, the DocumentDB instance is accessible within the cluster. If configured, the operator creates a Kubernetes Service for external client applications to connect to the DocumentDB cluster (via the Gateway) using any MongoDB-compatible client or tooling.

CloudNative-PG operator for PostgreSQL orchestration

The DocumentDB operator uses the CloudNative-PG (CNPG) operator for PostgreSQL cluster management. CNPG is a Cloud Native Computing Foundation (CNCF) Sandbox project that provides an open-source Kubernetes operator for managing PostgreSQL workloads. The CNPG operator runs in the cnpg-system namespace on Kubernetes worker nodes. Behind the scenes, the DocumentDB operator creates the required CNPG resources to manage the lifecycle of PostgreSQL instances with the DocumentDB extension.

The operator also includes a CNPG Sidecar Injector component, which is an admission webhook that automatically injects the DocumentDB Gateway container into PostgreSQL pods during deployment. Thanks to the extensibility of CNPG, the DocumentDB gateway container is implemented as a CloudNativePG Interface (CNPG-I) plugin.

DocumentDB is addressing a real need as an open-source, document-oriented NoSQL database built on PostgreSQL. By offering MongoDB API compatibility without vendor lock-in, it tackles a long-standing challenge for developers. We are thrilled to see the DocumentDB Kubernetes Operator joining the Linux Foundation, and proud that under the hood, it's powered by CloudNativePG, a CNCF Sandbox project. The future of PostgreSQL on Kubernetes just got even brighter!

Gabriele Bartolini, Vice President, EDB

Getting started with DocumentDB Kubernetes Operator

Ready to try it out? Getting started with the operator is straightforward. You can use a local Kubernetes cluster such as minikube or kind and use Helm for installation.

First, execute the commands below to install cert-manager to manage TLS certificates for the DocumentDB cluster:

helm repo add jetstack https://charts.jetstack.io

helm repo update

helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set installCRDs=true

Next, install the DocumentDB operator using the Helm chart:

helm install documentdb-operator oci://ghcr.io/microsoft/documentdb-operator --namespace documentdb-operator --create-namespace

This will install the latest version of the operator. To specify a version, use -- version.

Wait for the operator to start. Run this command to verify its status:

kubectl get pods -n documentdb-operator

You should see an output like this:

NAME                                 READY   STATUS    RESTARTS  AGE

documentdb-operator-65d6b97878-ns5wk 1/1     Running   0         1m

Now, create a Kubernetes Secret to store the DocumentDB credentials. This should have your desired administrator username and password (make sure to note them down):

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Namespace
metadata:
  name: documentdb-preview-ns
---
apiVersion: v1
kind: Secret
metadata:
  name: documentdb-credentials
  namespace: documentdb-preview-ns
type: Opaque
stringData:
  username: k8s_secret_user
  password: DemoPwd
EOF

With the credentials in place, create a single-node DocumentDB cluster:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Namespace
metadata:
  name: documentdb-preview-ns
---
apiVersion: db.microsoft.com/preview
kind: DocumentDB
metadata:
  name: documentdb-preview
  namespace: documentdb-preview-ns
spec:
  nodeCount: 1
  instancesPerNode: 1
  documentDbCredentialSecret: documentdb-credentials
  resource:
    storage:
      pvcSize: 10Gi
  exposeViaService:
    serviceType: ClusterIP
EOF

Wait for the DocumentDB cluster to be fully initialized, and run this command to verify that it is running:

kubectl get pods -n documentdb-preview-ns

You should see an output like this:

NAME                   READY   STATUS    RESTARTS   AGE

documentdb-preview-1   2/2     Running   0          1m

Once the cluster is running, you can connect to the DocumentDB instance directly through the Gateway port 10260. For both minikube and kind, this can be easily done using port forwarding:

kubectl port-forward pod/documentdb-preview-1 10260:10260 -n documentdb-preview-ns

With port forwarding active, you can now connect using any MongoDB client or tool. For example, from a different terminal, try connecting with mongosh (MongoDB shell):

mongosh 127.0.0.1:10260 -u k8s_secret_user -p DemoPwd --authenticationMechanism SCRAM-SHA-256 --tls --tlsAllowInvalidCertificates

Join us in our mission to advance the open-source document database ecosystem!

The DocumentDB Kubernetes Operator represents an important milestone in our broader mission and our commitment to vendor-neutral, community-driven development that puts developer needs first.

We invite you to join the community and help shape the future of cloud-native document databases.

Get started by exploring the GitHub repository, documentation, or participate in discussions on our Discord community. As the project continues to evolve under Linux Foundation governance, you can expect to see contributions that expand functionality and integrate with other Kubernetes and CNCF projects.

Build a RAG application with LangChain and Local LLMs powered by Ollama

Abhishek Gupta — Fri, 22 Aug 2025 14:12:59 +0000

Local large language models (LLMs) provide significant advantages for developers and organizations. Key benefits include enhanced data privacy, as sensitive information remains entirely within your own infrastructure, and offline functionality, enabling uninterrupted work even without internet access. While cloud-based LLM services are convenient, running models locally gives you full control over model behavior, performance tuning, and potential cost savings. This make them ideal for experimentation before running production workloads.

The ecosystem for local LLMs has matured significantly, with several excellent options available, such as Ollama, Foundry Local, Docker Model Runner, and more. Most popular AI/Agent frameworks including LangChain and LangGraph provide integration with these local model runners, making it easier to integrate them into your projects.

What will you learn?

This blog post will illustrate how to use local LLMs with Azure Cosmos DB as a vector database for retrieval-augmented generation (RAG) scenarios. It will guide you through setting up a local LLM solution, configuring Azure Cosmos DB, loading data, performing vector searches, and executing RAG queries. You can either use the Azure Cosmos DB emulator for local development or connecting to an Azure Cosmos DB account in the cloud. You will be using Ollama (open-source solution) to run LLMs locally on your own machine. It lets you download, run, and interact with a variety of LLMs (like Llama 3, Mistral, and others) using simple commands, without needing cloud access or complex setup.

By the end of this blog post, you will have a working local RAG setup that leverages Ollama and Azure Cosmos DB. the sample app uses LangChain integration with Azure Cosmos DB to perform embedding, data loading, and vector search. You can easily adapt it to other frameworks like LlamaIndex.

Alright, lets dive in!

Setup Ollama

To get started with Ollama, follow the official installation guide on GitHub to install it on your system. The installation process is straightforward across different platforms. For example, on Linux systems, you can install Ollama with a single command:

curl -fsSL https://ollama.com/install.sh | sh

Once installed, start the Ollama service by running:

ollama serve

This blog post demonstrates the integration using two specific models from the Ollama library:

mxbai-embed-large - A high-quality embedding model with 1024 dimensions, ideal for generating vector representations of text
llama3 - The 8B parameter variant of Meta's Llama 3, which serves as our chat model for the RAG pipeline

Download both models using the following commands. Note that this process may take several minutes depending on your internet connection speed, as these are substantial model files:

ollama pull mxbai-embed-large
ollama pull llama3:8b

Something to keep in mind ...

While tools like Ollama make it straightforward to run local LLMs, hardware requirements depend on the specific model and your performance expectations. Lightweight models (such as Llama 2 7B or Phi-2) can run on modern CPUs with as little as 8 GB RAM, though performance may be limited. Larger models (like Llama 3 70B or Mixtral) typically require a dedicated GPU with at least 16 GB VRAM for efficient inference.

Ollama supports both CPU and GPU execution. On CPU-only systems, you can expect slower response times, especially with larger models or concurrent requests. Using a compatible GPU significantly accelerates inference required for demanding workloads.

Setup Azure Cosmos DB

Since you're working with local models, you'll likely want to use the Azure Cosmos DB emulator for local development. The emulator provides a local environment that mimics the Azure Cosmos DB service, enabling you to develop and test your applications without incurring costs or requiring an internet connection.

Alternatively, you can use the cloud-based Azure Cosmos DB service. Simply create an Azure Cosmos DB for NoSQL account and enable the vector search feature. Make sure to log in using az cli with an identity that has RBAC permissions for the account, since the application uses DefaultAzureCredential for authentication (not key-based authentication).

The emulator is available as a Docker container, which is the recommended way to run it. Here are the steps to pull and start the Cosmos DB emulator. The commands shown are for Linux - refer to the documentation for other platform options.

If you don't have Docker installed, please refer to the Docker installation guide.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

docker run --publish 8081:8081 -e AZURE_COSMOS_EMULATOR_PARTITION_COUNT=1 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Next, configure the emulator SSL certificate. For example, on the Linux system I was using, I ran the following commands to download the certificate and regenerate the certificate bundle:

curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt
sudo update-ca-certificates

You should see output similar to this:

Updating certificates in /etc/ssl/certs...
rehash: warning: skipping ca-certificates.crt,it does not contain exactly one certificate or CRL
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

Load data into Azure Cosmos DB

Now that both Ollama and Azure Cosmos DB are set up, it's time to populate our vector database with some sample data. For this demonstration, we'll use Azure Cosmos DB's own documentation as our data source. The loader will fetch markdown content directly from the Microsoft Docs repository, specifically focusing on articles about Azure Cosmos DB vector search functionality.

Our data loading process will read these documentation articles, generate embeddings using the mxbai-embed-large model, and store both the content and vector representations in Azure Cosmos DB for retrieval.

Begin by cloning the GitHub repository containing the sample application:

git clone https://github.com/abhirockzz/local-llms-rag-cosmosdb
cd local-llms-rag-cosmosdb

Before running the loader application, ensure you have Python 3 installed on your system. Create a virtual environment and install the required dependencies:

python3 -m venv .venv
source .venv/bin/activate

pip3 install -r requirements.txt

Next, configure the environment variables and execute the loading script. The example below uses the Azure Cosmos DB emulator for local development. If you prefer to use the cloud service instead, simply set the COSMOS_DB_URL variable to your Azure Cosmos DB account URL and remove the USE_EMULATOR variable.

# export COSMOS_DB_URL="https://<Cosmos DB account name>.documents.azure.com:443/"
export USE_EMULATOR="true"
export DATABASE_NAME="rag_local_llm_db"
export CONTAINER_NAME="docs"
export EMBEDDINGS_MODEL="mxbai-embed-large"
export DIMENSIONS="1024"

python3 load_data.py

The script will automatically create the database and container if they don't already exist. Once the data loading process completes successfully, you should see output similar to this:

Uploading documents to Azure Cosmos DB ['https://raw.githubusercontent.com/MicrosoftDocs/azure-databases-docs/refs/heads/main/articles/cosmos-db/nosql/vector-search.md', 'https://raw.githubusercontent.com/MicrosoftDocs/azure-databases-docs/refs/heads/main/articles/cosmos-db/nosql/multi-tenancy-vector-search.md']
Using database: rag_local_llm_db, container: docs
Using embedding model: mxbai-embed-large with dimensions: 1024
Created instance of AzureCosmosDBNoSqlVectorSearch
Loading 26 document chunks from 2 documents
Data loaded into Azure Cosmos DB

To confirm that your data has been loaded successfully, you can inspect the results using the Azure Cosmos DB Data Explorer. If you're using the emulator, navigate to https://localhost:8081/_explorer/index.html in your browser. You should see the same number of documents in your container as the number of chunks reported by the loader application.

Run vector search queries

Now that your data is loaded, let's test the vector search functionality. Set the same environment variables used for data loading and run the vector search script with your desired query:

# export COSMOS_DB_URL="https://<Cosmos DB account name>.documents.azure.com:443/"
export USE_EMULATOR="true"
export DATABASE_NAME="rag_local_llm_db"
export CONTAINER_NAME="docs"
export EMBEDDINGS_MODEL="mxbai-embed-large"
export DIMENSIONS="1024"

python3 vector_search.py "show me an example of a vector embedding policy"

The script will process your query through the embedding model and perform a similarity search against the stored document vectors. You should see output similar to the following:

Searching top 5 results for query: "show me an example of a vector embedding policy"

Using database: rag_local_llm_db, container: docs
Using embedding model: mxbai-embed-large with dimensions: 1024
Created instance of AzureCosmosDBNoSqlVectorSearch
Score: 0.7437641827298191
Content: ```



### A policy with two vector paths
//....

The output shows the top five results ordered by their similarity scores, with higher scores indicating better matches to your query.

To modify the number of results returned, you can add the top_k argument. For example, to retrieve the top 10 results, run: python3 vector_search.py "show me an example of a vector embedding policy" 10

Execute Retrieval-Augmented Generation (RAG) queries

Now we will put it all together with an simple chat based interface that leverages the llama3 model to generate responses based on the contextual information retrieved from Azure Cosmos DB.

Configure the environment variables needed for the RAG application and launch the script:


bash
# export COSMOS_DB_URL="https://<Cosmos DB account name>.documents.azure.com:443/"
export USE_EMULATOR="true"
export DATABASE_NAME="rag_local_llm_db"
export CONTAINER_NAME="docs"
export EMBEDDINGS_MODEL="mxbai-embed-large"
export DIMENSIONS="1024"
export CHAT_MODEL="llama3"

python3 rag_chain.py

Once the application initializes, you'll see output confirming the RAG chain setup:


text
Building RAG chain. Using model: llama3
Using database: rag_local_llm_db, container: docs
Using embedding model: mxbai-embed-large with dimensions: 1024
Created instance of AzureCosmosDBNoSqlVectorSearch
Enter your questions below. Type 'exit' to quit, 'clear' to clear chat history, 'history' to view chat history.
[User]:

Ask questions about the Azure Cosmos DB vector search documentation that you've loaded. For instance, try asking show me an example of a vector embedding policy, and you'll see a response like this (note that these may vary slightly for your case, even across different runs):


text
//...
[User]: show me an example of a vector embedding policy
[Assistant]: Here is an example of a vector embedding policy:

{
    "vectorEmbeddings": [
        {
            "path":"/vector1",
            "dataType":"float32",
            "distanceFunction":"cosine",
            "dimensions":1536
        },
        {
            "path":"/vector2",
            "dataType":"int8",
            "distanceFunction":"dotproduct",
            "dimensions":100
        }
    ]
}

This policy defines two vector embeddings: one with the path `/vector1`, using `float32` data type, cosine distance function, and having 1536 dimensions; and another with the path `/vector2`, using `int8` data type, dot product distance function, and having 100 dimensions.

To further explore the capabilities of your RAG system, try these additional example queries:

"What is the maximum supported dimension for vector embeddings in Azure Cosmos DB?"
"Is it suitable for large scale data?"
"Is there a benefit to using the flat index type?"

You can enter 'exit' to quit the application, 'clear' to clear chat history, or 'history' to view your previous interactions. Feel free to experiment with different data sources and queries. To modify the number of vector search results used as context, you can add the TOP_K environment variable (defaults to 5).

Wrap up

In this walkthrough, you followed step-by-step instructions to set up a complete RAG application that runs entirely on your local infrastructure — from installing and configuring Ollama with embedding and chat models, to setting up Azure Cosmos DB for vector storage, loading documentation data, and running using RAG through an interactive chat interface.

Running models locally brings clear advantages in terms of costs, data privacy, and connectivity constraints. However, you need to plan for appropriate hardware, particularly for larger models that perform best with dedicated GPUs and sufficient memory. The trade-off between model size, performance, and resource requirements is crucial when planning your local AI setup.

Have you experimented with local LLMs in your projects? What challenges or benefits have you encountered when moving from cloud-based to local AI solutions? Perhaps you have used both approaches? Share your experience and feedback!

Integration testing for Go applications using Testcontainers and containerized databases

Abhishek Gupta — Thu, 24 Jul 2025 05:43:01 +0000

Integration testing has always presented a fundamental challenge: how do you test your application against real dependencies without the complexity of managing external services? Traditional approaches often involve either mocking dependencies (which can miss integration issues) or maintaining separate test environments (which can be expensive and difficult to manage consistently).

Hello Testcontainers!

Testcontainers solves this problem elegantly by providing a way to run lightweight, throwaway instances of databases, message brokers, web servers, and other services directly within your test suite. Instead of complex setup scripts or shared test environments, you can spin up real services in Docker containers that exist only for the duration of your tests. The core value proposition is compelling: write tests that run against the actual technologies your application uses in production, while maintaining the isolation and repeatability that good tests require. When your tests complete, the containers are automatically cleaned up, leaving no trace behind.

Testcontainers for Go (testcontainers-go package) brings this powerful testing approach to the Go ecosystem. It provides a clean, idiomatic Go API for creating and managing Docker containers within your test suite, handling the lifecycle management, port mapping, and health checks automatically.

What you'll learn

This post walks through a practical example of using testcontainers-go with the Azure Cosmos DB emulator. Cosmos DB offers fully-featured Docker containers that mimic the behavior of the cloud service, making it an excellent candidate for integration testing with Testcontainers. Whether you're building applications that will eventually run against Azure Cosmos DB, or you're simply exploring document database patterns, the emulator provides a realistic testing environment without requiring cloud resources.

There are two flavors of the Cosmos DB emulator. In this example, I have used the Linux-based emulator (in preview) (which runs, almost anywhere, including ARM64 architecture). You are welcome to try out the other version as well.

We'll examine a simple application with a focus on how testcontainers handles the container setup, test execution, and cleanup. The app uses the Go SDK for Azure Cosmos DB (azcosmos package) and exposes a simple REST API that manages items in a Cosmos DB container:

POST /items - Creates a new item with name, description, and category
GET /items/{id}?category={category} - Retrieves an item by ID and category

Testcontainers and Cosmos DB emulator in action

Let's see testcontainers in action with a practical example. The tests demonstrate how testcontainers automatically spins up a Cosmos DB emulator container, runs our integration tests against it, and cleans up afterward. This gives us the confidence of testing against real database behavior without the complexity of managing external services.

Running the tests

Before we examine the code, let's run the tests to see testcontainers in action. Make sure you have Go installed and Docker running on your machine. If you don't have Docker installed, you can follow the instructions on the Docker website.

Pull the Cosmos DB emulator image from Docker Hub:

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

Next, clone the repository and run the tests. The test suite will automatically start the Cosmos DB emulator in a Docker container, run the integration tests, and then clean up the container afterward.

git clone github.com/abhirockzz/cosmosdb-testcontainers-go
cd cosmosdb-testcontainers-go

go test -v ./...

You should see the tests passing with output similar to this (some lines removed for brevity):

github.com/testcontainers/testcontainers-go - Connected to docker: 
  Server Version: 28.3.0
  API Version: 1.48
  Operating System: Docker Desktop
  Total Memory: 7836 MB
//.....
🐳 Creating container for image mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
🐳 Creating container for image testcontainers/ryuk:0.11.0
✅ Container created: 5e43ec4bd8ea
🐳 Starting container: 5e43ec4bd8ea
✅ Container started: 5e43ec4bd8ea
⏳ Waiting for container id 5e43ec4bd8ea image: testcontainers/ryuk:0.11.0. Waiting for: &{Port:8080/tcp timeout:<nil> PollInterval:100ms skipInternalCheck:false}
🔔 Container is ready: 5e43ec4bd8ea
✅ Container created: cb1d2abb7255
🐳 Starting container: cb1d2abb7255
✅ Container started: cb1d2abb7255
⏳ Waiting for container id cb1d2abb7255 image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview. Waiting for: &{Port:8081 timeout:<nil> PollInterval:100ms skipInternalCheck:false}
🔔 Container is ready: cb1d2abb7255
=== RUN   TestCreateItem
--- PASS: TestCreateItem (0.00s)
=== RUN   TestCreateItem_FailureScenarios
//.....
--- PASS: TestCreateItem_FailureScenarios (0.00s)
    --- PASS: TestCreateItem_FailureScenarios/missing_name (0.00s)
    --- PASS: TestCreateItem_FailureScenarios/missing_category (0.00s)
    --- PASS: TestCreateItem_FailureScenarios/invalid_JSON (0.00s)
    --- PASS: TestCreateItem_FailureScenarios/wrong_HTTP_method (0.00s)
=== RUN   TestGetItem
--- PASS: TestGetItem (0.00s)
=== RUN   TestGetItem_FailureScenarios
//....
--- PASS: TestGetItem_FailureScenarios (0.00s)
    --- PASS: TestGetItem_FailureScenarios/missing_item_ID (0.00s)
    --- PASS: TestGetItem_FailureScenarios/missing_category_parameter (0.00s)
    --- PASS: TestGetItem_FailureScenarios/empty_category_parameter (0.00s)
    --- PASS: TestGetItem_FailureScenarios/non-existent_item_ID (0.00s)
    --- PASS: TestGetItem_FailureScenarios/valid_item_ID_but_wrong_category (0.00s)
PASS
🐳 Stopping container: cb1d2abb7255
✅ Container stopped: cb1d2abb7255
🐳 Terminating container: cb1d2abb7255
🚫 Container terminated: cb1d2abb7255
ok      demo    9.194s

Understanding the test flow

The output shows how testcontainers orchestrates the entire process in three distinct phases:

Container Setup Phase: testcontainers connects to Docker, starts the Cosmos DB emulator and Ryuk containers, and waits until the emulator is ready for use.
Test Execution Phase: Integration tests run against the live Cosmos DB container, covering both successful operations and various error scenarios to ensure robust handling.
Cleanup Phase: All containers are automatically stopped and removed, ensuring the system is left clean with no lingering resources.

The combination of testcontainers and the Cosmos DB emulator gives you the reliability of testing against services without the operational overhead of managing test infrastructure. Every test run is isolated, repeatable, and starts from a known clean state. It gives you fast feedback while maintaining the confidence that comes from testing against actual database behavior.

Deep dive

Now let's examine how this works by walking through the code and exploring the key components that make this work.

Orchestrating the test environment

The TestMain function serves as the entry point for our test suite, providing a way to perform setup and teardown operations that span multiple test functions. Unlike individual test functions that run in isolation, TestMain runs once per package and gives you control over the entire test execution lifecycle.

func TestMain(m *testing.M) {
    // Set up the CosmosDB emulator container
    ctx := context.Background()

    var err error
    emulator, err = setupCosmosDBEmulator(ctx)
    if err != nil {
        fmt.Printf("Failed to set up CosmosDB emulator: %v\n", err)
        os.Exit(1)
    }

    // ... client setup and data seeding

    // Run the tests
    code := m.Run()

    // Cleanup
    if emulator != nil {
        _ = emulator.Terminate(ctx)
    }

    os.Exit(code)
}

This structure ensures that the expensive operation of starting a Docker container happens only once, while all individual tests can run against the same container instance. The pattern is particularly valuable when your setup involves external resources like databases or message brokers.

Setting up the Cosmos DB emulator

The setupCosmosDBEmulator function encapsulates the logic for creating and starting the Cosmos DB emulator:

func setupCosmosDBEmulator(ctx context.Context) (testcontainers.Container, error) {

    req := testcontainers.ContainerRequest{
        Image:        emulatorImage,
        ExposedPorts: []string{emulatorPort + ":8081"},
        WaitingFor:   wait.ForListeningPort(nat.Port(emulatorPort)),
        Env: map[string]string{
            "ENABLE_EXPLORER": "false",
            "PROTOCOL":        "https",
        },
    }

    container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
        ContainerRequest: req,
        Started:          true,
    })

    // Give the emulator a bit more time to fully initialize
    time.Sleep(5 * time.Second)

    return container, nil
}

The ContainerRequest struct defines everything testcontainers needs to know about our desired container. The ExposedPorts field maps the container's internal port 8081 to the same port on the host, while WaitingFor ensures testcontainers doesn't consider the container ready until the Cosmos DB service is actually listening on that port. The environment variables configure the emulator to run in HTTPS (PROTOCOL) mode without the web-based data explorer (ENABLE_EXPLORER is set to false). I encourage you to explore the documentation for more configuration options that might suit your testing needs.

Connecting to the emulator

The auth.GetEmulatorClientWithAzureADAuth function is part of the cosmosdb-go-sdk-helper package. It provides a convenient way to create a Cosmos DB client that uses Microsoft Entra AD authentication, which is the recommended approach for production applications. However, in this test setup, GetEmulatorClientWithAzureADAuth creates a Cosmos DB client configured specifically for the emulator environment. By passing the custom transport through the ClientOptions, we ensure that the SDK can successfully connect to the emulator despite its self-signed certificate.

transport := &http.Client{Transport: &http.Transport{
    TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
}}

options := &azcosmos.ClientOptions{ClientOptions: azcore.ClientOptions{
    Transport: transport,
}}

client, err = auth.GetEmulatorClientWithAzureADAuth(emulatorEndpoint, options)

Note that InsecureSkipVerify: true should only be used in test/dev environments.

Test execution and cleanup

After the container is ready and the client is configured, the code seeds test data through seedTestData() to provide known items for the tests to work with. m.Run() then executes all the actual test functions, returning an exit code that indicates whether the tests passed or failed.

Finally, the emulator.Terminate(ctx) call in the cleanup section ensures that testcontainers properly stops and removes the Docker container, regardless of the test results. This cleanup is essential for preventing resource leaks and ensuring that subsequent test runs start with a clean slate.

Conclusion

With the right tools, the complexity of integration testing can be tamed. Testcontainers bridges this gap by making it easier to test against containerised services while maintaining isolation, repeatability, and eliminating the need for shared infrastructure.

While this example focused on Azure Cosmos DB, the patterns apply broadly to any service that offers Docker containers, including PostgreSQL, Kafka, and more. Start with a single service and expand your test coverage gradually.

Although the Cosmos DB emulator is a powerful tool for local development and testing, but it does not support every feature available in the full Azure Cosmos DB service. You can can read on the Differences between the emulator and cloud service, or consult the documentation to understand the subset of features that are supported in the emulator.

The full example code is available in the GitHub repository, and the testcontainers-go documentation provides comprehensive guidance for exploring more. Happy building!

Building resilient Go applications: Simple tip for mocking and testing database error responses

Abhishek Gupta — Sun, 06 Jul 2025 05:51:30 +0000

When building applications that rely on databases (which is almost every application, right?), one of the biggest challenges developers face is testing how their code handles various error scenarios. What happens when the database returns a HTTP 400 error? How does your application respond to throttling? Will your retry logic work as expected?

These questions are crucial because in production, errors are inevitable. This holds true for Azure Cosmos DB as well. The database's distributed nature means that errors can arise from various sources, including network issues (503 Service Unavailable), request timeouts (408 Request timeout), rate limits (429 Too many requests), and more. Therefore, robust error handling and testing are essential to maintain a reliable application that handles these gracefully rather than crashing or losing data.

Testing edge cases and different permutations of error scenarios traditionally requires a lot of effort and can be quite complex. Common approaches include:

Triggering real errors in your development environment (unreliable and hard to reproduce)
Mocking entire SDK responses (complex and may not reflect real behavior)
Waiting for errors to happen in production (definitely not ideal!)

This is where error simulation can come in handy. By intercepting HTTP requests and selectively returning error responses, we can test specific scenarios in a controlled, repeatable manner.

Simulating errors using pluggable mechanisms

There are multiple ways to test error scenarios – from integration testing with real services to comprehensive mocking frameworks. This particular example uses the Go SDK for Azure Cosmos DB to illustrate how to simulate HTTP error conditions (403 Forbidden) for a specific operation (such as ReadItem). Note that this is just one technique in a broader toolkit of testing strategies.

Follow the next steps if you want to run this as a standalone Go application and see how it works in practice. Or, feel free to skip to the next section for a walkthrough.

Step 1: Copy the code below into a file named main.go:

package main

import (
    "context"
    "errors"
    "fmt"
    "io"
    "net/http"
    "strings"

    "github.com/Azure/azure-sdk-for-go/sdk/azcore"
    azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
    "github.com/Azure/azure-sdk-for-go/sdk/azcore/policy"
    azruntime "github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
)

func init() {
    azlog.SetListener(func(cls azlog.Event, msg string) {

        // Log retry-related events
        switch cls {
        case azlog.EventRetryPolicy:
            fmt.Printf("Retry Policy Event: %s\n", msg)

        }
    })

    // Set logging level to include retries
    azlog.SetEvents(azlog.EventRetryPolicy)

}

// CustomTransport403Error implements policy.Transporter to simulate 403 errors only for ReadItem operations
type CustomTransport403Error struct{}

func (t *CustomTransport403Error) Do(req *http.Request) (*http.Response, error) {

    // Check if this is a ReadItem operation (typically a GET request with an item id in the path)
    // ReadItem URLs look like: /dbs/{db}/colls/{container}/docs/{id}
    isReadItemOperation := req.Method == "GET" && strings.Contains(req.URL.Path, "/docs/")

    if isReadItemOperation {
        fmt.Printf("CustomTransport403Error: Simulating 403 error for ReadItem operation: %s\n", req.URL.String())

        // Create a simulated 403 response with sub-status 3
        header := make(http.Header)
        header.Set("x-ms-substatus", "3")
        header.Set("x-ms-activity-id", "readitem-test-activity-id")
        header.Set("x-ms-request-id", "readitem-test-request-id")
        header.Set("Content-Type", "application/json")

        response := &http.Response{
            StatusCode: 403,
            Status:     "403 Forbidden",
            Header:     header,
            Body:       io.NopCloser(strings.NewReader(`{"code": "Forbidden", "message": "Simulated 403 error for ReadItem with sub-status 3"}`)),
            Request:    req,
        }

        // Return both the response and the error so the SDK can handle it properly
        responseErr := azruntime.NewResponseError(response)
        return response, responseErr
    }

    // For all other operations (like account properties), use a fake successful response
    fmt.Printf("CustomTransport403Error: Allowing operation: %s %s\n", req.Method, req.URL.String())

    // Create a fake successful response for account properties and other operations
    header := make(http.Header)
    header.Set("Content-Type", "application/json")
    header.Set("x-ms-activity-id", "success-activity-id")
    header.Set("x-ms-request-id", "success-request-id")

    response := &http.Response{
        StatusCode: 200,
        Status:     "200 OK",
        Header:     header,
        Body:       io.NopCloser(strings.NewReader("")),
        Request:    req,
    }

    return response, nil
}

// RetryLoggingPolicy logs error details during retries
type RetryLoggingPolicy struct{}

func (p *RetryLoggingPolicy) Do(req *policy.Request) (*http.Response, error) {
    // fmt.Println("RetryLoggingPolicy: Starting retry with request URL:", req.Raw().URL.String())

    // Call the next policy in the chain
    resp, err := req.Next()

    // If there's an error, log the details
    if err != nil {
        var azErr *azcore.ResponseError
        if errors.As(err, &azErr) {
            subStatus := azErr.RawResponse.Header.Get("x-ms-substatus")
            if subStatus == "" {
                subStatus = "N/A"
            }

            fmt.Printf("RetryLoggingPolicy: ResponseError during retry - Status: %d, SubStatus: %s, URL: %s\n",
                azErr.StatusCode, subStatus, req.Raw().URL.String())
        } else {
            fmt.Printf("RetryLoggingPolicy: Non-ResponseError during retry - %T: %v, URL: %s\n",
                err, err, req.Raw().URL.String())
        }
    } else if resp != nil && resp.StatusCode >= 400 {
        // Log HTTP error responses even if they don't result in Go errors
        subStatus := resp.Header.Get("x-ms-substatus")
        if subStatus == "" {
            subStatus = "N/A"
        }

        fmt.Printf("RetryLoggingPolicy: HTTP error response - Status: %d, SubStatus: %s, URL: %s\n",
            resp.StatusCode, subStatus, req.Raw().URL.String())
    }

    return resp, err
}

func main() {

    opts := &azcosmos.ClientOptions{
        ClientOptions: azcore.ClientOptions{
            PerRetryPolicies: []policy.Policy{
                &RetryLoggingPolicy{}, // This will log error details during retries
            },
            Transport: &CustomTransport403Error{}, // Use the selective transport to simulate 403 errors only for ReadItem
        },
    }

    creds, _ := azidentity.NewDefaultAzureCredential(nil)
    client, err := azcosmos.NewClient("https://i_dont_exist.documents.azure.com:443", creds, opts)
    if err != nil {
        fmt.Printf("NewClient Error occurred: %v\n", err)
        return
    }

    // Test the ReadItem operation
    container, err := client.NewContainer("dummy", "dummy")
    if err != nil {
        fmt.Printf("NewContainer Error occurred: %v\n", err)
        return
    }
    partitionKey := azcosmos.NewPartitionKeyString("testpk")

    _, err = container.ReadItem(context.Background(), partitionKey, "testid", nil)
    handlerError(err)

}

func handlerError(err error) {
    if err != nil {
        fmt.Println("ReadItem Error occurred")

        // Debug: Print the actual error type
        fmt.Printf("Error type: %T\n", err)
        // fmt.Printf("Error value: %v\n", err)

        var azErr *azcore.ResponseError

        if errors.As(err, &azErr) {
            fmt.Println("Successfully unwrapped to azcore.ResponseError using errors.As")
            fmt.Printf("error status code: %d\n", azErr.StatusCode)

            subStatus := azErr.RawResponse.Header.Get("x-ms-substatus")
            if subStatus == "" {
                subStatus = "N/A"
            }
            fmt.Printf("error sub-status code: %s\n", subStatus)
        }
    }
}

Step 2: Use the following commands to run the application:

go mod init demo
go mod tidy

go run main.go

Lets break this down and understand how it works.

1. Custom transport layer for injecting errors

CustomTransport403Error is a custom HTTP transport that intercepts requests before they reach Azure Cosmos DB. This transport examines each request and decides whether to simulate an error based on the operation type (e.g., ReadItem). If the request matches the criteria, it returns a simulated error response; otherwise, it allows the request to proceed normally.

It returns a 403 Forbidden HTTP response with a specific sub-status code (3 - WriteForbidden), and its wrapped in an azcore.ResponseError to closely mirror what Azure Cosmos DB would actually return. The x-ms-substatus header is particularly important for Cosmos DB applications, as it provides specific context about why an operation failed. It's included to make sure that error handling code processes responses exactly as it would in production.

You can customize the error simulation logic as needed.

type CustomTransport403Error struct{}

func (t *CustomTransport403Error) Do(req *http.Request) (*http.Response, error) {

    isReadItemOperation := req.Method == "GET" && strings.Contains(req.URL.Path, "/docs/")

    if isReadItemOperation {
        fmt.Printf("CustomTransport403Error: Simulating 403 error for ReadItem operation: %s\n", req.URL.String())

        // Create a simulated 403 response with sub-status 3
        header := make(http.Header)
        header.Set("x-ms-substatus", "3")
        header.Set("x-ms-activity-id", "readitem-test-activity-id")
        header.Set("x-ms-request-id", "readitem-test-request-id")
        header.Set("Content-Type", "application/json")

        response := &http.Response{
            StatusCode: 403,
            Status:     "403 Forbidden",
            Header:     header,
            Body:       io.NopCloser(strings.NewReader(`{"code": "Forbidden", "message": "Simulated 403 error for ReadItem with sub-status 3"}`)),
            Request:    req,
        }

        // Return both the response and the error so the SDK can handle it properly
        responseErr := azruntime.NewResponseError(response)
        return response, responseErr
    }

    // For all other operations, return a successful response
    // ... (successful response creation code)
}

The Go SDK for Azure Cosmos DB retries requests that return certain error codes, such as 403 (Forbidden), and others. This custom transport allows you to simulate these conditions without needing to actually hit the database.

2. Observing SDK retries using custom policies

I covered Retry Policies in a previous blog post – How to configure and customize the Go SDK for Azure Cosmos DB.

In this example, a custom policy is used to provide visibility into the retry behavior. It logs detailed information about each retry attempt:

type RetryLoggingPolicy struct{}

func (p *RetryLoggingPolicy) Do(req *policy.Request) (*http.Response, error) {
    // Call the next policy in the chain
    resp, err := req.Next()

    // If there's an error, log the details
    if err != nil {
        var azErr *azcore.ResponseError
        if errors.As(err, &azErr) {
            subStatus := azErr.RawResponse.Header.Get("x-ms-substatus")
            if subStatus == "" {
                subStatus = "N/A"
            }

            fmt.Printf("RetryLoggingPolicy: ResponseError during retry - Status: %d, SubStatus: %s, URL: %s\n",
                azErr.StatusCode, subStatus, req.Raw().URL.String())
        }
    }

    return resp, err
}

This is really useful for understanding how your application behaves under error conditions. When applications encounter errors, the SDK automatically retries those requests. They might ultimately succeed after a few attempts, but you may want to have visibility into this process.

You can plug in a custom RetryLoggingPolicy to intercept these retries and log relevant information, such as the status code, sub-status code, and the URL of the request. This helps you understand how your application behaves during error conditions.

3. Integration and error handling verification

The main function ties everything together. It sets up the Cosmos DB client with the custom transport and retry policy, then performs a ReadItem operation. If an error occurs, it uses the handlerError function to extract and log the status code and sub-status code from the error response.

The custom transport and retry policy are integrated into the application as part of ClientOptions.

The custom transport is configured as the Transporter which represents an HTTP pipeline transport used to send HTTP requests and receive responses.
The retry policy is added to the PerRetryPolicies list. Each policy is executed once per request, and for each retry of that request.

func main() {
    opts := &azcosmos.ClientOptions{
        ClientOptions: azcore.ClientOptions{
            PerRetryPolicies: []policy.Policy{
                &RetryLoggingPolicy{}, // This will log error details during retries
            },
            Transport: &CustomTransport403Error{}, // Use the custom transport
        },
    }

    // ... client creation and ReadItem operation ...

    _, err = container.ReadItem(context.Background(), partitionKey, "testid", nil)
    handlerError(err)
}

func handlerError(err error) {
    if err != nil {
        var azErr *azcore.ResponseError
        if errors.As(err, &azErr) {
            fmt.Printf("error status code: %d\n", azErr.StatusCode)

            subStatus := azErr.RawResponse.Header.Get("x-ms-substatus")
            if subStatus == "" {
                subStatus = "N/A"
            }
            fmt.Printf("error sub-status code: %s\n", subStatus)
        }
    }
}

Conclusion

By making error scenarios easy to reproduce and test, you're more likely to build applications that handle them gracefully. This pattern can be extended to test various scenarios such as different HTTP status codes (429 for throttling, for example), network timeouts, intermittent failures that succeed after retries, circuit breaker patterns, fallback mechanisms, and more.

To begin with, you can focus on combination specific operations (like read, or write) and error types that are most relevant to your application. You can gradually expand this to cover more complex scenarios, such as simulating throttling, server errors, or even network timeouts.