Skill v1.0.1
currentAutomated scan100/100+14 new
name: azure-cosmos-db-py description: "Build production-grade Azure Cosmos DB NoSQL services following clean code, security best practices, and TDD principles." risk: critical source: community date_added: "2026-02-27" metadata: version: "1.0.1"
Bundled upstream support
Supporting files are included at skill-relative paths. See UPSTREAM-NOTICE.md for their pinned sources, licenses, hashes, and import changes.
Restored helper safety
The integration fixture in assets/conftest_template.py connects to the configured Cosmos endpoint; cleanup_test_docs deletes records explicitly added to its tracking list. Use only an isolated disposable test container with test-only records, never production data. Copying the template does not connect to Cosmos.
Cosmos DB Service Implementation
Review corrections (2026-10-23): these snippets are incomplete application starters. Initialize the synchronous client during startup outside the event loop, serialize initialization and close client/credential on shutdown. A cached failed initialization needs an explicit bounded recovery path. azure.cosmos.aio is also available; the SDK is not synchronous-only. Enforce tenant authorization independently of partition routing; the bundled client assumes /workspaceId. Never accept caller SQL fragments. Distinguish unavailable storage (503) from not-found (404) and empty data; the older graceful-default examples below illustrate a policy to avoid for authoritative reads. Use ETag conditional writes to prevent lost updates, enforce uniqueness atomically, and implement cross-partition moves with conflict-aware compensation; read-then-upsert/delete is not atomic. No live Cosmos behavior is verified by these templates.
Build production-grade Azure Cosmos DB NoSQL services following clean code, security best practices, and TDD principles.
Installation
pip install azure-cosmos azure-identity
Environment Variables
COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/COSMOS_DATABASE_NAME=<database-name>COSMOS_CONTAINER_ID=<container-id># For emulator only (not production)COSMOS_KEY=<emulator-key>
Authentication
DefaultAzureCredential (preferred):
from azure.cosmos import CosmosClientfrom azure.identity import DefaultAzureCredentialclient = CosmosClient(url=os.environ["COSMOS_ENDPOINT"],credential=DefaultAzureCredential())
Emulator (local development):
from azure.cosmos import CosmosClientclient = CosmosClient(url="https://localhost:8081",credential=os.environ["COSMOS_KEY"],connection_verify=False)
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐│ FastAPI Router ││ - Auth dependencies (get_current_user, get_current_user_required)│ - HTTP error responses (HTTPException) │└──────────────────────────────┬──────────────────────────────────┘│┌──────────────────────────────▼──────────────────────────────────┐│ Service Layer ││ - Business logic and validation ││ - Document ↔ Model conversion ││ - Graceful degradation when Cosmos unavailable │└──────────────────────────────┬──────────────────────────────────┘│┌──────────────────────────────▼──────────────────────────────────┐│ Cosmos DB Client Module ││ - Singleton container initialization ││ - Dual auth: DefaultAzureCredential (Azure) / Key (emulator) ││ - Async wrapper via run_in_threadpool │└─────────────────────────────────────────────────────────────────┘
Quick Start
1. Client Module Setup
Create a singleton Cosmos client with dual authentication:
# db/cosmos.pyfrom azure.cosmos import CosmosClientfrom azure.identity import DefaultAzureCredentialfrom starlette.concurrency import run_in_threadpool_cosmos_container = Nonedef _is_emulator_endpoint(endpoint: str) -> bool:from urllib.parse import urlsplitparsed = urlsplit(endpoint)return (parsed.scheme == "https" and parsed.username is Noneand parsed.password is Noneand parsed.hostname in {"localhost", "127.0.0.1", "::1"})def get_container():global _cosmos_containerif _cosmos_container is None:if _is_emulator_endpoint(settings.cosmos_endpoint):client = CosmosClient(url=settings.cosmos_endpoint,credential=settings.cosmos_key,connection_verify=False)else:client = CosmosClient(url=settings.cosmos_endpoint,credential=DefaultAzureCredential())db = client.get_database_client(settings.cosmos_database_name)_cosmos_container = db.get_container_client(settings.cosmos_container_id)return _cosmos_container
Full implementation: See references/client-setup.md
2. Pydantic Model Hierarchy
Use five-tier model pattern for clean separation:
class ProjectBase(BaseModel): # Shared fieldsname: str = Field(..., min_length=1, max_length=200)class ProjectCreate(ProjectBase): # Creation requestworkspace_id: str = Field(..., alias="workspaceId")class ProjectUpdate(BaseModel): # Partial updates (all optional)name: Optional[str] = Field(None, min_length=1)class Project(ProjectBase): # API responseid: strcreated_at: datetime = Field(..., alias="createdAt")class ProjectInDB(Project): # Internal with docTypedoc_type: str = "project"
3. Service Layer Pattern
class ProjectService:def _use_cosmos(self) -> bool:return get_container() is not Noneasync def get_by_id(self, project_id: str, workspace_id: str) -> Project | None:if not self._use_cosmos():return Nonedoc = await get_document(project_id, partition_key=workspace_id)if doc is None:return Nonereturn self._doc_to_model(doc)
Full patterns: See references/service-layer.md
Core Principles
Security Requirements
- RBAC Authentication: Use
DefaultAzureCredentialin Azure — never store keys in code - Emulator-Only Keys: Hardcode the well-known emulator key only for local development
- Parameterized Queries: Always use
@parametersyntax — never string concatenation - Partition Key Validation: Validate partition key access matches user authorization
Clean Code Conventions
- Single Responsibility: Client module handles connection; services handle business logic
- Graceful Degradation: Services return
None/[]when Cosmos unavailable - Consistent Naming:
_doc_to_model(),_model_to_doc(),_use_cosmos() - Type Hints: Full typing on all public methods
- CamelCase Aliases: Use
Field(alias="camelCase")for JSON serialization
TDD Requirements
Write tests BEFORE implementation using these patterns:
@pytest.fixturedef mock_cosmos_container(mocker):container = mocker.MagicMock()mocker.patch("app.db.cosmos.get_container", return_value=container)return container@pytest.mark.asyncioasync def test_get_project_by_id_returns_project(mock_cosmos_container):# Arrangemock_cosmos_container.read_item.return_value = {"id": "123", "name": "Test"}# Actresult = await project_service.get_by_id("123", "workspace-1")# Assertassert result.id == "123"assert result.name == "Test"
Full testing guide: See references/testing.md
Reference Files
| File | When to Read | |
|---|---|---|
| references/client-setup.md | Setting up Cosmos client with dual auth, SSL config, singleton pattern | |
| references/service-layer.md | Implementing full service class with CRUD, conversions, graceful degradation | |
| references/testing.md | Writing pytest tests, mocking Cosmos, integration test setup | |
| references/partitioning.md | Choosing partition keys, cross-partition queries, move operations | |
| references/error-handling.md | Handling CosmosResourceNotFoundError, logging, HTTP error mapping |
Template Files
| File | Purpose | |
|---|---|---|
| assets/cosmos_client_template.py | Ready-to-use client module | |
| assets/service_template.py | Service class skeleton | |
| assets/conftest_template.py | pytest fixtures for Cosmos mocking |
Quality Attributes (NFRs)
Reliability
- Graceful degradation when Cosmos unavailable
- Retry logic with exponential backoff for transient failures
- Connection pooling via singleton pattern
Security
- Zero secrets in code (RBAC via DefaultAzureCredential)
- Parameterized queries prevent injection
- Partition routing does not authorize tenants; enforce membership/roles before accepting workspace IDs
Maintainability
- Five-tier model pattern enables schema evolution
- Service layer decouples business logic from storage
- Consistent patterns across all entity services
Testability
- Dependency injection via
get_container() - Easy mocking with module-level globals
- Clear separation enables unit testing without Cosmos
Performance
- Partition key queries avoid cross-partition scans
- Async wrapping prevents blocking FastAPI event loop
- Minimal document conversion overhead
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.