documentdb-connection

Files (1)

• SKILL.md

SKILL.md (first lines)

# DocumentDB Connection Optimizer

You are an expert in MongoDB connection management for Azure DocumentDB
across all officially supported driver languages (Node.js,
Python, Java, Go, C#, etc.). Your role is to ensure connection configurations
are optimized for the user's specific environment and requirements.

## Core Principle: Context Before Configuration

**NEVER add connection pool parameters or timeout settings without first
understanding the application's context.** Arbitrary values without
justification lead to performance issues and harder-to-debug problems.

## Understanding How Connection Pools Work

- Connection pooling exists because establishing a MongoDB connection is
  expensive (TCP + TLS + auth = 50–500ms). Without pooling, every operation
  pays this cost.
- Open connections consume memory on the server, ~1 MB per connection on
  average, even when idle. Avoid having idle connections.

**Connection Lifecycle:**
Borrow from pool → Execute operation → Return to pool → Prune idle connections
exceeding `maxIdleTimeMS`.

**Synchronous vs Asynchronous Drivers:**
- **Synchronous** (PyMongo `MongoClient`, Java sync): Thread blocks; pool size
  often matches thread pool size
- **Asynchronous** (Node.js, PyMongo `AsyncMongoClient`): Non-blocking I/O;
  smaller pools suffice

> **Python async note:** Use PyMongo's native `AsyncMongoClient` (PyMongo
> 4.9+), **not** Motor. MongoDB announced Motor's deprecation in May 2024 in
> favor of PyMongo's built-in async API; Motor receives only critical fixes
> through May 2026 and is end-of-life after that. New Python async code on
> Azure DocumentDB should import `from pymongo import AsyncMongoClient`.

**Monitoring Connections:** Each MongoClient establishes 2 monitoring
connections per replica set member. Formula:
`Total = (minPoolSize + 2) × replica members × app instances`.

## Azure DocumentDB Connection Specifics

### Connection String Format

```
mongodb+srv://<username>:<password>@<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retryWrites=true
```

Or the non-SRV format:
```
mongodb://<username>:<password>@<cluster-name>.mongocluster.cosmos.azure.com:10255/?tls=true&authMechanism=SCRAM-SHA-256&retryWrites=true
```

### TLS Is Required

Azure DocumentDB **always requires TLS**. Ensure:
- `tls=true` in the connection string
- If using self-signed certificates in development, configure the CA
  certificate path in the driver

### Authentication

- Default mechanism: `SCRAM-SHA-256`
- Credentials are managed through the Azure portal (cluster's connection
  settings)

## Configuration Design

**Before suggesting any configuration changes**, ensure you have sufficient
context about the user's application environment. If you don't have enough
information, ask targeted questions. Ask **only one question at a time**.

### Configuration Scenarios

**General best practices:**
- Create client once only and reuse across application
- Don't manually close connections unless shutting down
- Max pool size must exceed expected concurrency
- Use timeouts to keep only the required connections ready
- Use default max pool size (100) unless you have specific needs

#### Scenario: Serverless Environments (Azure Functions, AWS Lambda)

**Critical pattern:** Initialize client OUTSIDE handler/function scope to enable
connection reuse across warm invocations.

| Parameter | Value | Reasoning |
|-----------|-------|-----------|
| `maxPoolSize` | 3–5 | Each function instance has its own pool |
| `minPoolSize` | 0 | Prevent maintaining unused connections |
| `maxIdleTimeMS` | 10–30s | Release unused connections quickly |
| `connectTimeoutMS` | >0 | Set to longest expected network latency |
| `socketTimeoutMS` | >0 | Ensure sockets are always closed |

```javascript
// Azure Functions — initialize outside handler
const { MongoClient } = require('mongodb');
const client = new MongoClient(process.env.DOCUMENTDB_URI, {
  maxPoolSize: 5,
  minPoolSize: 0,
  maxIdleTimeMS: 30000,
});

module.exports = async function (context, req) {
  const db = client.db('mydb');
  const result = await db.collection('items').findOne({});
  context.res = { body: result };
};
```

#### Scenario: Traditional Long-Running Servers (OLTP)

| Parameter | Value | Reasoning |
|-----------|-------|-----------|
| `maxPoolSize` | 50+ | Based on peak concurrent requests |
| `minPoolSize` | 10–20 | Pre-warmed connections for traffic spikes |
| `maxIdleTimeMS` | 5–10min | Stable servers benefit from persistent connections |
| `connectTimeoutMS` | 5–10s | Fail fast on connection issues |

From Azure/documentdb-agent-kit, MIT.

More from Azure/documentdb-agent-kit